Skip to content

Commit

Permalink
integration-guide-and-jdbc-updates.md (#4670)
Browse files Browse the repository at this point in the history
Updating this per our recomendation of including partner-source

## What are you changing in this pull request and why?
<!---
Describe your changes and why you're making them. If linked to an open
issue or a pull request on dbt Core, then link to them here! 

To learn more about the writing conventions used in the dbt Labs docs,
see the [Content style
guide](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/content-style-guide.md).
-->

## Checklist
<!--
Uncomment if you're publishing docs for a prerelease version of dbt
(delete if not applicable):
- [ ] Add versioning components, as described in [Versioning
Docs](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#versioning-entire-pages)
- [ ] Add a note to the prerelease version [Migration
Guide](https://github.com/dbt-labs/docs.getdbt.com/tree/current/website/docs/docs/dbt-versions/core-upgrade)
-->
- [ ] Review the [Content style
guide](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/content-style-guide.md)
so my content adheres to these guidelines.
- [ ] For [docs
versioning](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#about-versioning),
review how to [version a whole
page](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#adding-a-new-version)
and [version a block of
content](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#versioning-blocks-of-content).
- [ ] Add a checklist item for anything that needs to happen before this
PR is merged, such as "needs technical review" or "change base branch."

Adding new pages (delete if not applicable):
- [ ] Add page to `website/sidebars.js`
- [ ] Provide a unique filename for the new page

Removing or renaming existing pages (delete if not applicable):
- [ ] Remove page from `website/sidebars.js`
- [ ] Add an entry `website/static/_redirects`
- [ ] Run link testing locally with `npm run build` to update the links
that point to the deleted page
  • Loading branch information
mirnawong1 authored Dec 19, 2023
2 parents eb5911c + 8214b79 commit fa3b9ff
Show file tree
Hide file tree
Showing 2 changed files with 27 additions and 14 deletions.
30 changes: 20 additions & 10 deletions website/docs/docs/dbt-cloud-apis/sl-jdbc.md
Original file line number Diff line number Diff line change
Expand Up @@ -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')` <br/> `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')` <br/> `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` |
Expand Down Expand Up @@ -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 <Term id="predicate-pushdown" /> where possible.
Expand Down
11 changes: 7 additions & 4 deletions website/docs/guides/sl-partner-integration-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit fa3b9ff

Please sign in to comment.