--where filters the rows a query looks at, using the same Jinja objects as metric filters: {{ Dimension('customer__country') }}, {{ TimeDimension('metric_time', 'month') }}, {{ Metric('revenue', group_by=['customer']) }}. The filter is for one query; a filter written in the metric’s YAML is part of the metric.

Copy and paste

# one condition
dbt sl query --metrics revenue --group-by metric_time__month \
  --where "{{ Dimension('customer__country') }} = 'IT'"

# two --where options: both apply (AND)
dbt sl query --metrics revenue,order_count --group-by metric_time__year \
  --where "{{ Dimension('customer__country') }} = 'IT'" \
  --where "{{ Dimension('order__status') }} = 'shipped'"

# OR, IN and parentheses inside one string
dbt sl query --metrics revenue --group-by metric_time__year \
  --where "{{ Dimension('customer__segment') }} = 'SMB' or {{ Dimension('order__order_size') }} = 'large'"

# a period
dbt sl query --metrics revenue --group-by customer__country \
  --where "{{ TimeDimension('metric_time', 'month') }} = '2026-05-01'"

# customers whose lifetime revenue is above 500
dbt sl query --metrics revenue --group-by customer__country \
  --where "{{ Metric('revenue', group_by=['customer']) }} > 500"

With dbt Core, the same options work with mf query.

Example

Italy, shipped orders only:

metric_time__year      revenue    order_count
-------------------  ---------  -------------
2025-01-01T00:00:00        930              8
2026-01-01T00:00:00        130              2

Revenue of customers above 500 in total (Anna in Italy, Ben in Germany):

customer__country      revenue
-------------------  ---------
DE                         740
IT                         570

What you can filter on

How query and metric filters combine

A query filter is added to every metric in the query, on top of the metric’s own filter. italy_revenue is defined with a filter on Italy; queried with --where on Germany it returns nothing, because no order is in both countries:

metric_time__year      italy_revenue    revenue
-------------------  ---------------  ---------
2025-01-01T00:00:00                         330
2026-01-01T00:00:00                         660

When a BI tool shows a filtered metric as empty, check whether the dashboard filter contradicts the metric’s definition.

–where or –start-time

--start-time and --end-time limit the time range too, but they act on the data the metrics read. For cumulative metrics with offsets, such as YTD against last year, that removes the history the offset needs. A --where on metric_time is applied to the results and keeps it. For simple metrics the two give the same rows.

Quoting in the shell

Wrap the whole condition in double quotes and the values in single quotes. In zsh, if the braces cause trouble, run setopt BRACECCL once in the session. In PowerShell, keep the double quotes outside and escape any double quotes inside.

Tested with dbt Core 1.12 and MetricFlow 0.213 on DuckDB; the dbt sl syntax follows the dbt documentation.

References