How to query a metric with dbt sl query

dbt sl query asks the Semantic Layer for metrics, grouped and filtered the way you choose, and prints the result. It runs through dbt platform from the platform CLI, the Studio IDE or the VS Code extension. Without dbt platform, the same queries run locally with mf query, with two small differences in the options.

Copy and paste

dbt sl list metrics
dbt sl list dimensions --metrics revenue

dbt sl query --metrics revenue,order_count --group-by metric_time__month
dbt sl query --metrics revenue --group-by customer__country --order-by -revenue --limit 10
dbt sl query --metrics revenue --group-by metric_time__month \
  --where "{{ Dimension('order__status') }} = 'shipped'"
dbt sl query --metrics revenue --group-by metric_time__month --compile    # show the SQL

The same with MetricFlow, locally:

mf query --metrics revenue --group-by customer__country --order -revenue --limit 10
mf query --metrics revenue --group-by metric_time__month --explain

customer__country      revenue
-------------------  ---------
IT                         520
DE                         110

dbt sl and mf

	dbt platform	dbt Core with MetricFlow
Prefix	`dbt sl`	`mf`
Sort	`--order-by`	`--order`
Show the SQL	`--compile`	`--explain`
Validate	`dbt sl validate`	`mf validate-configs`

Several metrics or dimensions go in one comma-separated list, without spaces. A - before a name sorts in descending order.

Names

Dimensions carry their entity: order__status, customer__country, never status or country alone.
Time uses metric_time with a grain: metric_time__day, __week, __month, __quarter, __year.
Filters wrap dimensions in {{ Dimension('...') }} and time in {{ TimeDimension('metric_time', 'month') }}. In zsh, if the braces cause trouble, run setopt BRACECCL once.

Reading the errors

A dimension without its entity:

ERROR: Got error(s) during query resolution.
  The given input does not match any of the available group-by-items for
  SimpleMetric('revenue').
  Suggestions:
    ['customer__country', 'customer', ...]

A misspelled metric:

  The given input does not exactly match any known metrics.
  Suggestions:
    ['revenue', 'revenue_mtd', 'shipped_revenue', ...]

Both errors list the names that would work. dbt sl list dimensions --metrics revenue prints all of them at once.

Things to know

Querying needs a paid plan. Querying the Semantic Layer from dbt platform and from BI tools needs a Starter, Enterprise or Enterprise+ account, and the CLI needs a valid dbt_cloud.yml; see how to install and configure the dbt Cloud CLI.
Limit the dates. --start-time 2026-01-01 --end-time 2026-03-31 keeps cumulative metrics from running to the end of the time spine.
To a file. mf query ... --csv revenue.csv writes the result to a CSV file.
The SQL. --compile or --explain show exactly what the Semantic Layer sends to the warehouse, which is the quickest way to check a join or a filter.

The mf commands and errors were tested with MetricFlow 0.213 on DuckDB; the dbt sl options come from the dbt platform documentation.

References

MetricFlow commands