> ## 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.
# Create a composite topic
> Create a composite topic in the model IDE, then refine its shared views, dimensions, and measures.
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
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 `.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](#save-and-use). Steps 2–4 cover optional refinements.
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:
```yaml title="Refining shared_views" theme={null}
topics: [orders_topic, marketing_topic]
shared_views: [date_spine, regions] # auto-detected; remove or add as needed
```
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.
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:
```yaml title="orders_and_marketing.composite_topic" theme={null}
topics: [orders_topic, marketing_topic]
label: "Revenue & Marketing"
shared_dimensions:
activity_date:
label: "Activity date"
description: "Aligns orders and marketing activity by day"
mappings:
orders_topic:
field: orders.created_at
marketing_topic:
field: campaigns.start_date
```
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.
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.
```yaml title="Adding a shared measure" theme={null}
topics: [orders_topic, marketing_topic]
shared_dimensions:
activity_date:
label: "Activity date"
mappings:
orders_topic:
field: orders.created_at
marketing_topic:
field: campaigns.start_date
shared_measures:
revenue_per_dollar_spent:
label: "Revenue per $ spent"
sql: ${@orders_topic.orders.total_revenue} / NULLIF(${@marketing_topic.campaigns.total_spend}, 0)
format: usdcurrency_2
```
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.
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
* [Composite topic examples](/modeling/composite-topics/examples) — worked composite topics you can adapt.
* [Composite topic parameters](/modeling/composite-topics/parameters) — the full parameter reference.