Learn how to define reusable filters in your semantic models
true
or false
. They encapsulate common query constraints, allowing users to easily apply predefined criteria without rewriting the logic repeatedly. Think of them as saved segments or common WHERE
clauses.
Using filters makes queries cleaner, more consistent, and easier to understand, focusing the analysis on specific questions rather than boilerplate filtering logic.
Here’s the basic structure for defining a filter:
country
, status
). Used for grouping, slicing, and direct filtering (WHERE country = 'USA'
). A boolean Dimension (e.g., is_active
) represents a fundamental true
/false
attribute stored in the data.total_revenue
). Used in aggregation functions (SUM
) and HAVING
clauses.last_30_days
, high_value_customers
). They must resolve to boolean and generate WHERE
clause logic.Field | Required | Description |
---|---|---|
name | Yes | Unique name for the filter within the model. |
description | Yes | Explains what condition the filter represents. This is mandatory. |
expr | No | The SQL expression defining the filter’s logic (must evaluate to boolean). Optional only if name matches a boolean dimension. |
args | No | A list of Argument objects to parameterize the filter’s expression. Defaults to an empty list if omitted. |
expr
true
or false
.expr
is optional only if the filter’s name
exactly matches the name of a boolean dimension defined within the same model. In this case, the filter implicitly means dimension_name = true
.
is_active
for dimension is_active
).expr
can reference:
{{arg_name}}
syntax).expr
, you typically don’t need a table prefix (e.g., country = 'USA'
). However, using prefixes (e.g., users.country
) can enhance clarity, especially when filters might be used in queries involving joins (even implicit ones via relationships). See Best Practices.args
. Reference parameters using {{parameter_name}}
.
args
: A list defining each parameter. See the Semantic Model Reference for the full specification of Argument
fields (name
, type
, description
, default
).relationship
exists. The semantic layer uses these relationships to potentially generate necessary joins or subqueries when the filter is applied in a query that also includes the required join defined by the relationship.
See the Semantic Model Reference for details on defining relationships.
Example: Cross-Model Filter
expr
must evaluate to a boolean (true
/false
).name
s (snake_case) and mandatory, clear description
s explaining the condition.dimension = true
, name the filter identically to the boolean dimension and omit the expr
.relationships
/joins or parameters in the description
.expr
involves fields that might also exist in other models or when using cross-model filters via relationships
. Use model_name.column_name
(e.g., users.country
) or relationship_name.column_name
(e.g., user_orders.product_sku
).expr
logic. Use parentheses ()
for complex conditions to ensure correct operator precedence.COALESCE
, IS NULL
, IS NOT NULL
etc., within expr
as needed for robust logic, as filter expressions are often used in WHERE
clauses where null propagation matters.type
for each parameter (string
, integer
, number
, date
, boolean
).args
list includes the required name
, type
, and description
fields.default
values for optional parameters.description
for each parameter.expr
using double curly braces: {{parameter_name}}
.expr
references fields from a related model (via a relationship
), the query using that filter must explicitly include the necessary join to that related model (using the relationship
).expr
. It validates that joins used in a query correspond to defined relationships
.description
must state if it relies on data from related models and which relationships
/joins are required. Example: “Filters for users whose latest order was cancelled. Requires joining using the ‘latest_order’ relationship.”customers
model context, incorporating various filter types and practices: