diff --git a/website/docs/docs/dbt-cloud-apis/sl-jdbc.md b/website/docs/docs/dbt-cloud-apis/sl-jdbc.md index 45b012c67c6..345be39635e 100644 --- a/website/docs/docs/dbt-cloud-apis/sl-jdbc.md +++ b/website/docs/docs/dbt-cloud-apis/sl-jdbc.md @@ -165,17 +165,17 @@ select * from {{ ## Querying the API for metric values -To query metric values, here are the following parameters that are available: +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 | Type | -| --------- | -----------| ------------ | -------------------- | -| `metrics` | The metric name as defined in your dbt metric configuration | `metrics=['revenue']` | Required | -| `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']` | Optional | -| `grain` | A parameter specific to any time dimension and changes the grain of the data from the default for the metric. | `group_by=[Dimension('metric_time')`
`grain('week\|day\|month\|quarter\|year')]` | Optional | -| `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')"` | Optional | -| `limit` | Limit the data returned | `limit=10` | Optional | -|`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)`] | Optional | -| `compile` | If true, returns generated SQL for the data platform but does not execute | `compile=True` | Optional | +| 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']` | +| `grain` | A parameter specific to any time dimension and changes the grain of the data from the default for the metric. | `group_by=[Dimension('metric_time')`
`grain('week\|day\|month\|quarter\|year')]` | +| `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` | @@ -248,6 +248,16 @@ select * from {{ }} ``` +### Query only a dimension + +In this case, you'll get the full list of dimension values for the chosen dimension. + +```bash +select * from {{ + semantic_layer.query(group_by=['customer__customer_type']) + }} +``` + ### Query with where filters Where filters in API allow for a filter list or string. We recommend using the filter list for production applications as this format will realize all benefits from the where possible. diff --git a/website/docs/guides/sl-partner-integration-guide.md b/website/docs/guides/sl-partner-integration-guide.md index 04f58f525bd..61d558f504d 100644 --- a/website/docs/guides/sl-partner-integration-guide.md +++ b/website/docs/guides/sl-partner-integration-guide.md @@ -39,11 +39,14 @@ We recommend you provide users with separate input fields with these components ### 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: +When building an integration, we recommend you expose certain metadata in the request for analytics and troubleshooting purpose. + +Please send us the following header with every query: + +`'X-dbt-partner-source': 'Your-Application-Name'` + +Additionally, it would be helpful if you also included the email and username of the person generating the query from your application. -- Your application's name (such as 'Tableau') -- The email of the person querying your application -- The version of dbt they are on. ## Use best practices when exposing metrics