Skip to content

Update from code changes: document user attribute query tags #969

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.

Sign up for GitHub

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

Open
mintlify wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update from code changes: document user attribute query tags #969

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 28 additions & 9 deletions references/workspace/usage-analytics.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,15 +54,34 @@ Query tags are metadata which is added to your data warehouse queries and gives

The following query tags are sent:

| Query Tag | Detail |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| organization_uuid | Lightdash organization unique identifier. |
| project_uuid | Lightdash project unique identifier. |
| user_uuid | User unique identifier. |
| dashboard_uuid | Dashboard unique identifier. |
| chart_uuid | Chart unique identifier. |
| explore_name | Name of the explore. |
| query_context | Which context the query was executed in. <br /><br />For queries in: <br />- dashboards use `dashboardView` <br />- explore use `exploreView`<br />- chart use `chartView`<br />- sql chart use `sqlChartView` |
| Query Tag | Detail |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| organization_uuid | Lightdash organization unique identifier. |
| project_uuid | Lightdash project unique identifier. |
| user_uuid | User unique identifier. |
| dashboard_uuid | Dashboard unique identifier. |
| chart_uuid | Chart unique identifier. |
| explore_name | Name of the explore. |
| query_context | Which context the query was executed in. <br /><br />For queries in: <br />- dashboards use `dashboardView` <br />- explore use `exploreView`<br />- chart use `chartView`<br />- sql chart use `sqlChartView` |
| user_attribute_`<name>` | One tag per [user attribute](/references/workspace/user-attributes) value assigned to the querying user. Applies to both regular users and embed viewers, and requires no configuration. |

### User attribute tags

For every query, Lightdash emits an extra `user_attribute_<name>` tag for each user attribute value assigned to the user running the query. This makes it possible to attribute warehouse cost, audit access, or debug row-level-security by user attribute directly from your warehouse's query history.

- Tags are emitted alongside the standard query tags for both signed-in users and embed viewers (using the attributes passed on the embed token).
- Values are carried through async query execution end-to-end, so they appear on the actual warehouse job (for example, as labels on a BigQuery job).
- Keys and values are sanitized to match warehouse tag constraints — lower-cased, restricted to `a-z 0-9 _ -`, and truncated if too long. Invalid or oversized metadata is sanitized rather than blocking the query.
- No configuration is required — user attribute tags are emitted automatically wherever query tags are already supported.

For example, a user with the `region` attribute set to `emea` and `customer_tier` set to `enterprise` will produce these additional tags on every warehouse query they trigger:

```text
user_attribute_region=emea
user_attribute_customer_tier=enterprise
```

You can then filter your warehouse's query or job history by these tags (for example, `labels.user_attribute_region = "emea"` in BigQuery) to break down usage or cost by user attribute.

Query tags are stored differently in each data warehouse:

Expand Down
Loading