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:

Feature	Exports	Saved queries
Availability	Available on dbt Cloud Team or Enterprise plans on dbt versions 1.7 or newer.	Available in both dbt Core and dbt Cloud.
Purpose	To 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.
Usage	Automatically 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.
Integration	Must 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.
Configuration	Defined 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:

semantic_model.yml

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

Parameters

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

Parameter	Type	Required	Description
name	String	Required	Name of the saved query object.
description	String	Required	A description of the saved query.
query_params	Structure	Required	Contains the query parameters.
query_params::metrics	List or String	Optional	A list of the metrics to be used in the query as specified in the command line interface.
query_params::group_by	List or String	Optional	A list of the Entities and Dimensions to be used in the query, which include the Dimension or TimeDimension.
query_params::where	List or String	Optional	A list of strings that may include the Dimension or TimeDimension objects.
exports	List or Structure	Optional	A list of exports to be specified within the exports structure.
exports::name	String	Required	Name of the export object.
exports::config	List or Structure	Required	A config section for any parameters specifying the export.
exports::config::export_as	String	Required	The type of export to run. Options include table or view currently and cache in the near future.
exports::config::schema	String	Optional	The schema for creating the table or view. This option cannot be used for caching.
exports::config::alias	String	Optional	The 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.

Related docs

• Exports
• Set up the dbt Semantic Layer