Skip to content

Document all query tags including MCP and AI contexts #1100

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

Merged
jpetey75 merged 1 commit into from
Aug 12, 2026
Merged

Document all query tags including MCP and AI contexts #1100

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
62 changes: 52 additions & 10 deletions references/workspace/usage-analytics.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,16 +54,58 @@ 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` |
| 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. |
| Query Tag | Detail |
| :----------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| organization_uuid | Lightdash organization unique identifier. |
| project_uuid | Lightdash project unique identifier. |
| user_uuid | User unique identifier for the user that triggered the query. |
| explore_name | Name of the explore the query was run against. |
| chart_uuid | Chart unique identifier. Only set when the query originates from a saved chart. |
| dashboard_uuid | Dashboard unique identifier. Only set when the query originates from a dashboard. |
| saved_sql_uuid | Saved SQL chart unique identifier. Only set when a scheduled job is running a saved SQL chart. |
| scheduler_uuid | Scheduler unique identifier. Only set when the query is triggered by a scheduled delivery, alert, or Google Sheets sync. |
| scheduler_name | Human-readable name of the scheduler. Only set when the query is triggered by a scheduler. |
| job_id | Scheduler job identifier for a single run of a scheduler. Only set when the query is triggered by a scheduler. |
| app_uuid | Identifier of the external app that originated the request, taken from the app attribution header. Self-reported by the caller and used for attribution only. |
| query_context | Which context the query was executed in. See [Query contexts](#query-contexts) below for the full list of values. |
| 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. |

### Query contexts

The `query_context` tag identifies which surface triggered the query. Possible values:

| Value | Where the query came from |
| :----------------------------- | :------------------------------------------------------------------------------------------- |
| `dashboardView` | Viewing a dashboard. |
| `autorefreshedDashboard` | Dashboard auto-refresh tick. |
| `exploreView` | Running a query from the explore view. |
| `chartView` | Viewing a saved chart. |
| `chartHistory` | Viewing a chart's version history. |
| `sqlChartView` | Viewing a saved SQL chart. |
| `sqlRunner` | Running a query from the SQL runner. |
| `viewUnderlyingData` | Viewing the underlying data behind a result cell. |
| `filterAutocomplete` | Autocomplete lookups for filter values. |
| `calculateTotal` | Calculating a column total. |
| `calculateSubtotal` | Calculating a group subtotal. |
| `metricsExplorer` | Queries from the Metrics Explorer. |
| `csvDownload` | CSV export of query results. |
| `gsheets` | Ad-hoc Google Sheets export. |
| `alert` | Scheduled alert evaluating its condition. |
| `scheduledDelivery` | Scheduled delivery running. |
| `scheduledChart` | Scheduled chart delivery. |
| `scheduledDashboard` | Scheduled dashboard delivery. |
| `scheduledGsheetsChart` | Scheduled Google Sheets sync for a chart. |
| `scheduledGsheetsDashboard` | Scheduled Google Sheets sync for a dashboard. |
| `scheduledGsheetsSqlChart` | Scheduled Google Sheets sync for a SQL chart. |
| `preAggregateMaterialization` | Building a pre-aggregate materialization. |
| `embed` | Query from an [embedded](/references/embedding) chart or dashboard. |
| `api` | Query issued through the Lightdash HTTP API. |
| `cli` | Query issued through the [Lightdash CLI](/references/lightdash-cli). |
| `ai` | Query issued by a [Lightdash AI agent](/guides/ai-agents/getting-started). |
| `mcp.run_metric_query` | `run_metric_query` tool call from the [Lightdash MCP server](/guides/ai-agents/mcp-servers). |
| `mcp.run_sql` | `run_sql` tool call from the Lightdash MCP server. |
| `mcp.search_field_values` | `search_field_values` tool call from the Lightdash MCP server. |
| `dataAppSample` | Sample query issued when previewing a data app. |

### User attribute tags

Expand Down
Loading