Skip to main content

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.

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

​
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: []