From 28c28c81fb9b6ad380effb07a48675be4f181880 Mon Sep 17 00:00:00 2001 From: rpourzand Date: Mon, 23 Oct 2023 15:30:18 -0700 Subject: [PATCH 1/9] Update sl-partner-integration-guide.md Adding a note on best practices for putting metadata in API requests for integration partners --- .../sl-partner-integration-guide.md | 27 ++++++++++++------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md b/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md index c41469bf08a..ad341eb4eff 100644 --- a/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md +++ b/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md @@ -33,6 +33,14 @@ The dbt Semantic Layer APIs authenticate with `environmentId`, `SERVICE_TOKEN`, We recommend you provide users with separate input fields with these components for authentication (dbt Cloud will surface these parameters for the user). +### Exposing Metadata to dbt Labs + +When building an integration, we recommend you expose certain metadata in the request for analytics purposes. Among other items, it is helpful to have the following: + +- Your application's name (e.g., Tableau) +- The user email of the person querying from your application +- The version of dbt they are on. + ## Best practices on exposing metrics @@ -85,7 +93,7 @@ Allow users to query either one metric alone without dimensions or multiple metr - Allow toggling between metrics/dimensions seamlessly. -- Be clear on exposing what dimensions are queryable with what metrics and hide things that don’t apply, and vice versa. +- Be clear on exposing what dimensions are queryable with what metrics and hide things that don’t apply(our APIs provide calls for you to get relevant dimensions for metrics, and vice versa). - Only expose time granularities (monthly, daily, yearly) that match the available metrics. * For example, if a dbt model and its resulting semantic model have a monthly granularity, make sure querying data with a 'daily' granularity isn't available to the user. Our APIs have functionality that will help you surface the correct granularities @@ -109,6 +117,15 @@ For better analysis, it's best to have the context of the metrics close to where - Allow for creating other metadata that’s useful for the metric. We can provide some of this information in our configuration (Display name, Default Granularity for View, Default Time range), but there may be other metadata that your tool wants to provide to make the metric richer. +### Transparency and Using Compile + +For transparency and additional context, we recommend you have an easy way for the user to obtain the SQL that MetricFlow generates. Depending on what API you are using, you can do this by using our compile parameter. This is incredibly powerful because we want to be very transparent to the user about what we're doing and do not want to be a black box. This would be mostly beneficial to a technical user. + + +### Where filters and Optimization + +In the cases where our APIs support either a string or a filter list for the `where` clause, we always recommend that your application utilizes the filter list in order to gain maximum pushdown benefits. The `where` string may be more intuitive for users writing queries during testing, but it will not have the performance benefits of the filter list in a production environment. + ## Example stages of an integration These are recommendations on how to evolve a Semantic Layer integration and not a strict runbook. @@ -136,14 +153,6 @@ These are recommendations on how to evolve a Semantic Layer integration and not * Querying dimensions without metrics and other more advanced querying functionality * Suggest metrics to users based on teams/identity, and so on. -### A note on transparency and using compile - -For transparency and additional context, we recommend you have an easy way for the user to obtain the SQL that MetricFlow generates. Depending on what API you are using, you can do this by using our compile parameter. This is incredibly powerful because we want to be very transparent to the user about what we're doing and do not want to be a black box. This would be mostly beneficial to a technical user. - - -### A note on where filters - -In the cases where our APIs support either a string or a filter list for the `where` clause, we always recommend that your application utilizes the filter list in order to gain maximum pushdown benefits. The `where` string may be more intuitive for users writing queries during testing, but it will not have the performance benefits of the filter list in a production environment. ## Related docs From baf071595972a90c806eb84461951e8a2e455df6 Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Wed, 25 Oct 2023 11:25:47 +0100 Subject: [PATCH 2/9] Update website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md --- .../docs/guides/dbt-ecosystem/sl-partner-integration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md b/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md index ad341eb4eff..51cd9682502 100644 --- a/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md +++ b/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md @@ -33,7 +33,7 @@ The dbt Semantic Layer APIs authenticate with `environmentId`, `SERVICE_TOKEN`, We recommend you provide users with separate input fields with these components for authentication (dbt Cloud will surface these parameters for the user). -### Exposing Metadata to dbt Labs +### Exposing metadata to dbt Labs When building an integration, we recommend you expose certain metadata in the request for analytics purposes. Among other items, it is helpful to have the following: From 0122e225b54dbf4052685522cd18900fff7cb629 Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Wed, 25 Oct 2023 11:26:19 +0100 Subject: [PATCH 3/9] Update website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md --- .../docs/guides/dbt-ecosystem/sl-partner-integration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md b/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md index 51cd9682502..fe2a1407c74 100644 --- a/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md +++ b/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md @@ -37,7 +37,7 @@ We recommend you provide users with separate input fields with these components When building an integration, we recommend you expose certain metadata in the request for analytics purposes. Among other items, it is helpful to have the following: -- Your application's name (e.g., Tableau) +- Your application's name (such as 'Tableau') - The user email of the person querying from your application - The version of dbt they are on. From 184ee98cabdc9077d5996d776e965a1574f450f3 Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Wed, 25 Oct 2023 11:26:58 +0100 Subject: [PATCH 4/9] Update website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md --- .../docs/guides/dbt-ecosystem/sl-partner-integration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md b/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md index fe2a1407c74..6c1751264cc 100644 --- a/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md +++ b/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md @@ -38,7 +38,7 @@ We recommend you provide users with separate input fields with these components When building an integration, we recommend you expose certain metadata in the request for analytics purposes. Among other items, it is helpful to have the following: - Your application's name (such as 'Tableau') -- The user email of the person querying from your application +- The email of the person querying your application - The version of dbt they are on. From af3b12b3e3c0d2bf6479053568a066bd9b1f793d Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Wed, 25 Oct 2023 11:27:27 +0100 Subject: [PATCH 5/9] Update website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md --- .../docs/guides/dbt-ecosystem/sl-partner-integration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md b/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md index 6c1751264cc..5b75498a4fd 100644 --- a/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md +++ b/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md @@ -93,7 +93,7 @@ Allow users to query either one metric alone without dimensions or multiple metr - Allow toggling between metrics/dimensions seamlessly. -- Be clear on exposing what dimensions are queryable with what metrics and hide things that don’t apply(our APIs provide calls for you to get relevant dimensions for metrics, and vice versa). +- Be clear on exposing what dimensions are queryable with what metrics and hide things that don’t apply. (Our APIs provide calls for you to get relevant dimensions for metrics, and vice versa). - Only expose time granularities (monthly, daily, yearly) that match the available metrics. * For example, if a dbt model and its resulting semantic model have a monthly granularity, make sure querying data with a 'daily' granularity isn't available to the user. Our APIs have functionality that will help you surface the correct granularities From 8a6abbb1fd3a05a4651dba603a01a57bccc20a4f Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Wed, 25 Oct 2023 11:27:40 +0100 Subject: [PATCH 6/9] Update website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md --- .../docs/guides/dbt-ecosystem/sl-partner-integration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md b/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md index 5b75498a4fd..bf40d43a8f0 100644 --- a/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md +++ b/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md @@ -117,7 +117,7 @@ For better analysis, it's best to have the context of the metrics close to where - Allow for creating other metadata that’s useful for the metric. We can provide some of this information in our configuration (Display name, Default Granularity for View, Default Time range), but there may be other metadata that your tool wants to provide to make the metric richer. -### Transparency and Using Compile +### Transparency and using compile For transparency and additional context, we recommend you have an easy way for the user to obtain the SQL that MetricFlow generates. Depending on what API you are using, you can do this by using our compile parameter. This is incredibly powerful because we want to be very transparent to the user about what we're doing and do not want to be a black box. This would be mostly beneficial to a technical user. From 2ed88fb71b14af5d6552b01c9b89eee758bff3a9 Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Wed, 25 Oct 2023 11:30:13 +0100 Subject: [PATCH 7/9] Update website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md --- .../docs/guides/dbt-ecosystem/sl-partner-integration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md b/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md index bf40d43a8f0..4f0f974ecf6 100644 --- a/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md +++ b/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md @@ -119,7 +119,7 @@ For better analysis, it's best to have the context of the metrics close to where ### Transparency and using compile -For transparency and additional context, we recommend you have an easy way for the user to obtain the SQL that MetricFlow generates. Depending on what API you are using, you can do this by using our compile parameter. This is incredibly powerful because we want to be very transparent to the user about what we're doing and do not want to be a black box. This would be mostly beneficial to a technical user. +For transparency and additional context, we recommend you have an easy way for the user to obtain the SQL that MetricFlow generates. Depending on what API you are using, you can do this by using our `compile` parameter. This is incredibly powerful and emphasizes transparency and openness, particularly for technically inclined users. ### Where filters and Optimization From 2212c4893191eed9041fc406034d40d48cd6ad95 Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Wed, 25 Oct 2023 11:30:39 +0100 Subject: [PATCH 8/9] Update website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md --- .../docs/guides/dbt-ecosystem/sl-partner-integration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md b/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md index 4f0f974ecf6..b8041a5d197 100644 --- a/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md +++ b/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md @@ -122,7 +122,7 @@ For better analysis, it's best to have the context of the metrics close to where For transparency and additional context, we recommend you have an easy way for the user to obtain the SQL that MetricFlow generates. Depending on what API you are using, you can do this by using our `compile` parameter. This is incredibly powerful and emphasizes transparency and openness, particularly for technically inclined users. -### Where filters and Optimization +### Where filters and optimization In the cases where our APIs support either a string or a filter list for the `where` clause, we always recommend that your application utilizes the filter list in order to gain maximum pushdown benefits. The `where` string may be more intuitive for users writing queries during testing, but it will not have the performance benefits of the filter list in a production environment. From 69c13e39fb1908edbf91aa77cebdf6b9fdc83153 Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Wed, 25 Oct 2023 11:46:29 +0100 Subject: [PATCH 9/9] remove callout --- .../docs/guides/dbt-ecosystem/sl-partner-integration-guide.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md b/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md index b8041a5d197..6cc32a4c836 100644 --- a/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md +++ b/website/docs/guides/dbt-ecosystem/sl-partner-integration-guide.md @@ -5,10 +5,6 @@ description: Learn about partner integration guidelines, roadmap, and connectivi --- -import NewChanges from '/snippets/_new-sl-changes.md'; - - - To fit your tool within the world of the Semantic Layer, dbt Labs offers some best practice recommendations for how to expose metrics and allow users to interact with them seamlessly. :::note