From f05cf490b24d4fa94cef85fe19561d760485086c Mon Sep 17 00:00:00 2001 From: Jordan Stein Date: Tue, 18 Jul 2023 19:50:57 -0700 Subject: [PATCH 01/12] add cli docs --- website/docs/docs/build/metricflow-cli.md | 247 ++++++++++++++++++++++ 1 file changed, 247 insertions(+) create mode 100644 website/docs/docs/build/metricflow-cli.md diff --git a/website/docs/docs/build/metricflow-cli.md b/website/docs/docs/build/metricflow-cli.md new file mode 100644 index 00000000000..36abd524c8d --- /dev/null +++ b/website/docs/docs/build/metricflow-cli.md @@ -0,0 +1,247 @@ +--- +title: MetricFlow CLI +id: metricflow-cli +description: "Query metrics and metadata in your dbt project with the metricflow cli" +sidebar_label: "CLI" +tags: [Metrics, Semantic Layer] +--- + +After you have defined metrics in your dbt project, you can easily query metrics, dimensions, dimension values, and validate your configs using the MetricFlow CLI. + +## Installation +1. Create or activate your virtual environment.`python -m venv venv` +2. Run `pip install dbt-metricflow` + +## CLI commands + +## List +Retrieve metadata values about metrics/dimensions/entities/dimension values + +# List metrics +List the metrics with their available dimensions +``` +mf list metrics +Options: + --search TEXT Filter available metrics by this search term + --show-all-dimensions Show all dimensions associated with a metric. + --help Show this message and exit. +``` + +# List dimensions +List all unique dimensions for a metric or multiple metrics. Only common dimensions are shown if querying multiple metrics +``` +mf list dimensions --metrics +Options: + --metrics SEQUENCE List dimensions by given metrics (intersection). Ex. + --metrics bookings,messages + --help Show this message and exit. +``` + +# List dimension-values +List all dimension values with the corresponding metric +``` +mf list dimension-values --metrics --dimension +Options: + --dimension TEXT Dimension to query values from [required] + --metrics SEQUENCE Metrics that are associated with the dimension + [required] + --end-time TEXT Optional iso8601 timestamp to constraint the end time of + the data (inclusive) + --start-time TEXT Optional iso8601 timestamp to constraint the start time + of the data (inclusive) + --help Show this message and exit. +``` +# List entities +List all unique entities. +``` +mf list entities --metrics +Options: + --metrics SEQUENCE List entities by given metrics (intersection). Ex. + --metrics bookings,messages + --help Show this message and exit. +``` + +## Validate configs + Perform validations against the defined semantic model configurations. +``` +mf validate-configs +Options: + --dw-timeout INTEGER Optional timeout for data warehouse + validation steps. Default None. + --skip-dw If specified, skips the data warehouse + validations + --show-all If specified, prints warnings and future- + errors + --verbose-issues If specified, prints any extra details + issues might have + --semantic-validation-workers INTEGER + Optional. Uses the number of workers + specified to run the semantic validations. + Should only be used for exceptionally large + configs + --help Show this message and exit. +``` + +## Health checks +Performs a health check against the DW provided in the configs. +``` +mf health-checks +``` + +## Tutorial +Runs through a getting started tutorial. + +``` +mf tutorial +``` + +## Query +Create a new query with MetricFlow, execute that query agaisnt the users data platform and return the result. +``` +mf query --metrics --group-by +Options: + --metrics SEQUENCE Metrics to query for: syntax is --metrics bookings + or for multiple metrics --metrics bookings,messages + --group-by SEQUENCE Dimensions and/or entities to group by: syntax is + --group-by ds or for multiple group bys --group-by + ds,org + --end-time TEXT Optional iso8601 timestamp to constraint the end + time of the data (inclusive) + --start-time TEXT Optional iso8601 timestamp to constraint the start + time of the data (inclusive) + --where TEXT SQL-like where statement provided as a string. For + example: --where "revenue > 100" + --limit TEXT Limit the number of rows out using an int or leave + blank for no limit. For example: --limit 100 + --order SEQUENCE Metrics or group bys to order by ("-" prefix for + DESC). For example: --order -ds or --order + ds,-revenue + --csv FILENAME Provide filepath for dataframe output to csv + --explain In the query output, show the query that was + executed against the data warehouse + --show-dataflow-plan Display dataflow plan in explain output + --display-plans Display plans (e.g. metric dataflow) in the browser + --decimals INTEGER Choose the number of decimal places to round for + the numerical values + --show-sql-descriptions Shows inline descriptions of nodes in displayed SQL + --help Show this message and exit. + ``` + + +## Query Examples + +Query metrics by dimensions. + +The following query will retrun the order_amount metric by metric time. +``` +mf query --metrics order_amount --group-by metric_time +✔ Success 🦄 - query completed after 1.24 seconds +| METRIC_TIME | ORDER_AMOUNT | +|:--------------|---------------:| +| 2017-06-16 | 792.17 | +| 2017-06-17 | 458.35 | +| 2017-06-18 | 490.69 | +| 2017-06-19 | 749.09 | +| 2017-06-20 | 712.51 | +| 2017-06-21 | 541.65 | +``` + +You can include multiple dimensions in a query. For example, we can also group by the `is_food_order` dimension to see if orders we're for food or not. + +``` +mf query --metrics order_amount --group-by metric_time, is_food_order + Success 🦄 - query completed after 1.70 seconds +| METRIC_TIME | IS_FOOD_ORDER | ORDER_AMOUNT | +|:--------------|:----------------|---------------:| +| 2017-06-16 | True | 499.27 | +| 2017-06-16 | False | 292.90 | +| 2017-06-17 | True | 431.24 | +| 2017-06-17 | False | 27.11 | +| 2017-06-18 | True | 466.45 | +| 2017-06-18 | False | 24.24 | +| 2017-06-19 | False | 300.98 | +| 2017-06-19 | True | 448.11 | +``` + +You can add order and limit functions to filter and present the data in a readable format. The following query limits the data set to 10 records, and orders by metric time descending. + +``` +mf query --metrics order_amount --group-by metric_time,is_food_order --limit 10 --order -metric_time +✔ Success 🦄 - query completed after 1.41 seconds +| METRIC_TIME | IS_FOOD_ORDER | ORDER_AMOUNT | +|:--------------|:----------------|---------------:| +| 2017-08-31 | True | 459.90 | +| 2017-08-31 | False | 327.08 | +| 2017-08-30 | False | 348.90 | +| 2017-08-30 | True | 448.18 | +| 2017-08-29 | True | 479.94 | +| 2017-08-29 | False | 333.65 | +| 2017-08-28 | False | 334.73 | +``` + +You can futher filter the data set by adding a where clause to your query. + +``` + mf query --metrics order_amount --group-by metric_time,is_food_order --limit 10 --order -metric_time --where "is_food_order = True" + ✔ Success 🦄 - query completed after 1.06 seconds +| METRIC_TIME | IS_FOOD_ORDER | ORDER_AMOUNT | +|:--------------|:----------------|---------------:| +| 2017-08-31 | True | 459.90 | +| 2017-08-30 | True | 448.18 | +| 2017-08-29 | True | 479.94 | +| 2017-08-28 | True | 513.48 | +| 2017-08-27 | True | 568.92 | +| 2017-08-26 | True | 471.95 | +| 2017-08-25 | True | 452.93 | +| 2017-08-24 | True | 384.40 | +| 2017-08-23 | True | 423.61 | +| 2017-08-22 | True | 401.91 | +``` + +To filter by time, there are dedicated start and end time options. Using these options to filter by time allows MetricFlow to further optimize query performance by pushing down the where filter when appropriate. + +``` + mf query --metrics order_amount --group-by metric_time,is_food_order --limit 10 --order -metric_time --where "is_food_order = True" --start-time '2017-08-22' --end-time '2017-08-27' +✔ Success 🦄 - query completed after 1.53 seconds +| METRIC_TIME | IS_FOOD_ORDER | ORDER_AMOUNT | +|:--------------|:----------------|---------------:| +| 2017-08-27 | True | 568.92 | +| 2017-08-26 | True | 471.95 | +| 2017-08-25 | True | 452.93 | +| 2017-08-24 | True | 384.40 | +| 2017-08-23 | True | 423.61 | +| 2017-08-22 | True | 401.91 | +``` + +You can see the SQL metricflow is generating by adding --explain to your query. + +``` + mf query --metrics order_amount --group-by metric_time,is_food_order --limit 10 --order -metric_time --where "is_food_order = True" --start-time '2017-08-22' --end-time '2017-08-27' --explain + ✔ Success 🦄 - query completed after 0.28 seconds +🔎 SQL (remove --explain to see data or add --show-dataflow-plan to see the generated dataflow plan): +SELECT + metric_time + , is_food_order + , SUM(order_cost) AS order_amount +FROM ( + SELECT + cast(ordered_at as date) AS metric_time + , is_food_order + , order_cost + FROM ANALYTICS.js_dbt_sl_demo.orders orders_src_1 + WHERE cast(ordered_at as date) BETWEEN CAST('2017-08-22' AS TIMESTAMP) AND CAST('2017-08-27' AS TIMESTAMP) +) subq_3 +WHERE is_food_order = True +GROUP BY + metric_time + , is_food_order +ORDER BY metric_time DESC +LIMIT 10 +``` +To export the results of your query to a csv, simply add the `--csv file_name.csv` flag. + +``` +mf query --metrics order_amount --group-by metric_time,is_food_order --limit 10 --order -metric_time --where "is_food_order = True" --start-time '2017-08-22' --end-time '2017-08-27' --csv query_example.csv +✔ Success 🦄 - query completed after 0.83 seconds +🖨 Successfully written query output to query_example.csv +``` \ No newline at end of file From bc686db975ccb077fe59d4a7bdf6665c5363a9c8 Mon Sep 17 00:00:00 2001 From: Jordan Stein Date: Tue, 18 Jul 2023 20:07:03 -0700 Subject: [PATCH 02/12] add spec for metrics and measures --- website/docs/docs/build/measures.md | 20 ++++++++++++++++++++ website/docs/docs/build/metrics-overview.md | 14 ++++++++++++++ 2 files changed, 34 insertions(+) diff --git a/website/docs/docs/build/measures.md b/website/docs/docs/build/measures.md index f85d21e3dcb..e9922bda8a9 100644 --- a/website/docs/docs/build/measures.md +++ b/website/docs/docs/build/measures.md @@ -15,6 +15,26 @@ Measures are aggregations performed on columns in your model. They can be used a | [`agg`](#aggregation) | dbt supports the following aggregations: `sum`, `max`, `min`, `count_distinct`, and `sum_boolean`. | Required | | [`expr`](#expr) | You can either reference an existing column in the table or use a SQL expression to create or derive a new one. | Optional | | [`non_additive_dimension`](#non-additive-dimensions) | Non-additive dimensions can be specified for measures that cannot be aggregated over certain dimensions, such as bank account balances, to avoid producing incorrect results. | Optional | +|[agg_params]| specific aggregation properties such as a percentile. | [Optional]| +|[agg_time_dimension]| The time field. Defaults to the default agg time dimension for the semantic model. | [Optional] | +|[non_additive_dimension]| configs used if needing non-additive dimensions | [Optional]| +|[label]| How the metric will be displayed in docs and downstream integrations. | [Required]| + + +## Measyres Spec +An example of the complete yaml measures spec is below. The actual configuration of your measures will depend on the aggregation you're using. + +``` +measures: + - name: The name of the measure # think transaction_total. If `expr` not present then this is the expected name of the column [Required] + description: same as always [Optional] + agg: the aggregation type. #think average, sum, max, min, etc.[Required] + expr: the field # think transaction_total or some other name you might want to alias [Optional] + agg_params: specific aggregation properties such as a percentile [Optional] + agg_time_dimension: The time field. Defaults to the default agg time dimension for the semantic model. [Optional] + non_additive_dimension: configs used if needing non-additive dimensions [Optional] + label: How the metric will be displayed in docs and downstream integrations. [Required] +` ### Name diff --git a/website/docs/docs/build/metrics-overview.md b/website/docs/docs/build/metrics-overview.md index e7271ecf417..7658926cb19 100644 --- a/website/docs/docs/build/metrics-overview.md +++ b/website/docs/docs/build/metrics-overview.md @@ -16,6 +16,20 @@ The keys for metrics definitions are: * `constraint`: For any type of metric, you may optionally include a constraint string, which applies a dimensional filter when computing the metric. You may think of this as your WHERE clause. * `meta`: Additional metadata you want to add to your metric. +An example of the complete metrics spec configuration is below: +``` +metrics: + - name: metric name + description: same as always + type: the type of the metric + type_params: + - specific properties for the metric type + configs: here for `enabled` + label: The display name for your metric. This value will be shown in downstream tools. + filter: | + {{ dimension('name') }} > 0 and {{ dimension(' another name') }} is not null + +``` This page explains the different supported metric types you can add to your dbt project. - [About MetricFlow](/docs/build/about-metricflow) - [Semantic models](/docs/build/semantic-models) - [Metrics](/docs/build/metrics-overview) +- [MetricFlow CLI](/docs/build/metricflow-cli) diff --git a/website/sidebars.js b/website/sidebars.js index bf992619dbc..e11f51feca9 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -257,6 +257,7 @@ const sidebarSettings = { "docs/build/join-logic", "docs/build/validation", "docs/build/metricflow-time-spine", + "docs/build/metricflow-cli", ] }, "docs/build/sl-getting-started", From 9de4f66fa062bc14c5034a882bba82e589c04d3b Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Wed, 19 Jul 2023 12:20:03 +0100 Subject: [PATCH 07/12] change sidebar --- website/docs/docs/build/metricflow-cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/build/metricflow-cli.md b/website/docs/docs/build/metricflow-cli.md index ee048539ac4..8dff28680d4 100644 --- a/website/docs/docs/build/metricflow-cli.md +++ b/website/docs/docs/build/metricflow-cli.md @@ -2,7 +2,7 @@ title: MetricFlow CLI id: metricflow-cli description: "Query metrics and metadata in your dbt project with the metricflow cli" -sidebar_label: "MetricFlow CLI" +sidebar_label: "MetricFlow CLI commands" tags: [Metrics, Semantic Layer] --- From eab30e5aeb226f0ae2d4fbf8b9afa7885df9d489 Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Wed, 19 Jul 2023 12:32:39 +0100 Subject: [PATCH 08/12] active voice --- website/docs/docs/build/metricflow-cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/build/metricflow-cli.md b/website/docs/docs/build/metricflow-cli.md index 9cab298fd59..6a49f11878f 100644 --- a/website/docs/docs/build/metricflow-cli.md +++ b/website/docs/docs/build/metricflow-cli.md @@ -6,7 +6,7 @@ sidebar_label: "MetricFlow CLI commands" tags: [Metrics, Semantic Layer] --- -After you have defined metrics in your dbt project, you can query metrics, dimensions, dimension values, and validate your configs using the MetricFlow command line (CLI). +Once you define metrics in your dbt project, you can query metrics, dimensions, dimension values, and validate your configs using the MetricFlow command line (CLI). ## Installation From 6963cea971257f3fb1a7d415d6eba30421306e0e Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Wed, 19 Jul 2023 16:16:19 +0100 Subject: [PATCH 09/12] org tabs better --- website/docs/docs/build/metricflow-cli.md | 34 +++++++++++++++-------- 1 file changed, 23 insertions(+), 11 deletions(-) diff --git a/website/docs/docs/build/metricflow-cli.md b/website/docs/docs/build/metricflow-cli.md index 6a49f11878f..0098d470def 100644 --- a/website/docs/docs/build/metricflow-cli.md +++ b/website/docs/docs/build/metricflow-cli.md @@ -8,7 +8,7 @@ tags: [Metrics, Semantic Layer] Once you define metrics in your dbt project, you can query metrics, dimensions, dimension values, and validate your configs using the MetricFlow command line (CLI). -## Installation +# Installation You can install the [MetricFlow CLI](https://github.com/dbt-labs/metricflow#getting-started) from [PyPI](https://pypi.org/project/dbt-metricflow/). You need to use `pip` to install the MetricFlow CLI on Windows or Linux operating systems: @@ -17,7 +17,7 @@ You can install the [MetricFlow CLI](https://github.com/dbt-labs/metricflow#gett The MetricFlow CLI is compatible with Python versions 3.8, 3.9, 3.10 and 3.11 -## CLI commands +# CLI commands The MetricFlow CLI provides the following commands to retrieve metadata and query metrics. @@ -33,13 +33,13 @@ To execute the commands, use the `mf` prefix before the command name. For exampl - [`tutorial`](#tutorial) — Dedicated MetricFlow tutorial to help get you started. - [`query`](#query) — Query metrics and dimensions you want to see in the CLI. Refer to [query examples](#query-examples) to help you get started. -### List +## List This command retrieves metadata values related to [Metrics](/docs/build/metrics-overview), [Dimensions](/docs/build/dimensions), and [Entities](/docs/build/entities) values. For example, if you're trying to retrieve the `name` metadata value for a metric, you can use the following command: -### List metrics +## List metrics This command lists the metrics with their available dimensions: @@ -51,7 +51,7 @@ Options: --help Show this message and exit. ``` -### List dimensions +## List dimensions This command lists all unique dimensions for a metric or multiple metrics. It displays only common dimensions when querying multiple metrics: @@ -63,7 +63,7 @@ Options: --help Show this message and exit. ``` -### List dimension-values +## List dimension-values This command lists all dimension values with the corresponding metric: @@ -79,7 +79,7 @@ Options: of the data (inclusive) --help Show this message and exit. ``` -### List entities +## List entities This command lists all unique entities: @@ -114,7 +114,7 @@ Options: --help Show this message and exit. ``` -### Health checks +## Health checks This command performs a health check against the data platform you provided in the configs: @@ -122,7 +122,7 @@ This command performs a health check against the data platform you provided in t mf health-checks ``` -### Tutorial +## Tutorial Follow the dedicated MetricFlow tutorial to help you get started: @@ -130,7 +130,7 @@ Follow the dedicated MetricFlow tutorial to help you get started: mf tutorial ``` -### Query +## Query Create a new query with MetricFlow, execute that query against the user's data platform, and return the result: @@ -165,7 +165,7 @@ Options: ``` -### Query examples +## Query examples The following tabs presents various different types of query examples that you can use to query metrics and dimensions. Select the tab that best suits your needs: @@ -220,6 +220,7 @@ mf query --metrics order_amount --group-by metric_time, is_food_order + **Example 3** — You can add order and limit functions to filter and present the data in a readable format. The following query limits the data set to 10 records and orders them by `metric_time`, descending. @@ -297,6 +298,17 @@ mf query --metrics order_amount --group-by metric_time,is_food_order --limit 10 + + + +### Additional query examples + +The following tabs presents additional query examples, like exporting to a CSV. Select the tab that best suits your needs: + + + + + **Example 6** — Add `--explain` to your query to view the SQL generated by MetricFlow. From 6f9e3d7c71d71c0ffdd284d307468735c20efcd5 Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Wed, 19 Jul 2023 17:07:46 +0100 Subject: [PATCH 10/12] fix headers --- website/docs/docs/build/metricflow-cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/build/metricflow-cli.md b/website/docs/docs/build/metricflow-cli.md index 0098d470def..32ec5864b7a 100644 --- a/website/docs/docs/build/metricflow-cli.md +++ b/website/docs/docs/build/metricflow-cli.md @@ -91,7 +91,7 @@ Options: --help Show this message and exit. ``` -### Validate-configs +## Validate-configs This command performs validations against the defined semantic model configurations: From 014175fabafc408ec19fba0b0f866ee46ea2fdf6 Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Wed, 19 Jul 2023 18:07:31 +0100 Subject: [PATCH 11/12] Update website/docs/docs/build/metricflow-cli.md --- website/docs/docs/build/metricflow-cli.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/website/docs/docs/build/metricflow-cli.md b/website/docs/docs/build/metricflow-cli.md index 32ec5864b7a..23ac3c14079 100644 --- a/website/docs/docs/build/metricflow-cli.md +++ b/website/docs/docs/build/metricflow-cli.md @@ -41,6 +41,9 @@ For example, if you're trying to retrieve the `name` metadata value for a metric ## List metrics +```bash +mf list + This command lists the metrics with their available dimensions: ```bash From 5a74d72318938843de735ad0937b3bdb27ecd090 Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Wed, 19 Jul 2023 18:07:54 +0100 Subject: [PATCH 12/12] Update website/docs/docs/build/metricflow-cli.md --- website/docs/docs/build/metricflow-cli.md | 1 - 1 file changed, 1 deletion(-) diff --git a/website/docs/docs/build/metricflow-cli.md b/website/docs/docs/build/metricflow-cli.md index 23ac3c14079..9e934e9ccca 100644 --- a/website/docs/docs/build/metricflow-cli.md +++ b/website/docs/docs/build/metricflow-cli.md @@ -37,7 +37,6 @@ To execute the commands, use the `mf` prefix before the command name. For exampl This command retrieves metadata values related to [Metrics](/docs/build/metrics-overview), [Dimensions](/docs/build/dimensions), and [Entities](/docs/build/entities) values. -For example, if you're trying to retrieve the `name` metadata value for a metric, you can use the following command: ## List metrics