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

# faceting

> Controls how a dimension's filter suggestions are affected by other active filters.

When faceting is enabled, if you select values in one filter, the suggestions shown in other filters automatically update to reflect only the values that exist with your current selections. The `faceting` property lets you customize this behavior per dimension.

You can configure dimensions to have suggestions that are:

* **Independent** of all other filters - Specified using `depends_on: []`
* **Dependent** only on specific fields - Specified using `depends_on: [<fields>]`
* **Filtered** by all fields except specific ones - Specified using `exclude: [<fields>]`

This is particularly useful for improving user experience in scenarios where the default faceting behavior is too restrictive or where certain dimensions should remain independent regardless of other selections.

## Limitations

* This parameter can't be used with [`suggest_from_field`](/modeling/dimensions/parameters/suggest-from-field) or [`suggest_from_topic`](/modeling/dimensions/parameters/suggest-from-topic) on the same dimension
* Cross-view references are only allowed in topic-scoped views
* Field references in `depends_on` or `exclude` must resolve to existing dimensions or filter-only fields (not measures)
* Self-references (a dimension depending on or excluding itself) will generate a warning
* `depends_on` and `exclude` can't be used on the same dimension

## Syntax

```yaml theme={null}
<dimension_name>:
  faceting:
    depends_on: [<field_reference>, ...]
```

```yaml theme={null}
<dimension_name>:
  faceting:
    exclude: [<field_reference>, ...]
```

## 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="faceting" type="object">
      Configuration object that controls suggestion filtering behavior.

      <Expandable title="faceting properties" defaultOpen="true">
        <ParamField path="depends_on" type="array of strings">
          List of field references that should filter this dimension's suggestions. All other filters are ignored.

          * Use an empty array `[]` to make suggestions completely independent of all filters
          * Field references can point to dimensions or filter-only fields (not measures) to make suggestions dependent on specific fields
          * In topic-scoped views, can reference fields from other views in the topic (e.g., `orders.region`)
          * Cannot be used with `exclude`
        </ParamField>

        <ParamField path="exclude" type="array of strings">
          List of field references that should NOT filter this dimension's suggestions. All other filters are applied.

          * Field references can point to dimensions or filter-only fields (not measures)
          * In topic-scoped views, can reference fields from other views in the topic
          * Cannot be an empty array (has no effect)
          * Cannot be used with `depends_on`
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

### Independent suggestions

Make `gender` suggestions available regardless of other filter selections:

```yaml title="Independent suggestions" theme={null}
views:
  users:
    dimensions:
      gender:
        sql: ${users.gender}
        faceting:
          depends_on: []
```

### Include-list faceting

`city` suggestions should only be filtered by `country` and `state` selections, ignoring all other active filters:

```yaml title="Suggestions dependent on specific fields" theme={null}
views:
  users:
    dimensions:
      city:
        sql: ${users.city}
        faceting:
          depends_on:
            - country
            - state

      country:
        sql: ${users.country}

      state:
        sql: ${users.state}
```

### Exclude-list faceting

`first_name` suggestions should be filtered by all fields except `state`:

```yaml title="Exclude specific fields" theme={null}
views:
  users:
    dimensions:
      first_name:
        sql: ${users.first_name}
        faceting:
          exclude:
            - state
```

### Cross-view faceting in topics

In a topic-scoped view, reference fields from other views in the topic. This example makes `city` suggestions depend on the `region` from the `orders` view:

```yaml title="Cross-view suggestions" theme={null}
topics:
  sales:
    views:
      users:
        dimensions:
          city:
            faceting:
              depends_on:
                - orders.region

      orders:
        dimensions:
          region:
            sql: ${orders.region}
```

### Per-topic customization

Different topics can configure different faceting behavior for the same base view:

```yaml theme={null}
# Base view definition
views:
  users:
    dimensions:
      city:
        sql: ${TABLE}.city

# Topic 1: city depends on country
topics:
  sales:
    views:
      users:
        dimensions:
          city:
            faceting:
              depends_on:
                - country

# Topic 2: city has independent suggestions
topics:
  marketing:
    views:
      users:
        dimensions:
          city:
            faceting:
              depends_on: []
```

## Related parameters

* [`suggest_from_field`](/modeling/dimensions/parameters/suggest-from-field) - Alternative way to control suggestion behavior by pulling from a different field
* [`suggest_from_topic`](/modeling/dimensions/parameters/suggest-from-topic) - Pull suggestions from a field in a different topic
* [`suggestion_list`](/modeling/dimensions/parameters/suggestion-list) - Provide a static list of suggestions