M↓ View as Markdown ↗

Pre-defined Filters¶

Filters are saved conditions on a model, so the AI Analyst doesn't have to work out how to exclude test data or filter to active records each time. Some apply to every query; others are available for the AI Analyst to use when they fit the question.

Add or edit a filter¶

Availability

Who can do this: members with the Edit capability in the active Workspace.

In Studio, open Models and select a model.
Open the Filters tab.
Select a filter in the list to edit it, or click New filter at the bottom of the list.
Fill in the fields described below.
Click Save filter.

To delete a filter, select it and click the Remove (trash) icon next to its name, then confirm Remove filter?.

Each filter name must be unique within its model. If you reuse a name, you see "This model already has a filter with that name".

Filter fields¶

Filter name¶

A clear identifier that describes what condition this filter applies.

Examples: premium_customers_only, verified_only, recently_created, active_only, exclude_deleted

Description¶

Explain what this filter narrows to and when to apply it.

Example: "Filter to include only premium tier customers" or "Exclude records marked as deleted"

SemQL expression¶

The filter condition, written as a SemQL predicate over this model's dimensions. Rows that don't match are excluded.

Examples:

tier = 'PREMIUM': only premium customers
is_active = true: only active users
created_at >= CURRENT_DATE - INTERVAL '90 days': last 90 days

Reference dimensions by name and use single quotes for text. Filters can't reference measures or use aggregate functions. If you need warehouse-specific SQL, put it in a dimension and filter on that dimension.

Double quotes are not text

In SemQL, double quotes mark a quoted name (identifier), not a text value. Write status = 'active', not status = "active".

As you type, the editor validates the predicate and runs it against your data, showing how many rows match (for example "1,204 rows match"). You see "Checking filter…" while it runs. If the predicate is invalid, the error message appears under the editor and Save filter stays disabled until it validates. If the check can't be completed, you see "Filter failed to run". Use the reference panel below the editor to insert dimensions, functions and operators.

For the full syntax, see SemQL core syntax.

Apply to every query¶

Select Apply to every query if you want this filter applied to every query on this model, including queries on Metrics built on it.

The AI Analyst can see default filters but cannot turn them off, so only turn this on for conditions that must hold for every analysis. The AI Analyst always sees every filter on a model it can access, and opts into an optional filter by name.

Good candidates are conditions that must always hold: excluding test or demo data, excluding deleted or archived records, or keeping only production data (for example exclude_deleted). Leave it off for optional conditions that depend on the question, like active_only or premium_customers. An active_only filter helps when someone asks about "current users" but shouldn't be applied automatically when analyzing historical churn.

How filters behave in joins and metrics¶

A filter narrows only its own model's rows¶

A filter restricts the rows of the model it belongs to, not the whole joined result. When the model is on the optional side of an outer join (for example, the target of a Left join), a row that the filter removes simply counts as "no match", and the rows of the other model are kept.

If a rule such as "exclude test accounts" must also govern another model's rows, add a filter for it on that model too.

Metrics inherit model filters¶

Metrics don't have their own filters. They use the filters of the models they are built on:

Filters with Apply to every query turned on always apply to the metric. The metric shows them as Applied by default, and you change them on the model.
Other filters can be offered to the AI Analyst as Optional filters on the metric.

See Metrics.

Filters follow model access¶

Filters are not controlled separately in an AI Analyst's access settings. If an AI Analyst can access a model, it can see and use all of that model's filters.

Filters vs dimensions¶

A filter is a row-level condition applied as a WHERE on the model's rows. A dimension is an attribute you can filter, group or display. You build filters from dimensions: an active_only filter might use the is_active dimension with the condition is_active = true.