How to define a saved query in dbt

A saved query is a named Semantic Layer query in YAML: these metrics, grouped by these dimensions, with these filters. It is the unit that exports write to tables and that the cache can pre-compute, and BI integrations can list it for users who want a ready-made question rather than a blank canvas.

Copy and paste

# models/saved_queries/sales.yml
saved_queries:
  - name: monthly_sales_by_country
    description: Revenue and orders by month and country since 2026, for the sales dashboard.
    label: Monthly sales by country
    query_params:
      metrics:
        - revenue
        - order_count
      group_by:
        - TimeDimension('metric_time', 'month')
        - Dimension('customer__country')
      where:
        - "{{ TimeDimension('metric_time', 'day') }} >= '2026-01-01'"

Run it:

dbt sl query --saved-query monthly_sales_by_country     # dbt platform
mf query --saved-query monthly_sales_by_country --order metric_time__month   # dbt Core

metric_time__month    customer__country      revenue    order_count
--------------------  -------------------  ---------  -------------
2026-01-01T00:00:00   DE                         110              1
2026-02-01T00:00:00   DE                         130              1
2026-03-01T00:00:00   IT                         100              1
2026-04-01T00:00:00   IT                          80              1
2026-05-01T00:00:00   DE                         420              2
2026-05-01T00:00:00   IT                          50              1

The parts

• name, description, label: the name is what commands use; the label is what BI tools show. The documentation marks all three as required.
• query_params.metrics: one or more metrics. With several, group_by and where can only use dimensions they all share.
• query_params.group_by: written as objects, without the {{ }}: TimeDimension('metric_time', 'month'), Dimension('customer__country'), Entity('customer').
• query_params.where: a list of conditions, each a full Jinja filter string in quotes, as in a metric filter. All of them apply.

Adding to a saved query at run time

Options given on the command line are combined with the saved ones. A --where adds a condition:

mf query --saved-query monthly_sales_by_country --where "{{ Dimension('customer__country') }} = 'IT'"

That returns the three Italian rows. Use it to test variations; if a variation becomes a regular request, give it its own saved query.

Where to keep them

Saved queries can live in any YAML file under model-paths. A folder per team or dashboard keeps them apart from the model definitions; see how to organise semantic model and metric YAML files. They are nodes of the dbt DAG: dbt ls --resource-type saved_query lists them, and mf list saved-queries (dbt sl list saved-queries) shows them with their descriptions.

Saved query or view

A saved query is not materialized by itself; every run computes it from the current tables. To give tools without a Semantic Layer integration a table to read, add an export.

Tested with dbt Core 1.12 and MetricFlow 0.213 on DuckDB; the dbt sl command comes from the dbt documentation.