> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# shared_dimensions

> Defines cross-topic join keys that align the included topics.

Defines cross-topic join keys for the composite topic. A shared dimension handles the case where each topic has its own field for the same logical concept at a different path — for example, an order date in one topic and a campaign start date in another. The shared dimension becomes a single selectable field, and Omni joins each topic's subquery on its mapped field.

<Note>
  You don't need a shared dimension for a field that already lives in a [shared view](/modeling/composite-topics/parameters/shared-views) — the shared view's columns are usable as join keys directly.
</Note>

## Syntax

```yaml theme={null}
shared_dimensions:
  <dimension_name>:
    label: <string>
    description: <string>
    ai_context: <string>
    display_order: <integer>
    timeframes: [<timeframe>, ...]   # date/timestamp dimensions only
    timeframe_metadata:              # date/timestamp dimensions only
      <timeframe_name>:
        label: <string>
        format: <string>
        group_label: <string>
    mappings:
      <topic_name>:
        field: <view.field>
```

## Properties

<ParamField path="shared_dimensions" type="object">
  A map of shared dimension definitions, keyed by the dimension's name. The name becomes the selectable field in the workbook.

  <Expandable title="shared dimension properties" defaultOpen="true">
    <ParamField path="label" type="string">
      The display name for the shared dimension in the field browser.
    </ParamField>

    <ParamField path="description" type="string">
      A description of the shared dimension.
    </ParamField>

    <ParamField path="ai_context" type="string">
      Context passed to the Omni Agent for this shared dimension.
    </ParamField>

    <ParamField path="display_order" type="integer">
      Overrides the ordering of the shared dimension in the field browser.
    </ParamField>

    <ParamField path="mappings" type="object" required>
      One entry per included topic, mapping the topic to the field it contributes to the join. Each shared dimension needs a `mappings` entry for **every topic in the composite** — missing mappings surface as a validator error in the IDE. The mapped columns don't need to share a name, but they must represent the same logical value.

      <Expandable title="mappings properties" defaultOpen="true">
        <ParamField path="field" type="string" required>
          The field within that topic, in the format `view.field`. Use the bare field name — for date and timestamp dimensions, the timeframe (Day, Week, Month, …) is chosen when querying the shared dimension, not set in the mapping.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="timeframes" type="string[]">
      For shared dimensions that map to date or timestamp fields, this array specifies which timeframes are available for selection. If absent, Omni uses default timeframes: `raw`, `date`, `week`, `month`, `quarter`, `year`. See the [timeframes reference](/modeling/dimensions/parameters/timeframes) for all supported timeframe values.
    </ParamField>

    <ParamField path="timeframe_metadata" type="object">
      For shared dimensions that map to date or timestamp fields, this allows you to override properties for specific timeframes. Common use cases include customizing labels or formats for individual timeframes.

      <Expandable title="timeframe_metadata properties" defaultOpen="true">
        <ParamField path="<timeframe_name>" type="object">
          The name of the timeframe (e.g., `date`, `week`, `month`). Each timeframe can have the following properties:

          * `label` — custom display name for this timeframe
          * `format` — formatting override for this timeframe
          * `group_label` — group label override for this timeframe
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Align orders and marketing by day" theme={null}
shared_dimensions:
  activity_date:
    label: "Activity date"
    description: "Date the order was placed or the campaign was active"
    ai_context: "Use this for any time-series comparison between orders and marketing."
    mappings:
      orders_topic:
        field: orders.created_at
      marketing_topic:
        field: campaigns.start_date
```

```yaml title="Custom timeframes on shared dimension" theme={null}
shared_dimensions:
  activity_date:
    label: "Activity date"
    timeframes: [date, week, month, quarter]
    mappings:
      orders_topic:
        field: orders.created_at
      marketing_topic:
        field: campaigns.start_date
```

```yaml title="Custom timeframe labels with timeframe_metadata" theme={null}
shared_dimensions:
  activity_date:
    label: "Activity date"
    timeframes: [date, week, month, quarter, year]
    timeframe_metadata:
      date:
        label: "Day"
      week:
        label: "Week starting"
      month:
        label: "Month of activity"
      year:
        label: "Activity year"
    mappings:
      orders_topic:
        field: orders.created_at
      marketing_topic:
        field: campaigns.start_date
```