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

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.omni.co/feedback

```json
{
  "path": "/modeling/dimensions/parameters/level-of-detail",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# level_of_detail

> Creates a Level of Detail field, which controls the granularity at which an aggregation is computed.

This parameter is useful for creating metrics that remain consistent across different groupings, such as customer-level totals or category-level averages. LoD fields are dimensionalized, enabling you to perform an additional layer of aggregation - e.g. average customer lifetime spend.

<Tip>
  You can also create LoD fields in the workbook! In the field browser of a query tab, click the <Icon icon="ellipsis-vertical" type="solid" /> on a dimension and then **Modeling > New level of detail field**.
</Tip>

## Syntax

```yaml theme={null}
<dimension_name>:
  sql: <field>
  level_of_detail:
    aggregate_type: <aggregation>
    <grouping_strategy>: [<field_name>]
    custom_primary_key_sql: <field_reference>
    cancel_query_filters: <true_false>
```

## Properties

<ParamField path="dimension_name" type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties" defaultOpen="true">
    <ParamField path="level_of_detail" type="object">
      Configures the Level of Detail calculation for this dimension.

      <Expandable title="level_of_detail properties" defaultOpen="true">
        <ParamField path="aggregate_type" type="string" required>
          The type of aggregation to apply. Supports standard aggregations like `sum`, `average`, `count`, `min`, `max`, and distinct-on aggregations.

          **When the following aggregations are used**, the `custom_primary_key_sql` parameter is required:

          * `sum_distinct_on`
          * `average_distinct_on`
          * `median_distinct_on`
          * `percentile_distinct_on`
        </ParamField>

        <ParamField path="grouping_strategy" type="string" required>
          The grouping strategy and the field to use to apply it, specified as `grouping_strategy: [ field_name ]`. Refer to the [Examples](#examples) section to see an example with complete syntax.

          The grouping strategy must be one of the following:

          * `always_include` - Adds specified dimensions to the query's grouping, forcing a finer level of detail
          * `always_exclude` - Removes specified dimensions from the grouping, producing a coarser aggregation
          * `fixed` - Defines an absolute level of detail, replacing all query groupings
        </ParamField>

        <ParamField path="custom_primary_key_sql" type="string">
          A field reference that defines the key to use for deduplication when using `*_distinct_on` aggregate types, specified using `${}` syntax. This allows you to aggregate over a different level than the view's primary key, such as summing amounts by order ID when your view is at the order items level.

          **This parameter is required** when the following `aggregate_type`s are used:

          * `sum_distinct_on`
          * `average_distinct_on`
          * `median_distinct_on`
          * `percentile_distinct_on`
        </ParamField>

        <ParamField path="cancel_query_filters" type="boolean" default="false">
          When `true`, ignores any row filters applied in the outer query when computing the LoD metric. Defaults to `false`.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Customer lifetime spend" theme={null}
customer_lifetime_spend:
  sql: ${sale_price}
  label: Customer Lifetime Spend
  level_of_detail:
    aggregate_type: sum
    always_include: [user_id]
    cancel_query_filters: true
```

```yaml title="Fixed level of detail" theme={null}
category_total:
  sql: ${revenue}
  level_of_detail:
    aggregate_type: sum
    fixed: [category]
```

```yaml title="Exclude dimensions from grouping" theme={null}
overall_average:
  sql: ${score}
  level_of_detail:
    aggregate_type: average
    always_exclude: [region]
```

```yaml title="Sum distinct on with custom primary key" theme={null}
sum_by_order:
  sql: ${order_items.amount}
  level_of_detail:
    aggregate_type: sum_distinct_on
    custom_primary_key_sql: ${order_items.order_id}
    fixed: []
```