Query Datasource
Executes VizQL queries against a published Tableau data source to answer business questions from your data. The tool is read-only: it runs the query you supply and returns the resulting rows.
APIs called
This tool runs its queries against the VizQL Data Service (VDS) API (served by Tableau Cloud or
Tableau Server), and — only when tool scoping restricts which data sources may be queried — reads
data source details from the Tableau REST API. The MCP-layer gate requires the
tableau:mcp:datasource:read scope.
- Runs the supplied query against the data source and returns the result rows. Issued against the
VizQL Data Service (VDS) API; requires the
tableau:viz_data_service:readOAuth scope.POST /api/v1/vizql-data-service/query-datasource— execute the query and return the data. Query Data Source
- Validates the query before running it — checking fields, parameters, and
SET/MATCHfilter values against the data source — so a malformed query can self-heal. Skipped whenDISABLE_QUERY_DATASOURCE_VALIDATION_REQUESTSis set. Issued against the VizQL Data Service (VDS) API; requires thetableau:viz_data_service:readOAuth scope.POST /api/v1/vizql-data-service/read-metadata— read field and parameter metadata to validate the query against the data source. Read MetadataPOST /api/v1/vizql-data-service/query-datasource— sample the field's values to validateSETandMATCHfilter values. Query Data Source
- Confirms the requested data source is within the configured
tool scoping bounded context, only when project
or tag scoping is configured. Issued against the Tableau REST API; requires the
tableau:content:readandtableau:mcp_site_settings:readOAuth scopes.GET /api/{version}/sites/{siteId}/datasources/{datasourceId}— fetch the data source to check its project and tags. Query Data Source
Required arguments
datasourceLuid
The LUID of the data source, potentially retrieved by the List Data Sources tool.
Example
2d935df8-fe7e-4fd8-bb14-35eb4ba31d45
query
The VizQL query to execute against the data source. See Create a Query for more information.
Some query features need a recent Tableau version. The tool rejects them on earlier versions with an error that names the version they need:
- Table calculation fields (
tableCalculation) require Tableau 2025.3 or later. CONDITIONfilters require Tableau 2026.1 or later.
Example
{
"fields": [
{
"fieldCaption": "Customer Name"
},
{
"fieldCaption": "Sales",
"function": "SUM",
"fieldAlias": "Total Revenue",
"sortDirection": "DESC",
"sortPriority": 1
}
],
"filters": [
{
"field": {
"fieldCaption": "Customer Name"
},
"filterType": "TOP",
"howMany": 5,
"direction": "TOP",
"fieldToMeasure": {
"fieldCaption": "Sales",
"function": "SUM"
}
}
]
}
Optional arguments
limit
The maximum number of rows to return. The tool returns at most this many rows. Range: 1- (a
positive integer). When MAX_RESULT_LIMIT
is configured, the effective cap is the smaller of that limit and this value.
See also: MAX_RESULT_LIMIT
Example
2000
Notes and caveats
Before running the query, the tool may issue additional VizQL Data Service requests to validate
inputs such as string filter values and the semantic accuracy of the generated query. Setting
DISABLE_QUERY_DATASOURCE_VALIDATION_REQUESTS
disables those supplementary calls. We do not recommend turning them off: they help an agent
self-heal from malformed queries and produce more accurate answers from your data.
Example result
{
"data": [
{
"Customer Name": "Sean Miller",
"Total Revenue": 25043.05
},
{
"Customer Name": "Tamara Chand",
"Total Revenue": 19052.217999999997
},
{
"Customer Name": "Raymond Buch",
"Total Revenue": 15117.338999999998
},
{
"Customer Name": "Tom Ashbrook",
"Total Revenue": 14595.62
},
{
"Customer Name": "Adrian Barton",
"Total Revenue": 14473.571
}
]
}
Environment variables
-
DISABLE_QUERY_DATASOURCE_VALIDATION_REQUESTSThe
query-datasourcetool may issue additional VizQL Data Service and Metadata API requests to validate inputs such as string filter values and the semantic accuracy of the generated query. Setting this variable disables those supplementary calls. We do not recommend turning them off: they help an agent self-heal from malformed queries and produce more accurate answers from your data.
Embedded (workbook) data sources
Besides published data sources, this tool can query a data source embedded in a workbook — pass the
embedded data source's datasourceLuid (e.g. a connection's datasource ID from
Get Workbook). A few caveats apply:
- Site opt-in: a site administrator must enable querying of workbook (embedded) data sources on the Tableau site, otherwise the query returns a "not enabled" error.
- Permissions: an embedded data source has no permissions of its own — it inherits those of its
containing workbook, so you need view/query access to that workbook.
Get Workbook reports this up front as
queryability.isQueryable. - Version: requires Tableau 2026.3+ (REST API 3.30 or later); published data sources are unaffected.
- Tool scoping: when tool scoping limits which workbooks are visible, the workbook that contains the embedded data source has to be included.
Warnings
The tool validates the query for a common pitfall: combining a TOP/BOTTOM filter with one or
more dimension filters (SET, DATE, MATCH, or a non-aggregated QUANTITATIVE_NUMERICAL/
QUANTITATIVE_DATE filter) that don't set context: true. In Tableau's query order of
operations, TOP/BOTTOM filters are evaluated before regular dimension filters, so the TOP
filter selects from the full dataset first and the dimension filters are applied afterward — this
can produce fewer results than expected (e.g. 8 rows when requesting Top 10), because some of the
top-ranked values may not exist in the filtered subset.
When this pattern is detected, the result includes a non-blocking mcp.warnings array (the query
still executes and returns data):
{
"data": [ /* ... */ ],
"mcp": {
"warnings": [
{
"type": "MISSING_CONTEXT_ON_DIMENSION_FILTER",
"severity": "WARNING",
"message": "This query combines a TOP/BOTTOM filter with dimension filters that are not set as context filters. ...",
"affectedFilters": ["Region"]
}
]
}
}
If the intent is to find the Top values within the filtered subset, add "context": true to
the affected dimension filter(s). If the intent is to find the Top values globally and then
filter them, no change is needed — the warning can be ignored.