Skip to main content
Composite topics are currently in beta, but available on all Omni instances.
A composite topic combines existing topics so users can query across them from a single workbook. This guide covers creating one in the model IDE and optionally refining its shared views, dimensions, and measures.

​
Requirements

To follow the steps in this guide, you’ll need:
  • At least Modeler permissions to create a composite topic in the shared model
  • At least two existing topics that share at least one logical dimension (date, customer ID, region, etc.)

​
Create the composite topic

1

Create the file

Composite topics live in their own file with the .composite_topic extension.
  1. Open the Model IDE.
  2. Click File > New Composite topic.
  3. Enter a name. This becomes the filename and the unique identifier — for example, revenue_and_spend.
  4. Pick the topics you want to combine.
  5. Optional. Choose whether Omni should auto-detect shared views across the topics.
  6. Optional. Add a Group Label.
  7. Click Create.
Omni creates a <name>.composite_topic file with:
  • The topics: list you picked
  • A shared_views: list populated with any dimension tables joinable from every included topic, if you enabled auto-detection
For many use cases, this file is enough — skip to Save and use the composite topic. Steps 2–4 cover optional refinements.
2

Optional: Refine shared views

A shared view is a dimension table joinable from every topic — typically a date spine, region table, or product catalog. If you enabled auto-detection during creation, Omni populates the list for you. Edit it as needed:
Refining shared_views
Each shared view must be joinable from every included topic — either as the base view of every topic or through the model’s relationships. The validator surfaces an error otherwise.Any topic can use a shared view’s dimensions as join keys. Measures on a shared view are aggregated per topic, not combined. For example, if both an orders topic and a marketing topic use a shared regions view, the field picker shows a separate region count for each topic instead of one shared total.
3

Optional: Add shared dimensions

Shared dimensions handle the case where each topic has its own field for the same logical concept but at a different path.
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.
To define shared dimensions, use the mappings: syntax — each topic name is a key, and each value is the field path within that topic:
orders_and_marketing.composite_topic
The shared dimension activity_date becomes a single selectable field in the workbook. When a user picks it, Omni includes orders.created_at in the orders subquery and campaigns.start_date in the marketing subquery, then joins on the resulting columns.
4

Optional: Add shared measures

A shared measure combines values from multiple topics in a single SQL expression. Define it in the shared_measures block and reference topic-scoped fields with ${topic_name.view.field}.
To get the exact ${@topic.view.field} reference, open a workbook on the composite topic, find the measure you want to reference, click the menu, and select Modeling > Copy reference. This copies the fully-resolved reference (for example, ${@orders_topic.orders.total_revenue}) to your clipboard, which you can then paste directly into the shared measure SQL.The field picker context menu showing Modeling > Copy reference highlighted
Adding a shared measure
A few important things about shared measures:
  • Fields arrive pre-aggregated. Each ${topic.view.field} is already aggregated by the time the shared measure sees it — every topic runs its own subquery first.
  • Referenced fields are auto-included. Any field you reference is added to the right subquery; you don’t need to also add it to the workbook.
  • Filters on a shared measure run after the join. For example, revenue_per_dollar_spent > 1.5 is applied as a WHERE on the joined result in the generated SQL.
Write the sql as plain math over already-aggregated values — arithmetic, CASE, COALESCE, NULLIF, etc. Each referenced field is already a single aggregated value, so wrapping it in SUM(...) or COUNT(...) or setting aggregate_type re-aggregates over the post-join result, which usually isn’t desirable.
5

Save and use the composite topic

Save the file. The composite topic appears in the topic picker for any workbook on the same model. Open a workbook, select the composite topic, and mix fields from any of the included topics in a single query.

​
Next steps