Skip to main content

Get Datasource Metadata

Fetches datasource metadata for the specified datasource, including:

  • datasource description
  • datasource model relationships (when available)
  • fields grouped by logicalTableId
  • Tableau parameters

APIs called​

Environment variables​

Required arguments​

datasourceLuid​

The LUID of the data source, potentially retrieved by the List Data Sources tool.

Example: 2d935df8-fe7e-4fd8-bb14-35eb4ba31d45

Optional arguments​

workbookLuid​

The LUID of the workbook an embedded (workbook) data source belongs to, potentially retrieved by the Get Workbook tool. Required to access an embedded data source when tool scoping is enabled. Ignored for published data sources.

Example: 222ea993-9391-4910-a167-56b3d19b4e3b

Embedded (workbook) data sources​

Besides published data sources, this tool can fetch metadata for 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 request 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 is enabled, also pass workbookLuid.

Optional field selectors​

  • fieldNames: a nonempty array of exact, case-sensitive field captions. All duplicate-caption matches are returned. These are captions, not VDS internal field names.
  • search: a nonblank, case-insensitive substring of a field's caption or description. Leading and trailing whitespace is trimmed. With fieldNames, both conditions must match.

For example, use fieldNames: ["Sales", "Order Date"] for known fields, or search: "revenue" to discover fields whose captions or descriptions contain that text. Selected fields retain their full metadata, including formulas and descriptions. Empty field groups are omitted.

Search is literal, so related fields and formula dependencies may not match. For broad discovery or uncertain terminology, omit selectors; fetch referenced fields when needed.

When either selector is supplied, mcp.resultInfo reports totalFields before selection, matchedFields after both selectors, and unknownFieldNames for requested captions absent from the datasource. A known caption excluded by search is not an unknown name. No matches produces empty fieldGroups.

Selectors only affect fields. Parameters, datasource descriptions and model relationships are returned unchanged. Filtering happens after upstream metadata is fetched; it reduces tool output, not upstream requests. There is no response-size cap. Omit both selectors for the existing full response without mcp.resultInfo.

Response shape​

Top-level keys are returned in this order:

  1. datasourceDescription
  2. datasourceModel (optional)
  3. fieldGroups
  4. parameters
  5. mcp (only when a field selector is supplied)

datasourceModel is available on Tableau versions that support the VDS get-datasource-model endpoint (2025.3+). On older versions, it is omitted.

Fields expose their display caption as name and, when available from VDS, their underlying query name as fieldName. Parameters similarly expose name and optional parameterName. If captions repeat across logical tables, choose the intended table and use its exact query names with query-datasource on Tableau 2025.3+. Metadata API-only fallback results do not include underlying query names.

Example result​

{
  "datasourceDescription": "Datasource metadata and usage notes...",
  "datasourceModel": {
    "logicalTables": [
      {
        "logicalTableId": "Orders_...",
        "caption": "Orders"
      },
      {
        "logicalTableId": "Returns_...",
        "caption": "Returns"
      }
    ],
    "logicalTableRelationships": [
      {
        "fromLogicalTable": { "logicalTableId": "Orders_..." },
        "toLogicalTable": { "logicalTableId": "Returns_..." },
        "expression": {
          "relationships": [
            {
              "operator": "=",
              "fromField": "[Order ID]",
              "toField": "[Order ID (Returns)]"
            }
          ]
        }
      }
    ]
  },
  "fieldGroups": [
    {
      "logicalTableId": "Orders_...",
      "fields": [
        {
          "name": "Order ID",
          "dataType": "STRING",
          "columnClass": "COLUMN",
          "logicalTableId": "Orders_...",
          "defaultAggregation": "COUNT",
          "dataCategory": "NOMINAL",
          "role": "DIMENSION"
        },
        {
          "name": "Sales",
          "dataType": "REAL",
          "columnClass": "COLUMN",
          "logicalTableId": "Orders_...",
          "defaultAggregation": "SUM",
          "dataCategory": "QUANTITATIVE",
          "role": "MEASURE"
        }
      ]
    },
    {
      "logicalTableId": null,
      "fields": [
        {
          "name": "CrossTable Calc",
          "dataType": "REAL",
          "columnClass": "CALCULATION",
          "logicalTableId": null,
          "defaultAggregation": "SUM",
          "formula": "[Sales] / NULLIF([Quantity], 0)"
        }
      ]
    }
  ],
  "parameters": [
    {
      "name": "Top Customers",
      "parameterType": "QUANTITATIVE_RANGE",
      "dataType": "INTEGER",
      "value": 5,
      "min": 5,
      "max": 20,
      "step": 5
    },
    {
      "name": "Profit Bin Size",
      "parameterType": "QUANTITATIVE_RANGE",
      "dataType": "INTEGER",
      "value": 200,
      "min": 50,
      "max": 200,
      "step": 50
    }
  ]
}