diff --git a/website/docs/docs/build/metricflow-commands.md b/website/docs/docs/build/metricflow-commands.md index a0964269e68..b26b9c14139 100644 --- a/website/docs/docs/build/metricflow-commands.md +++ b/website/docs/docs/build/metricflow-commands.md @@ -25,7 +25,7 @@ Using MetricFlow with dbt Cloud means you won't need to manage versioning &mdash -- MetricFlow commands are embedded in the dbt Cloud CLI. This means you can immediately run them once you install the dbt Cloud CLI and don't need to install MetricFlow separately. +- MetricFlow [commands](#metricflow-commands) are embedded in the dbt Cloud CLI. This means you can immediately run them once you install the dbt Cloud CLI and don't need to install MetricFlow separately. - You don't need to manage versioning — your dbt Cloud account will automatically manage the versioning for you. @@ -36,21 +36,17 @@ Using MetricFlow with dbt Cloud means you won't need to manage versioning &mdash You can create metrics using MetricFlow in the dbt Cloud IDE. However, support for running MetricFlow commands in the IDE will be available soon. ::: - - +:::tip Use dbt Cloud CLI for semantic layer development -:::info Use dbt Cloud CLI for semantic layer development - -Use the dbt Cloud CLI for the experience in defining and querying metrics in your dbt project on dbt Cloud or dbt Core with MetricFlow. +You can use the dbt Cloud CLI for the experience in defining and querying metrics in your dbt project. A benefit to using the dbt Cloud is that you won't need to manage versioning — your dbt Cloud account will automatically manage the versioning. ::: - You can install [MetricFlow](https://github.com/dbt-labs/metricflow#getting-started) from [PyPI](https://pypi.org/project/dbt-metricflow/). You need to use `pip` to install MetricFlow on Windows or Linux operating systems: 1. Create or activate your virtual environment `python -m venv venv` @@ -70,16 +66,16 @@ Something to note, MetricFlow `mf` commands return an error if you have a Metafo MetricFlow provides the following commands to retrieve metadata and query metrics. - + -Use the `dbt sl` prefix before the command name to execute them in dbt Cloud. For example, to list all metrics, run `dbt sl list metrics`. +You can use the `dbt sl` prefix before the command name to execute them in the dbt Cloud CLI. For example, to list all metrics, run `dbt sl list metrics`. - [`list`](#list) — Retrieves metadata values. - [`list metrics`](#list-metrics) — Lists metrics with dimensions. - [`list dimensions`](#list) — Lists unique dimensions for metrics. - [`list dimension-values`](#list-dimension-values) — List dimensions with metrics. - [`list entities`](#list-entities) — Lists all unique entities. -- [`query`](#query) — Query metrics and dimensions you want to see in the command line interface. Refer to [query examples](#query-examples) to help you get started. +- [`query`](#query) — Query metrics, saved queries, and dimensions you want to see in the command line interface. Refer to [query examples](#query-examples) to help you get started. + ## Querying the API for metric values To query metric values, here are the following parameters that are available. Your query must have _either_ a `metric` **or** a `group_by` parameter to be valid. -| Parameter | Description | Example | +| Parameter |
Description
|
Example
| | --------- | -----------| ------------ | | `metrics` | The metric name as defined in your dbt metric configuration | `metrics=['revenue']` | | `group_by` | Dimension names or entities to group by. We require a reference to the entity of the dimension (other than for the primary time dimension), which is pre-appended to the front of the dimension name with a double underscore. | `group_by=['user__country', 'metric_time']` | @@ -177,7 +294,8 @@ To query metric values, here are the following parameters that are available. Yo | `where` | A where clause that allows you to filter on dimensions and entities using parameters. This takes a filter list OR string. Inputs come with `Dimension`, and `Entity` objects. Granularity is required if the `Dimension` is a time dimension | `"{{ where=Dimension('customer__country') }} = 'US')"` | | `limit` | Limit the data returned | `limit=10` | |`order` | Order the data returned by a particular field | `order_by=['order_gross_profit']`, use `-` for descending, or full object notation if the object is operated on: `order_by=[Metric('order_gross_profit').descending(True)`] | -| `compile` | If true, returns generated SQL for the data platform but does not execute | `compile=True` | +| `compile` | If true, returns generated SQL for the data platform but does not execute | `compile=True` | +| `saved_query` | A saved query you can use for frequently used queries. | `select * from {{ semantic_layer.query(saved_query="new_customer_orders"` | ## Note on time dimensions and `metric_time` @@ -403,16 +521,35 @@ semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'], ### Query with compile keyword -Use the following example to query using a `compile` keyword: +- Use the following example to query using a `compile` keyword: + ```sql + select * from {{ + semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'], + group_by=[Dimension('metric_time').grain('month'),'customer__customer_type'], + compile=True) + }} + ``` -```bash -select * from {{ -semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'], - group_by=[Dimension('metric_time').grain('month'),'customer__customer_type'], - compile=True) - }} +- Use the following example to compile SQL with a [saved query](/docs/build/saved-queries). You can use this for frequently used queries. + + ```sql + select * from {{ semantic_layer.query(saved_query="new_customer_orders", limit=5, compile=True}} + ``` + +:::info A note on querying saved queries +When querying [saved queries](/docs/build/saved-queries),you can use parameters such as `where`, `limit`, `order`, `compile`, and so on. However, keep in mind that you can't access `metric` or `group_by` parameters in this context. This is because they are predetermined and fixed parameters for saved queries, and you can't change them at query time. If you would like to query more metrics or dimensions, you can build the query using the standard format. +::: + +### Query a saved query + +Use the following example to query a [saved query](/docs/build/saved-queries): + +```sql +select * from {{ semantic_layer.query(saved_query="new_customer_orders", limit=5}} ``` +The JDBC API will use the saved query (`new_customer_orders`) as defined and apply a limit of 5 records. + ## FAQs