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 or 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

<dimension_name>:
  faceting:
    depends_on: [<field_reference>, ...]

<dimension_name>:
  faceting:
    exclude: [<field_reference>, ...]

Properties

dimension_name · object

The name of the dimension. Dimension names must:

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

Hide dimension_name properties

faceting · object

Configuration object that controls suggestion filtering behavior.

Hide faceting properties

depends_on · 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

exclude · 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

Examples

Independent suggestions

Make gender suggestions available regardless of other filter selections:

Independent suggestions

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:

Suggestions dependent on specific fields

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:

Exclude specific fields

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:

Cross-view suggestions

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:

# 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 - Alternative way to control suggestion behavior by pulling from a different field
• suggest_from_topic - Pull suggestions from a field in a different topic
• suggestion_list - Provide a static list of suggestions