Skip to main content

Saved queries

Saved queries are a way to save commonly used queries in MetricFlow. You can group metrics, dimensions, and filters that are logically related into a saved query.

Exports and saved queries comparison

Saved queries are distinct from exports, which schedule and execute saved queries using dbt Cloud's job scheduler. The following table compares the features and usage of exports and saved queries:

Saved queries
AvailabilityAvailable on dbt Cloud Team or Enterprise plans on dbt versions 1.7 or newer.Available in both dbt Core and dbt Cloud.
PurposeTo materialize saved queries in your data platform and expose metrics and dimensions as a view or table.To define and manage common Semantic Layer queries in YAML, which includes metrics and dimensions.
UsageAutomatically runs saved queries and materializes them within your data platform. Exports count towards queried metrics usage.

Example: Creating a weekly aggregated table for active user metrics, automatically updated and stored in the data platform.
Used for organizing and reusing common MetricFlow queries within dbt projects.

Example: Group related metrics together for better organization, and include commonly uses dimensions and filters.
IntegrationMust have the dbt Semantic Layer configured in your dbt project.

Tightly integrated with the MetricFlow Server and dbt Cloud's job scheduler.
Integrated into the dbt DAG and managed alongside other dbt nodes.
ConfigurationDefined within the saved_queries configuration. Set up within the dbt Cloud environment and job scheduler settings.Defined in YAML format within dbt project files.

All metrics in a saved query need to use the same dimensions in the group_by or where clauses. The following is an example of a saved query:

- name: p0_booking
description: Booking-related metrics that are of the highest priority.
- bookings
- instant_bookings
- TimeDimension('metric_time', 'day')
- Dimension('listing__capacity_latest')
- "{{ Dimension('listing__capacity_latest') }} > 3"


To define a saved query, refer to the following parameters:

nameStringRequiredName of the saved query object.
descriptionStringRequiredA description of the saved query.
query_paramsStructureRequiredContains the query parameters.
query_params::metricsList or StringOptionalA list of the metrics to be used in the query as specified in the command line interface.
query_params::group_byList or StringOptionalA list of the Entities and Dimensions to be used in the query, which include the Dimension or TimeDimension.
query_params::whereList or StringOptionalA list of strings that may include the Dimension or TimeDimension objects.
exportsList or StructureOptionalA list of exports to be specified within the exports structure.
exports::nameStringRequiredName of the export object.
exports::configList or StructureRequiredA config section for any parameters specifying the export.
exports::config::export_asStringRequiredThe type of export to run. Options include table or view currently and cache in the near future.
exports::config::schemaStringOptionalThe schema for creating the table or view. This option cannot be used for caching.
exports::config::aliasStringOptionalThe table alias to use to write the table or view. This option cannot be used for caching.

All metrics in a saved query need to use the same dimensions in the group_by or where clauses.