> ## 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_measures

> Defines measures that combine values across topics after the join.

Defines measures that combine already-aggregated values from multiple topics in a single SQL expression. Each topic runs its own subquery first, so every `${@topic.view.field}` reference is a single aggregated value by the time the shared measure sees it. Any field you reference is auto-included in the right subquery — you don't need to also add it to the workbook.

<Warning>
  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 what you want.
</Warning>

## Syntax

```yaml theme={null}
shared_measures:
  <measure_name>:
    label: <string>
    description: <string>
    format: <format>
    sql: <expression using ${@topic.view.field}>
```

## Properties

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

  <Expandable title="shared measure properties" defaultOpen="true">
    <ParamField path="sql" type="string" required>
      The SQL expression combining topic-scoped fields, referenced as `${@topic_name.view.field}`. Filters on a shared measure are applied as a `WHERE` on the post-join result.
    </ParamField>

    <ParamField path="label" type="string">
      The display name for the shared measure in the field browser.
    </ParamField>

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

    <ParamField path="format" type="string">
      The number format for the measure's values. Accepts any Omni [named format](/modeling/models/format-values) (for example, `usdcurrency_2` or `percent_2`), an Excel-style string, or a conditional format.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Revenue per dollar of marketing spend" theme={null}
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
```