Go here to sign up for a free account and learn more about our dbt Semantic Layer integration.

Deliver a streamlined metrics catalog to your business users so they can access data from your dbt Semantic Layer metrics for visualization, discovery, and dashboarding.

This article includes:

• Before connecting to PowerMetrics
• Adding dbt Semantic Layer metrics
• Setting metric properties
• Certifying metrics
• Accessing metric details
• Frequently asked questions
• Does PowerMetrics have any pre-built metric definitions?
• How does PowerMetrics get updated when my dbt metrics change?
• How do I share an account connection?
• How do I delete an account connection?
• Why can't I load my metrics?
• How do I access the dbt queries for my metric visualizations?

Before connecting to PowerMetrics

Confirm you have the right setup for the PowerMetrics – dbt Semantic Layer integration by ensuring:

• You have a dbt Cloud Team or Enterprise level account and are using a version of dbt that supports dbt Semantic Layer (dbt v1.6 or higher).
• You’ve already set up the dbt Semantic Layer and built and defined metrics in a dbt Semantic Layer project.

Have the following information ready. You’ll enter it when connecting to PowerMetrics:

• The environment ID. To find this information, go to your environment in dbt Cloud and look at the URL. The environment ID is the set of digits at the end. For example, in this case https://cloud.getdbt.com/#/accounts/11111/projects/22222/environments/55555/ the environment ID is 55555.
• Your dbt Cloud service token. If needed, go here to learn how to generate a service account token. Make sure you assign “Semantic Layer Only” and “Metadata Only” permissions to your service account token. If you already have a token but aren’t sure where to find it, go to the Your Profile section and look under API Access.

Adding dbt Semantic Layer metrics

Connect to your dbt Cloud account and import your dbt metrics into PowerMetrics.

To add dbt Semantic Layer metrics:

1. In the left navigation sidebar click the + button beside Metrics and select dbt™ Semantic Layer metrics. (See below.)
   
2. If this is your first time connecting to dbt Semantic Layer:
• Click Connect account.
• Click Add a new account.
• Enter the Environment ID (the unique ID you received when enabling the Semantic Layer feature for your dbt project).
• Enter your dbt Cloud Service token. Learn more about dbt Cloud service account tokens and permissions.
• At Host name, note that semantic-layer.cloud.getdbt.com (the North American multi-tenant host name) is entered here by default. Learn more about dbt Cloud Regions and IP addresses.
• Enter a Display name. We recommend using an intuitive name that matches your dbt Semantic Layer project and data warehouse.
• Click Save.
3. The Connection successful window displays.
4. If you want PowerMetrics to automatically update when you successfully deploy your dbt Semantic Layer project, you need to set up a webhook. Click the Copy button to copy the webhook URL that displays under Webhook. You’ll use it when setting up the webhook in dbt.
   Learn more in this section of the article “How does PowerMetrics get updated when my dbt metrics change?”
   
5. Click Continue.
   Note: The next time you add dbt Semantic Layer metrics, we assume you want to use the same account as before and skip steps 2 - 5. If you want to use a different account, click the account connection (as shown below). Then, click Add a new account (go back to step 2).
   
6. Select the metrics you want to add to your list of metrics. You can click individual metric tiles or click Select all metrics to add them to your list of metrics.
   Note: The metric names here are formatted for display purposes (initial uppercase, no underscores). To see the metric names as they’re formatted in the dbt project (lowercase, with underscores) hover over the display name and view the tooltip.
   Important: In future, whenever you add metrics to your dbt Semantic Layer project, remember to come back here and import them into PowerMetrics.
   Tip: If you have a lot of dbt metrics, use the Search field to help locate the ones you’re looking for. (See below.) You can also use the Metric type filter to display specific types of dbt metrics: Simple, ratio, cumulative, or derived.
   
   Tip: Click the icon for a metric to learn about it, including its description, metric type (simple, derived, ratio, and cumulative) and its available periodicities and segmentations. (See below.)
   
7. When you’re done selecting metrics, click Add metrics.
   Tip: If you return to this page later, you can tell which metrics you’ve already imported. They display with a green checkmark. (See below.)
   
8. Your list of metrics opens with the newly added ones displayed at the top. To open a metric’s homepage, select it in the list.

Setting metric properties

After adding a dbt Semantic Layer metric to PowerMetrics, you can modify its data format and set a favourable trend. You can also change the metric’s display name and add a description.

To set properties for a metric:

1. In the left navigation sidebar, click Metrics to open your list of metrics.
2. Select the desired metric. The metric’s homepage opens in view mode.
3. Click the Edit button at the top of the page, then click the Settings tab.
4. At Format, select an alternate data format from the drop-down menu.
5. At Favourable trend, choose whether you want ascending or descending values to indicate a positive trend.
   For example, if your metric includes sales totals, a higher (ascending) number demonstrates a positive trend but, if your metric includes cost to acquire customers, a lower (descending) number indicates a positive trend. Favourable trends are indicated by a green arrow. Unfavourable changes in metric values are indicated by a red arrow.
6. Click the About tab.
7. At Name, enter a different display name for the metric.
8. At Description, the metric description from the dbt Semantic Layer project is automatically entered here. You can, optionally, override this description with different text.
   Note: You can also certify your metric while setting its properties. See more about certifying metrics below.
9. Click Save metric.

Certifying metrics

When you’re finished adding and setting properties for a metric you can certify it. This recommends it for use by others in your organization. Learn more about metric certification.

Accessing metric details

You access metric details from the About panel, opened by clicking the button in the banner across the top of a metric’s homepage. (To open a metric’s homepage, click the Metrics button in the left navigation sidebar, then select a metric from the list to open it.)

In the About panel, you’ll see the following:

• The metric description. By default, this information comes from the dbt Semantic Layer project, however, in edit mode, you can override it with an alternate description.
• The metric type (simple, ratio, cumulative, or derived).
• The metric owner and when it was last edited.
• The amount of data history that’s available.
• The available segments, displayed as pink text.
• The semantic layer metric name (ID).
• The metric's certification status. Learn more about certifying metrics.
• The associated data service.

Frequently asked questions

Does PowerMetrics have any pre-built metric definitions?

Yes. We provide dbt metric definition templates for every metric in MetricHQ. Each definition includes its label, description, type, expression, and base metrics.

To access dbt metric definition templates:

• Select a metric in MetricHQ. Under Metric Toolkit, click dbt Metric Definition, then click Copy.
  After copying the definition, you’ll paste it into your yml file in the dbt Semantic Layer. Then, you’ll populate the placeholder text with the applicable information from your data warehouse.

How does PowerMetrics get updated when my dbt metrics change?

dbt Semantic Layer metrics evolve over time as new data is added to the database or metric definitions in dbt are updated. To ensure these changes are automatically reflected in your PowerMetric metrics, you can set up a webhook in dbt. The webhook notifies PowerMetrics when you have successfully run a deployment job for the corresponding dbt Semantic Layer project. PowerMetrics then updates the metadata it has for the metric, clears cached queries, and notifies the UI to update its state and get the latest data for the changed metrics. For information on setting up a webhook, see Webhooks for your jobs.

Here are a few tips for creating a webhook in dbt Cloud:

• In the Event section, select the Run completed option.
• In the Jobs section, select the job that builds and updates the semantic model and metrics.
• In the Endpoint field, paste the Webhook URL you copied from PowerMetrics (step #4 in the “Adding dbt Semantic Layer metrics” procedure above).
  Tip: You can also find the Webhook URL by:
  1. In the left navigation sidebar, clicking the + button beside Metrics and selecting dbt™ Semantic Layer metrics.
  2. Clicking the account connection, located in the upper-right corner.
  3. Clicking the 3-dot menu beside the account connection name and selecting Edit.

Instead of setting up automatic updates, you can manually clear the cache in PowerMetrics for an account connection. This action also updates your metrics in PowerMetrics to align with changes to your dbt metric data and metric definitions.

To manually clear the cache for an account connection:

1. In the left navigation sidebar, click Metrics to open your list of metrics.
2. Select any dbt metric from the list. The metric’s homepage opens in view mode.
3. Click the Edit button at the top of the page, then click the Data tab.
4. At Semantic layer account, click the 3-dot menu, then select Clear cache. The cache is cleared for all metrics associated with this account connection. (See below.)
   
5. Click Save metric.
   Note: You can alternatively clear the cache using the following method: Click the + button beside Metrics and select dbt™ Semantic Layer metrics. Next, click the account connection in the upper right corner. Click the 3-dot menu beside the account connection name and then click Clear cache. Click Connect, then click Continue.

How do I share an account connection?

You can share an account connection to enable other editor users to import and set up metrics from the associated dbt Semantic Layer project.

To share an account connection:

1. In the left navigation sidebar click the + button beside Metrics and select dbt™ Semantic Layer metrics.
2. Click the account connection, located in the upper-right corner. (See below.)
   
3. Click the 3-dot menu beside the account connection name and then click Edit. (See below.)
   
4. Enable the Share account connection with editor users toggle. (See below.)
   
5. Click Save.

How do I delete an account connection?

To delete an account connection:

1. In the left navigation sidebar click the + button beside Metrics and select dbt™ Semantic Layer metrics.
2. Click the account connection, located in the upper-right corner. (See below.)
   
3. Click the 3-dot menu beside the account connection name and then click Delete. (See below.)
   

Why can’t I load my metrics?

If you see the following message: “The metric <"metric name"> cannot be found in the associated dbt Semantic Layer project”, this means there are no dbt metrics available for import. This happens because metrics weren’t added to the Semantic Layer project or they were removed from it. It can also happen if the metric has been renamed in the dbt project but not updated in PowerMetrics.

If the dbt metric you originally used for this visualization is unchanged, except that it’s been renamed, click the Edit button and, in the Data tab, under dbt project metric, select the renamed metric. Update the name of the metric visualization to match the new dbt metric name and click Save metric.

If you need help adding metrics to your dbt Semantic Layer project, you can refer to these articles: Setting up the dbt Semantic Layer and building and defining metrics.

Tip: If you remove a metric from dbt and want to re-add it, if it uses the same metric name/ID as before, the associated metric in PowerMetrics will start working again. You’ll find the metric name/ID in the About tab.

How do I access the dbt queries for my metric visualizations?

When debugging and troubleshooting it can be helpful to investigate the dbt and SQL queries for your metric visualizations.

You can view (and, optionally, copy) queries for a metric visualization on the metric’s homepage, on a dashboard, or in Explorer.

Note: Only the owner of the associated dbt Semantic Layer account can access these queries.

To view queries for metric visualizations on a metric homepage:

1. In the left navigation sidebar, click Metrics to open your list of metrics.
2. Click the metric you want to investigate.
3. Click the 3-dot menu for a metric visualization on the homepage and select View queries. (See below.)
   
   Note: The homepage displays a set of visualizations for a single metric. As a result, they’re all created using the same queries so you can click the 3-dot menu for any of them. The only exception is the “details” visualization in the upper-right corner.
4. Under Queries, select the query you want to view and, optionally, click the Copy button to assist with further investigation.
   Note: If an error occurs when the queries are being run, an error message will display here.
5. When you’re done, click Close.

To view queries for metric visualizations on a dashboard:

1. In the left navigation sidebar, click Dashboards to open your list of dashboards.
2. Select the dashboard that contains the metric(s) you want to investigate.
3. Click the 3-dot menu for the metric visualization on the dashboard and select View queries.
4. Under Queries, select the query you want to view and, optionally, click the Copy button to assist with further investigation.
   
   Note: If an error occurs when the queries are being run, an error message will display here.
5. When you’re done, click Close.

To view queries in Explorer:

1. In the left navigation sidebar, click Explorer.
   If you haven’t added any metrics yet to Explorer, go here to learn how.
2. Either click the View queries button or the 3-dot menu in the upper-right corner of the window and select View queries from the drop-down list. (See below.)
   
3. Under Queries, select the query you want to view and, optionally, click the Copy button to assist with further investigation.
   Note: If an error occurs when the queries are being run, an error message will display here.
4. When you’re done, click Close.

Related articles

• PowerMetrics: Working with (and combining) semantic and metrics layer metrics