Skip to main content

Query Datasource

Available June 2026 and later.

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:read OAuth 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/MATCH filter values against the data source — so a malformed query can self-heal. Skipped when DISABLE_QUERY_DATASOURCE_VALIDATION_REQUESTS is set. Issued against the VizQL Data Service (VDS) API; requires the tableau:viz_data_service:read OAuth scope.
    • POST /api/v1/vizql-data-service/read-metadata — read field and parameter metadata to validate the query against the data source. Read Metadata
    • POST /api/v1/vizql-data-service/query-datasource — sample the field's values to validate SET and MATCH filter 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:read and tableau:mcp_site_settings:read OAuth 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.
  • CONDITION filters 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​

Query validation

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_REQUESTS

    The query-datasource tool 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.