Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update build-metrics-intro.md #4128

Merged
merged 11 commits into from
Sep 26, 2023
4 changes: 2 additions & 2 deletions website/docs/docs/build/about-metricflow.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@ This guide introduces MetricFlow's fundamental ideas for new users. MetricFlow,

:::info

MetricFlow is a new way to define metrics in dbt and one of the key components of the [dbt Semantic Layer](/docs/use-dbt-semantic-layer/dbt-sl). It handles SQL query construction and defines the specification for dbt semantic models and metrics.
MetricFlow is a new way to define metrics and one of the key components of the [dbt Semantic Layer](/docs/use-dbt-semantic-layer/dbt-sl). It handles SQL query construction and defines the specification for dbt semantic models and metrics.

To fully experience the dbt Semantic Layer, including the ability to query dbt metrics via external integrations, you'll need a [dbt Cloud Team or Enterprise account](https://www.getdbt.com/pricing/).
MetricFlow is currently available on dbt v1.6 or higher for all users. dbt Core users can use the MetricFlow CLI to define metrics in their local dbt Core project. However, to experience the power of the universal [dbt Semantic Layer](/docs/use-dbt-semantic-layer/dbt-sl) and query those metrics in downstream tools, you'll need a dbt Cloud [Team or Enterprise](https://www.getdbt.com/pricing/) account.

:::

Expand Down
5 changes: 2 additions & 3 deletions website/docs/docs/build/build-metrics-intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,14 @@ Use MetricFlow in dbt to centrally define your metrics. As a key component of th
Use familiar constructs like semantic models and metrics to avoid duplicative coding, optimize your development workflow, ensure data governance for company metrics, and guarantee consistency for data consumers.

:::info
MetricFlow is currently available on dbt v1.6 or higher. MetricFlow provides a new way to define metrics in dbt and replaces the dbt_metrics package.
MetricFlow is currently available on dbt v1.6 or higher and allows users to define metrics in their dbt project whether in dbt Cloud or dbt Core. dbt Core users can use the MetricFlow CLI to define metrics in their local dbt Core project. However, to experience the power of the universal [dbt Semantic Layer](/docs/use-dbt-semantic-layer/dbt-sl) and query those metrics in downstream tools, you'll need a dbt Cloud [Team or Enterprise](https://www.getdbt.com/pricing/) account.

To use the dbt Semantic Layer, you must have a [dbt Cloud Team or Enterprise account](https://www.getdbt.com/pricing/).
:::

Before you start, consider the following guidelines:

- Define metrics in YAML and query them using these [new metric specifications](https://github.com/dbt-labs/dbt-core/discussions/7456).
- You must be on dbt v1.6 or higher to use MetricFlow. [Upgrade your dbt Cloud version](/docs/dbt-versions/upgrade-core-in-cloud) to get started.
- You must be on dbt v1.6 or higher to use MetricFlow. [Upgrade your dbt version](/docs/dbt-versions/upgrade-core-in-cloud) to get started.
- Use MetricFlow with Snowflake, BigQuery, Databricks, Postgres (CLI only), or Redshift. (dbt Cloud Postgres support coming soon)
- Unlock insights and query your metrics using the [dbt Semantic Layer](/docs/use-dbt-semantic-layer/dbt-sl) and its diverse range of [available integrations](/docs/use-dbt-semantic-layer/avail-sl-integrations).

Expand Down
17 changes: 9 additions & 8 deletions website/docs/docs/build/sl-getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,9 @@ import DefineMetrics from '/snippets/_sl-define-metrics.md';
import ConfigMetric from '/snippets/_sl-configure-metricflow.md';
import TestQuery from '/snippets/_sl-test-and-query-metrics.md';

This getting started page presents a sample workflow to help you create your first metrics in dbt Cloud or the command-line interface (CLI). It uses the [Jaffle shop example project](https://github.com/dbt-labs/jaffle-sl-template) as the project data source and is available for you to use. If you prefer, you can create semantic models and metrics for your own dbt project.
This getting started page presents a sample workflow to help you create your first metrics in dbt Cloud or the command-line interface (CLI). It uses the [Jaffle shop example project](https://github.com/dbt-labs/jaffle-sl-template) as the project data source and is available for you to use.

This guide will walk you through how to:
If you prefer, you can create semantic models and metrics for your own dbt project. This page will guide you on how to:

- [Create a semantic model](#create-a-semantic-model) using MetricFlow
- [Define metrics](#define-metrics) using MetricFlow
Expand All @@ -25,7 +25,10 @@ This guide will walk you through how to:
- [Set up dbt Semantic Layer](#set-up-dbt-semantic-layer) in dbt Cloud
- [Connect to and query the API](#connect-and-query-api) with dbt Cloud

To experience the power of a universal [dbt Semantic Layer](/docs/use-dbt-semantic-layer/dbt-sl) and query metrics in downstream tools, you'll need a dbt Cloud [Team or Enterprise](https://www.getdbt.com/pricing/) account.

MetricFlow allows users to define metrics in their dbt project whether in dbt Cloud or in dbt Core. dbt Core users can use the [MetricFlow CLI](/docs/build/metricflow-cli) to define metrics in their local dbt Core project.

However, to experience the power of the universal [dbt Semantic Layer](/docs/use-dbt-semantic-layer/dbt-sl) and query those metrics in downstream tools, you'll need a dbt Cloud [Team or Enterprise](https://www.getdbt.com/pricing/) account.

## Prerequisites

Expand All @@ -35,7 +38,7 @@ To experience the power of a universal [dbt Semantic Layer](/docs/use-dbt-semant
- Create a successful run in the environment where you configure the Semantic Layer.
- **Note:** Semantic Layer currently supports the Deployment environment for querying. (_development querying experience coming soon_)
- Set up the [Semantic Layer API](/docs/dbt-cloud-apis/sl-api-overview) in the integrated tool to import metric definitions.
- **Note:** dbt Core or Developer accounts can only query data manually using the [MetricFlow CLI](/docs/build/metricflow-cli) and SQL. To dynamically query metrics using external tools, you must have a dbt Cloud [Team or Enterprise](https://www.getdbt.com/pricing/) account with access to the Semantic Layer API.<br />
- **Note:** To access the API and query metrics in downstream tools, you must have a dbt Cloud [Team or Enterprise](https://www.getdbt.com/pricing/) account. dbt Core or Developer accounts can define metrics using the [MetricFlow CLI](/docs/build/metricflow-cli).<br />
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The MetricFlow CLI installation instructions state: You can install MetricFlow using PyPI as an extension of your dbt adapter in the CLI." Will that have to do additional installations outside of just MetricFlow to get this working with a dbt Cloud Developer account? If so, we may need to add that to the CLI page as I don't see any mentions of it working with a cloud account.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the cli doesn't work in cloud so we don't need to add the info. but maybe i can add 'ide' to clarify.

mirnawong1 marked this conversation as resolved.
Show resolved Hide resolved
- Understand [MetricFlow's](/docs/build/about-metricflow) key concepts, which powers the revamped dbt Semantic Layer.

:::tip
Expand Down Expand Up @@ -80,7 +83,7 @@ import SlSetUp from '/snippets/_new-sl-setup.md';

You can query your metrics in a JDBC-enabled tool or use existing first-class integrations with the dbt Semantic Layer.

Before you begin, you must have a dbt Cloud Team or Enterprise [multi-tenant](/docs/cloud/about-cloud/regions-ip-addresses) deployment, hosted in North America (cloud.getdbt.com login).
You must have a dbt Cloud Team or Enterprise [multi-tenant](/docs/cloud/about-cloud/regions-ip-addresses) deployment, hosted in North America. (Additional region support coming soon)

- <span>To learn how to use the JDBC API and what tools you can query it with, refer to the <a href="https://docs.getdbt.com/docs/dbt-cloud-apis/sl-api-overview" target="_self">{frontMatter.meta.api_name}</a></span>.<br />

Expand All @@ -105,12 +108,10 @@ User data passes through the Semantic Layer on its way back from the warehouse.
</details>
<details>
<summary>Is the dbt Semantic Layer open source?</summary>
The dbt Semantic Layer is proprietary, however, some components of the dbt Semantic Layer are open source, like dbt-core and MetricFlow. <br /><br />The universal dbt Semantic Layer is available to all Team and Enterprise Plans during public beta. Users on dbt Cloud Developer plans or dbt Core users can use MetricFlow to only define and test metrics locally.</details>
The dbt Semantic Layer is proprietary, however, some components of the dbt Semantic Layer are open source, like dbt-core and MetricFlow. <br /><br />dbt Cloud Developer or dbt Core users can define metrics in their project, including a local dbt Core project, using the dbt Cloud IDE or the MetricFlow CLI. However, to experience the universal dbt Semantic Layer and access those metrics using the API or downstream tools, users will must be on a dbt Cloud <a href="https://www.getdbt.com/pricing/">Team or Enterprise plan.</a></details>

## Next steps

Review the following documents to learn more and get started:

- [About MetricFlow](/docs/build/about-metricflow)
- [Build your metrics](/docs/build/build-metrics-intro)
- [Get started with the dbt Semantic Layer](/docs/use-dbt-semantic-layer/quickstart-sl)
Expand Down
2 changes: 1 addition & 1 deletion website/docs/docs/use-dbt-semantic-layer/dbt-sl.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ import Features from '/snippets/_sl-plan-info.md'
<Features
cycle="public beta"
product="dbt Semantic Layer"
plan="dbt Cloud Team and Enterprise"
plan="dbt Cloud Team or Enterprise"
instance="hosted in North America"
/>

Expand Down
14 changes: 8 additions & 6 deletions website/docs/docs/use-dbt-semantic-layer/quickstart-sl.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,9 @@ import TestQuery from '/snippets/_sl-test-and-query-metrics.md';

The dbt Semantic Layer, powered by [MetricFlow](/docs/build/about-metricflow), simplifies defining and using critical business metrics. It centralizes metric definitions, eliminates duplicate coding, and ensures consistent self-service access to metrics in downstream tools.

MetricFlow is a powerful component within the dbt Semantic Layer that helps users define and manage company metrics efficiently. It provides flexible abstractions and SQL query generation and also allows data consumers to retrieve metric datasets quickly and easily from a data platform.
MetricFlow, a powerful component of the dbt Semantic Layer, simplifies the creation and management of company metrics. It offers flexible abstractions, SQL query generation, and enables fast retrieval of metric datasets from a data platform.

Use this guide to fully experience the power of a universal dbt Semantic Layer. Here are the following steps you'll take:
Use this guide to fully experience the power of the universal dbt Semantic Layer. Here are the following steps you'll take:

- [Create a semantic model](#create-a-semantic-model) in dbt Cloud using MetricFlow
- [Define metrics](#define-metrics) in dbt Cloud using MetricFlow
Expand All @@ -34,6 +34,10 @@ Use this guide to fully experience the power of a universal dbt Semantic Layer.
- [Set up dbt Semantic Layer](#setup) in dbt Cloud
- [Connect and query API](#connect-and-query-api) with dbt Cloud


MetricFlow allows users to define metrics in their dbt project whether in dbt Cloud or in dbt Core. dbt Core users can use the [MetricFlow CLI](/docs/build/metricflow-cli) to define metrics in their local dbt Core project.

However, to experience the power of the universal [dbt Semantic Layer](/docs/use-dbt-semantic-layer/dbt-sl) and query those metrics in downstream tools, you'll need a dbt Cloud [Team or Enterprise](https://www.getdbt.com/pricing/) account.
## Prerequisites

import SetUp from '/snippets/_v2-sl-prerequisites.md';
Expand Down Expand Up @@ -86,7 +90,7 @@ import SlSetUp from '/snippets/_new-sl-setup.md';

You can query your metrics in a JDBC-enabled tool or use existing first-class integrations with the dbt Semantic Layer.

Before you begin, you must have a dbt Cloud Team or Enterprise [multi-tenant](/docs/cloud/about-cloud/regions-ip-addresses) deployment, hosted in North America (cloud.getdbt.com login).
You must have a dbt Cloud Team or Enterprise [multi-tenant](/docs/cloud/about-cloud/regions-ip-addresses) deployment, hosted in North America (Additional region support coming soon).

- <span>To learn how to use the JDBC API and what tools you can query it with, refer to the <a href="https://docs.getdbt.com/docs/dbt-cloud-apis/sl-api-overview" target="_self">{frontMatter.meta.api_name}</a></span>.<br />

Expand All @@ -112,13 +116,11 @@ User data passes through the Semantic Layer on its way back from the warehouse.
</details>
<details>
<summary>Is the dbt Semantic Layer open source?</summary>
The dbt Semantic Layer is proprietary, however, some components of the dbt Semantic Layer are open source, like dbt-core and MetricFlow. <br /><br />The universal dbt Semantic Layer is available to all Team and Enterprise Plans during public beta. Users on dbt Cloud Developer plans or dbt Core users can use MetricFlow to only define and test metrics locally.</details>
The dbt Semantic Layer is proprietary, however, some components of the dbt Semantic Layer are open source, like dbt-core and MetricFlow. <br /><br />dbt Cloud Developer or dbt Core users can define metrics in their project, including a local dbt Core project, using the dbt Cloud IDE or the MetricFlow CLI. However, to experience the universal dbt Semantic Layer and access those metrics using the API or downstream tools, users will must be on a dbt Cloud <a href="https://www.getdbt.com/pricing/">Team or Enterprise plan.</a></details>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same feedback (as further up) regarding MetricFlow CLI availability for dbt Cloud Developer users. If you scroll up to line 38 in this same doc, it only mentions dbt Core.

<br></br>

## Next steps

Review the following documents to learn more and get started:

- [Build your metrics](/docs/build/build-metrics-intro)
- [Set up dbt Semantic Layer](docs/use-dbt-semantic-layer/setup-dbt-sl)
- [Available integrations](/docs/use-dbt-semantic-layer/avail-sl-integrations)
Expand Down
2 changes: 1 addition & 1 deletion website/snippets/_sl-plan-info.md
Original file line number Diff line number Diff line change
@@ -1 +1 @@
<span>During <a href="https://docs.getdbt.com/docs/dbt-versions/release-notes/Aug-2023/sl-revamp-beta#public-beta" target="_self">{props.cycle}</a>, you can access {props.product} on <a href="https://www.getdbt.com/pricing/">{props.plan}</a> multi-tenant plans <a href="https://docs.getdbt.com/docs/cloud/about-cloud/regions-ip-addresses" target="_self">{props.instance}</a> (cloud.getdbt.com login). It's available on dbt v1.6 or higher. dbt Cloud Developer plans and dbt Core users can use MetricFlow to define and test metrics locally, but can't dynamically query them with integrated tools.</span><br /><br />
<span>To define and query metrics with the {props.product}, you must be on a <a href="https://www.getdbt.com/pricing/">{props.plan}</a> multi-tenant plan, <a href="https://docs.getdbt.com/docs/cloud/about-cloud/regions-ip-addresses" target="_self">{props.instance}</a> (Additional region support coming soon).<br /><br /> The re-released dbt Semantic Layer is available on dbt v1.6 or higher. dbt Core users can use the <a href="https://docs.getdbt.com/docs/build/metricflow-cli">MetricFlow CLI</a> to define metrics in their local project, but won't be able dynamically query them with integrated tools.</span><br /><br />
4 changes: 2 additions & 2 deletions website/snippets/_sl-test-and-query-metrics.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@ Support for testing or querying metrics in the dbt Cloud IDE is not available in

You can use the **Preview** or **Compile** buttons in the IDE to run semantic validations and make sure your metrics are defined. You can [dynamically query metrics](#connect-and-query-api) with integrated tools on a dbt Cloud [Team or Enterprise](https://www.getdbt.com/pricing/) plan using the [Semantic Layer API](/docs/dbt-cloud-apis/sl-api-overview).

Currently, you can test metrics locally using the MetricFlow CLI. dbt Cloud IDE support is coming soon. Alternatively, you can test using SQL client tools like DataGrip, DBeaver, or RazorSQL.
Currently, you can define and test metrics using the MetricFlow CLI. dbt Cloud IDE support is coming soon. Alternatively, you can test using SQL client tools like DataGrip, DBeaver, or RazorSQL.

:::

This section will explain how you can test and query metrics locally using the MetricFlow CLI (dbt Cloud IDE support coming soon).
This section will explain how you can test and query metrics using the MetricFlow CLI (dbt Cloud IDE support coming soon).

Before you begin, you'll need to install the [MetricFlow CLI](/docs/build/metricflow-cli) package and make sure you run at least one model.
### Install MetricFlow
Expand Down
2 changes: 1 addition & 1 deletion website/snippets/_v2-sl-prerequisites.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ To use the Semantic Layer, you must:
- Create a successful run in the environment where you configure the Semantic Layer.
- **Note:** Semantic Layer currently supports the Deployment environment for querying. (_development querying experience coming soon_)
- Set up the [Semantic Layer API](/docs/dbt-cloud-apis/sl-api-overview) in the integrated tool to import metric definitions.
- **Note:** dbt Core or Developer accounts can only query data manually using the [MetricFlow CLI](/docs/build/metricflow-cli) and SQL. To dynamically query metrics using external tools, you must have a dbt Cloud [Team or Enterprise](https://www.getdbt.com/pricing/) account with access to the Semantic Layer API.<br />
- **Note:** To access the API and query metrics in downstream tools, you must have a dbt Cloud [Team or Enterprise](https://www.getdbt.com/pricing/) account. dbt Core or Developer accounts can define metrics with the [MetricFlow CLI](/docs/build/metricflow-cli) but won't be able to dynamically query them.<br />
mirnawong1 marked this conversation as resolved.
Show resolved Hide resolved
- Understand [MetricFlow's](/docs/build/about-metricflow) key concepts, which powers the revamped dbt Semantic Layer.


Expand Down
Loading