Skip to content

Commit

Permalink
Update saved-queries.md (#5189)
Browse files Browse the repository at this point in the history
update versionblock so the 'parameters' heading doesn't show up twice.
also removing redundancy.
  • Loading branch information
mirnawong1 authored Mar 28, 2024
2 parents 91bf668 + d00b7bd commit 4c78b91
Showing 1 changed file with 28 additions and 23 deletions.
51 changes: 28 additions & 23 deletions website/docs/docs/build/saved-queries.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Saved queries are distinct from [exports](/docs/use-dbt-semantic-layer/exports),
| ----------- | ----------- | ---------------- |
| **Availability** | Available on dbt Cloud [Team or Enterprise](https://www.getdbt.com/pricing/) plans on dbt versions 1.7 or newer.| Available in both dbt Core and dbt Cloud. |
| **Purpose** | To write 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 writes them within your data platform. Exports count towards [queried metrics](/docs/cloud/billing#what-counts-as-a-queried-metric) usage. <br /><br />**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.<br /><br /><br />**Example**: Group related metrics together for better organization, and include commonly uses dimensions and filters. | For materializing query results in the data platform. |
| **Usage** | Automatically runs saved queries and writes them within your data platform. Exports count towards [queried metrics](/docs/cloud/billing#what-counts-as-a-queried-metric) usage. <br /><br />**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.<br /><br /><br />**Example**: Group related metrics together for better organization, and include commonly used dimensions and filters. | For materializing query results in the data platform. |
| **Integration** | Must have the dbt Semantic Layer configured in your dbt project.<br /><br />Tightly integrated with the [MetricFlow Server](/docs/use-dbt-semantic-layer/sl-architecture#components) and dbt Cloud's job scheduler. | Integrated into the dbt <Term id="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. |

Expand Down Expand Up @@ -52,28 +52,6 @@ saved_queries:
```
</File>
## 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. |
| `label` | String | Required | The display name for your saved query. This value will be shown in downstream tools. |
| `config` | String | Required | A config section for any parameters specifying the saved query. |
| `config::cache` | String | Optional | A boolean to specify if a saved query should be used to populate the cache. Accepts `true` or `false`. Defaults to `false` |
| `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 used to write to the table or view. This option cannot be used for caching. |

</VersionBlock>
<!-- For versions 1.7 and lower-->
Expand Down Expand Up @@ -102,11 +80,38 @@ saved_queries:
schema: my_export_schema_name
```
</File>
</VersionBlock>
## Parameters
To define a saved query, refer to the following parameters:
<!-- For versions 1.8 and higher -->
<VersionBlock firstVersion="1.8">
| Parameter | Type | Required | Description |
|-------|---------|----------|----------------|
| `name` | String | Required | Name of the saved query object. |
| `description` | String | Required | A description of the saved query. |
| `label` | String | Required | The display name for your saved query. This value will be shown in downstream tools. |
| `config` | String | Required | A config section for any parameters specifying the saved query. |
| `config::cache` | String | Optional | A boolean to specify if a saved query should be used to populate the cache. Accepts `true` or `false`. Defaults to `false` |
| `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 used to write to the table or view. This option cannot be used for caching. |

</VersionBlock>

<!-- For versions 1.7 and lower-->
<VersionBlock lastVersion="1.7">

| Parameter | Type | Required | Description |
|-------|---------|----------|----------------|
| `name` | String | Required | Name of the saved query object. |
Expand Down

0 comments on commit 4c78b91

Please sign in to comment.