Customizing filter suggestions

When you filter on a field in Omni, you get a list of suggested values to pick from. That list isn’t a static lookup — it’s a query Omni runs against your warehouse, which is why suggestions can load slowly, include values that don’t fit the rest of your query, or go stale. This guide covers where those values come from and the model parameters that change that behavior: where suggestions are sourced from, whether they narrow in response to other filters, and how long they’re cached.

How suggestions are sourced

By default, Omni populates up to 2,000 suggestions (not configurable) by querying the field’s distinct values in the context of the topic the field belongs to:

  SELECT field_filter_is_based_on
    FROM table
GROUP BY 1
   LIMIT 2000

Depending on the specifics of the model — for example, if the field is in a view other than the topic’s base view — you may also see the relevant JOIN or WHERE clauses in the suggestion query.

Changing the suggestion source

Three dimension parameters override the default query. Setting any of them means suggestions no longer come from the field’s own distinct values.

Parameter	Description	Available on measures?
`suggest_from_field`	Pulls suggestions from a different field, usually one that queries faster	Yes
`suggest_from_topic`	Routes the suggestion query to a different topic	No
`suggestion_list`	Sets the list of options explicitly, bypassing the query. Also allows you to set a display label separate from the underlying value, which is helpful when the stored value isn’t intuitive.	Yes

suggest_from_field and suggest_from_topic can’t be used with faceting on the same dimension.

How other filters affect suggestions

When faceting is enabled, selecting values in one filter narrows the suggestions shown in other filters to values that exist alongside your current selections.

Customizing per-dimension suggestion behavior

The faceting parameter lets you customize how suggestions behave on a per-dimension basis.

Independent of selections
Depend on specified fields
Exclude specified fields

To make suggestions independent of all other filter selections, add depends_on: [] as a child to faceting. In this example, gender suggestions will be available regardless of other filter selections:

Suggestions are independent of other filter selections

dimensions:
  gender:
    sql: ${users.gender}
    faceting:
      depends_on: []

Note: depends_on cannot be used with exclude.

To make a dimension’s suggestions dependent only on specific fields, specify a field list in depends_on. In this example, city suggestions should only be filtered by country and state selections, ignoring all other active filters:

Suggestions are filtered only by specified fields

dimensions:
  city:
    sql: ${users.city}
    faceting:
      depends_on:
        - country
        - state

  country:
    sql: ${users.country}

  state:
    sql: ${users.state}

Note: depends_on cannot be used with exclude.

You can also configure a list of fields that will not affect suggestions using exclude. In this example, first_name suggestions should be filtered by all fields except state:

Suggestions are filtered by all fields except those excluded

dimensions:
  first_name:
    sql: ${users.first_name}
    faceting:
      exclude:
        - state

Note: exclude cannot be used with depends_on.

Enabling faceting across the workbook

facet_workbook_filters is disabled by default. Set it to true to turn faceting on for every filter in the workbook. When enabled, all filter suggestions in the workbook will be faceted based on the current filter selection.

Enabling this setting can make suggestion queries more complex and less cacheable, so they may run slower or return nothing where suggestions were expected.

Caching and refreshing

Filter suggestions are retained for 30 days, independent of the model’s cache policy. To make them obey the policy’s max_cache_age instead, set filter_suggestions_must_obey_policy to true on the cache policy:

Obey cache policy & retain for 24 hours

cache_policies:
  cache_for_a_day:
    max_cache_age: 24 hours
    filter_suggestions_must_obey_policy: true

Once filter_suggestions_must_obey_policy is set, it can’t be removed, though its value can be changed.

Refreshing stale filter suggestions

In rare circumstances, suggestions may be cached in a stale state. To enable the refresh option for a specific query:

Mac - Hold Command + Shift
Windows - Hold Control + Shift

A icon will appear. Click it to refresh the filter suggestions. This will refresh suggestions for the current query. If other queries have stale suggestions, you will need to repeat these steps on that query’s filter.

The filter suggestion menu with the refresh option enabled

Next steps

Adding and configuring filters on workbook queries
Troubleshooting filters not showing all expected values