From d99385b74dbddacbed13ad1729b0ea27a6adac90 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Fri, 10 Jul 2026 00:44:07 +0000
Subject: [PATCH] docs: document user attribute query tags
---
references/workspace/usage-analytics.mdx | 37 ++++++++++++++++++------
1 file changed, 28 insertions(+), 9 deletions(-)
diff --git a/references/workspace/usage-analytics.mdx b/references/workspace/usage-analytics.mdx
index 3deb0957..c87b3b19 100644
--- a/references/workspace/usage-analytics.mdx
+++ b/references/workspace/usage-analytics.mdx
@@ -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.
For queries in:
- dashboards use `dashboardView`
- explore use `exploreView`
- chart use `chartView`
- 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.
For queries in:
- dashboards use `dashboardView`
- explore use `exploreView`
- chart use `chartView`
- sql chart use `sqlChartView` |
+| user_attribute_`` | 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_` 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: