Skip to main content
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
  • Dependent only on specific fields
  • Filtered by all fields except specific ones
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.

​
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

​
Faceting modes

ConfigurationBehavior
No faceting propertyDefault: all active filters affect suggestions
faceting: { depends_on: [] }Independent: no filters applied to suggestions
faceting: { depends_on: [fields] }Include-list: only specified fields affect suggestions
faceting: { exclude: [fields] }Exclude-list: all fields affect suggestions except specified ones

​
Examples

​
Independent suggestions

Make gender suggestions available regardless of other filter selections: 
views:
  users:
    dimensions:
      gender:
        sql: ${TABLE}.gender
        faceting:
          depends_on: []

​
Include-list faceting

City suggestions should only be filtered by country and state selections, ignoring all other active filters: 
views:
  users:
    dimensions:
      city:
        sql: ${TABLE}.city
        faceting:
          depends_on:
            - country
            - state

      country:
        sql: ${TABLE}.country

      state:
        sql: ${TABLE}.state

​
Exclude-list faceting

First name suggestions should be filtered by all fields except state: 
views:
  users:
    dimensions:
      first_name:
        sql: ${TABLE}.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: 
topics:
  sales:
    views:
      users:
        dimensions:
          city:
            faceting:
              depends_on:
                - orders.region

      orders:
        dimensions:
          region:
            sql: ${TABLE}.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: []

​
Validation rules

The faceting property has several validation rules:
  • depends_on and exclude are mutually exclusive - you cannot use both on the same dimension
  • faceting cannot be used with suggest_from_field or suggest_from_topic on the same dimension
  • An empty exclude: [] array is invalid (has no effect)
  • Field references in depends_on or exclude must resolve to existing dimensions or filter-only fields (not measures)
  • Cross-view references are only allowed in topic-scoped views
  • Self-references (a dimension depending on or excluding itself) will generate a warning
  • Duplicate entries in depends_on or exclude will generate a warning