shared_dimensions - Omni Docs

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.

You don’t need a shared dimension for a field that already lives in a shared view — the shared view’s columns are usable as join keys directly.

Syntax

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

shared_dimensions

object

A map of shared dimension definitions, keyed by the dimension’s name. The name becomes the selectable field in the workbook.

Hide shared dimension properties

label

string

The display name for the shared dimension in the field browser.

description

string

A description of the shared dimension.

ai_context

string

Context passed to the Omni Agent for this shared dimension.

display_order

integer

Overrides the ordering of the shared dimension in the field browser.

mappings

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.

Hide mappings properties

field

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.

timeframes

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 for all supported timeframe values.

timeframe_metadata

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.

Hide timeframe_metadata properties

<timeframe_name>

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

Examples

Align orders and marketing by day

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

Custom timeframes on shared dimension

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

Custom timeframe labels with timeframe_metadata

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

​Syntax

​Properties

​Examples

Syntax

Properties

Examples