Request Data Source Metadata

🕐 2 min read

Get the data structure in the data source

The Request data source metadata method provides you with information about the queryable fields in a data source. This method requires that you pass in the data source object, which could be the datasourceLuid for a published data source, or the workbookDatasourceId for a workbook data source. To find the datasourceLuid, see Find the data source LUID.

{
    "datasource": {
        "datasourceLuid": "1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b",
    }
}

For a workbook data source, you must specify the workbookDatasourceId, and also include the session ID and the global session header (for Tableau Cloud) in the request headers. For instructions, see Find the workbook session ID and workbook data source ID.

{
    "datasource": {
        "workbookDatasourceId": "federated.1a2b3c4d5e6f7g8h9i1j2k3l4m5n"
    }
}

The request has the following options:

bypassMetadataCache: Set to true if either the published data source or the underlying database has changed within your current session. When set to true, VizQL Data Service (VDS) refreshes the metadata. Note that VDS automatically invalidates the cache when the data source is republished. Use this option if your underlying database has changed.
withNewSession: Set to true to request a new session. Clears the cached session for the user before a new session is created.
interpretFieldCaptionsAsFieldNames: When set to true, the response returns the fieldName value everywhere the fieldCaption is used. This is also true for parameters. For example, if you set this field to true, the response returns, for example, Parameter 2 instead of Profit Bin Size.
includeHiddenFields: When set to true, the response shows hidden fields.
includeGroupFormulas: When set to true, the response shows the group information for fields that are categorical bins.

Request data source metadata response

This API method returns two objects: data and extraData.

The data object returns these fields:

fieldName: The underlying field name on the data source.
fieldCaption: The fieldCaption is what you must pass into a query. This is often the same as fieldName.
dataType: Either INTEGER, REAL, STRING, DATETIME, BOOLEAN, DATE, SPATIAL, or UNKNOWN.
fieldRole: Either MEASURE or DIMENSION.
fieldType: Either NOMINAL, ORDINAL, or CONTINUOUS. NOMINAL and ORDINAL are subtypes of DISCRETE.
defaultAggregation: The default aggregation applied to the field.
columnClass: The type of field. Either COLUMN, BIN, GROUP, CALCULATION, or TABLE_CALCULATION.
formula: The formula for this field if it’s a calculation.
groupFormula: When includeGroupFormulas is set to true and the field is a categorical bin, the response shows group information (groupFormula). The group formula includes the baseFieldName, and the groupings, an array of objects defined by the group formula. Each group object includes the name of group (alias) and list of members that belong to the group. If hasIncludeOther is true (the Include ‘Other’ option was selected in the Edit Group dialog box), all domain values not specified in a grouping will be grouped together. If set (true), the response could return a large amount of data. The default setting is false.
logicalTableId: If you have a data model with more than one logical table, this tells you which table the field originated from.
description: The description of the field (what appears under the Lineage tab for the data source) if you have enabled data catalog.
imageRole: The value URL indicates whether the field is assigned an image role.
hidden: Indicates whether the field is hidden (true) or not (false).
defaultFormatting: Describes the default formatting for the field. The value of decimalPlaces indicates the number of decimal places used for the field.
isLODCalc: Indicates whether the calculation contains a level of detail (LOD) expression.
aliases: An array of aliases for fields. Each alias shows the original name (member) and it’s alias (value).

The extraData object returns a parameters object with these fields:

parameterType: Either ANY_VALUE (accepts any value without restrictions), LIST (a set number of values from which you can choose), QUANTITATIVE_DATE (a date range with specified minimum, maximum, and granularity settings), QUANTITATIVE_RANGE (a numeric range with specified minimum, maximum, and step values), or ALL (no restrictions).
parameterName: The internal name defined by Tableau.
parameterCaption: The user-defined name of the parameter to identify and reference the parameter.
dataType: Either INTEGER, REAL, STRING, DATETIME, BOOLEAN, and DATE, SPATIAL, UNKNOWN
value: The default value for the parameter.
min: The maximum value for the range.
max: The minimum value for the range.
step: The jumps between values.

Note:

DATETIME and SPATIAL are currently not supported parameter dataType values.
Date type parameters for using range controls don't support step size validation when configured with ISO Years, ISO Quarters, or ISO Weeks (all ISO period types).

Example responses

A bin on the data source

{
    "data": [
        {
            "fieldName": "Profit (bin)",
            "fieldCaption": "Profit (bin)",
            "dataType": "INTEGER",
            "fieldRole": "DIMENSION",
            "fieldType": "ORDINAL",
            "defaultAggregation": "NONE",
            "columnClass": "BIN",
            "logicalTableId": "Orders_ECFCA1FB690A41FE803BC071773BA862",
            "formula": "SYS_NUMBIN([Profit],[Profit Bin Size])",
        }
    ]
}

A group on the data source

This example response shows the groupForumula, which is included when the includeGroupForumulas option is set to true. This example doesn’t show all the groupings that would be shown in the response, or all of the other fields.

{
    "data": [
        {
            "fieldName": "Product Name (group)",
            "fieldCaption": "Manufacturer",
            "dataType": "STRING",
            "fieldRole": "DIMENSION",
            "fieldType": "NOMINAL",
            "defaultAggregation": "COUNT",
            "columnClass": "GROUP",
            "groupFormula": {
                "baseFieldName": "Product Name",
                "groupings": [
                    {
                        "alias": "3D Systems",
                        "members": [
                            "3D Systems Cube Printer, 2nd Generation, Magenta",
                            "3D Systems Cube Printer, 2nd Generation, White"
                        ]
                    },
                    {
                        "alias": "3M",
                        "members": [
                            "3M Hangers With Command Adhesive",
                            "3M Office Air Cleaner",
                            "3M Organizer Strips",
                            "3M Polarizing Light Filter Sleeves",
                            "3M Polarizing Task Lamp with Clamp Arm, Light Gray",
                            "3M Replacement Filter for Office Air Cleaner for 20' x 33' Room"
                        ]
                    }  
                ],
               "hasIncludeOther": true
            },
            "logicalTableId": "Orders_ECFCA1FB690A41FE803BC071773BA862",
            "hidden": false
        }
    ]
}

A calculation on the data source

{
    "data": [
        {
            "fieldName": "Calculation_1368249927221915648",
            "fieldCaption": "Profit Ratio",
            "dataType": "REAL",
            "fieldRole": "MEASURE",
            "fieldType": "CONTINUOUS",
            "defaultAggregation": "AGG",
            "columnClass": "CALCULATION",
            "isLODCalc": false,
            "formula": "SUM([Profit])/SUM([Sales])"
        }
    ]
}

Full example from the Superstore data source

{
    "data": [
        {
            "fieldName": "Category",
            "fieldCaption": "Category",
            "dataType": "STRING",
            "fieldRole": "DIMENSION",
            "fieldType": "NOMINAL",
            "defaultAggregation": "COUNT",
            "columnClass": "COLUMN",
            "logicalTableId": "Orders_ECFCA1FB690A41FE803BC071773BA862",
            "description": "This is the *Category*."
        },
        {
            "fieldName": "Discount",
            "fieldCaption": "Discount",
            "dataType": "REAL",
            "fieldRole": "MEASURE",
            "fieldType": "CONTINUOUS",
            "defaultAggregation": "SUM",
            "columnClass": "COLUMN",
            "logicalTableId": "Orders_ECFCA1FB690A41FE803BC071773BA862"
        },
        {
            "fieldName": "Regional Manager",
            "fieldCaption": "Regional Manager",
            "dataType": "STRING",
            "fieldRole": "UNKNOWN",
            "fieldType": "UNKNOWN",
            "defaultAggregation": "COUNT",
            "columnClass": "COLUMN",
            "logicalTableId": "People_D73023733B004CC1B3CB1ACF62F4A965"
        },
        {
            "fieldName": "Ship Date",
            "fieldCaption": "Ship Date",
            "dataType": "DATE",
            "fieldRole": "DIMENSION",
            "fieldType": "ORDINAL",
            "defaultAggregation": "YEAR",
            "columnClass": "COLUMN",
            "logicalTableId": "Orders_ECFCA1FB690A41FE803BC071773BA862"
        },
        {
            "fieldName": "Sub-Category",
            "fieldCaption": "Sub-Category",
            "dataType": "STRING",
            "fieldRole": "DIMENSION",
            "fieldType": "NOMINAL",
            "defaultAggregation": "COUNT",
            "columnClass": "COLUMN",
            "logicalTableId": "Orders_ECFCA1FB690A41FE803BC071773BA862"
        },
        {
            "fieldName": "Profit (bin)",
            "fieldCaption": "Profit (bin)",
            "dataType": "INTEGER",
            "fieldRole": "DIMENSION",
            "fieldType": "ORDINAL",
            "defaultAggregation": "NONE",
            "columnClass": "BIN",
            "logicalTableId": "Orders_ECFCA1FB690A41FE803BC071773BA862",
            "formula": "SYS_NUMBIN([Profit],[Profit Bin Size])"
        },
        {
            "fieldName": "Segment",
            "fieldCaption": "Segment",
            "dataType": "STRING",
            "fieldRole": "DIMENSION",
            "fieldType": "NOMINAL",
            "defaultAggregation": "COUNT",
            "columnClass": "COLUMN",
            "logicalTableId": "Orders_ECFCA1FB690A41FE803BC071773BA862"
        },
        {
            "fieldName": "Sales",
            "fieldCaption": "Sales",
            "dataType": "REAL",
            "fieldRole": "MEASURE",
            "fieldType": "CONTINUOUS",
            "defaultAggregation": "SUM",
            "columnClass": "COLUMN",
            "logicalTableId": "Orders_ECFCA1FB690A41FE803BC071773BA862"
        },
        {
            "fieldName": "Product Name (group)",
            "fieldCaption": "Manufacturer",
            "dataType": "STRING",
            "fieldRole": "DIMENSION",
            "fieldType": "NOMINAL",
            "defaultAggregation": "COUNT",
            "columnClass": "GROUP",
            "logicalTableId": "Orders_ECFCA1FB690A41FE803BC071773BA862"
        },
        {
            "fieldName": "Ship Mode",
            "fieldCaption": "Ship Mode",
            "dataType": "STRING",
            "fieldRole": "DIMENSION",
            "fieldType": "NOMINAL",
            "defaultAggregation": "COUNT",
            "columnClass": "COLUMN",
            "logicalTableId": "Orders_ECFCA1FB690A41FE803BC071773BA862"
        },
        {
            "fieldName": "Order Date",
            "fieldCaption": "Order Date",
            "dataType": "DATE",
            "fieldRole": "DIMENSION",
            "fieldType": "ORDINAL",
            "defaultAggregation": "YEAR",
            "columnClass": "COLUMN",
            "logicalTableId": "Orders_ECFCA1FB690A41FE803BC071773BA862"
        },
        {
            "fieldName": "Profit",
            "fieldCaption": "Profit",
            "dataType": "REAL",
            "fieldRole": "MEASURE",
            "fieldType": "CONTINUOUS",
            "defaultAggregation": "SUM",
            "columnClass": "COLUMN",
            "logicalTableId": "Orders_ECFCA1FB690A41FE803BC071773BA862"
        },
        {
            "fieldName": "Calculation_1368249927221915648",
            "fieldCaption": "Profit Ratio",
            "dataType": "REAL",
            "fieldRole": "MEASURE",
            "fieldType": "CONTINUOUS",
            "defaultAggregation": "AGG",
            "columnClass": "CALCULATION",
            "isLODCalc": false,
            "formula": "SUM([Profit])/SUM([Sales])"
        },
        {
            "fieldName": "Customer Name",
            "fieldCaption": "Customer Name",
            "dataType": "STRING",
            "fieldRole": "DIMENSION",
            "fieldType": "NOMINAL",
            "defaultAggregation": "COUNT",
            "columnClass": "COLUMN",
            "logicalTableId": "Orders_ECFCA1FB690A41FE803BC071773BA862"
        },
        {
            "fieldName": "Returned",
            "fieldCaption": "Returned",
            "dataType": "STRING",
            "fieldRole": "DIMENSION",
            "fieldType": "NOMINAL",
            "defaultAggregation": "COUNT",
            "columnClass": "COLUMN",
            "logicalTableId": "Returns_2AA0FE4D737A4F63970131D0E7480A03"
        },
        {
            "fieldName": "Postal Code",
            "fieldCaption": "Postal Code",
            "dataType": "STRING",
            "fieldRole": "DIMENSION",
            "fieldType": "ORDINAL",
            "defaultAggregation": "COUNT",
            "columnClass": "COLUMN",
            "logicalTableId": "Orders_ECFCA1FB690A41FE803BC071773BA862"
        },
        {
            "fieldName": "Order ID",
            "fieldCaption": "Order ID",
            "dataType": "STRING",
            "fieldRole": "DIMENSION",
            "fieldType": "NOMINAL",
            "defaultAggregation": "COUNT",
            "columnClass": "COLUMN",
            "logicalTableId": "Orders_ECFCA1FB690A41FE803BC071773BA862"
        },
        {
            "fieldName": "Product Name",
            "fieldCaption": "Product Name",
            "dataType": "STRING",
            "fieldRole": "DIMENSION",
            "fieldType": "NOMINAL",
            "defaultAggregation": "COUNT",
            "columnClass": "COLUMN",
            "logicalTableId": "Orders_ECFCA1FB690A41FE803BC071773BA862"
        },
        {
            "fieldName": "Quantity",
            "fieldCaption": "Quantity",
            "dataType": "INTEGER",
            "fieldRole": "MEASURE",
            "fieldType": "CONTINUOUS",
            "defaultAggregation": "SUM",
            "columnClass": "COLUMN",
            "logicalTableId": "Orders_ECFCA1FB690A41FE803BC071773BA862"
        },
        {
            "fieldName": "City",
            "fieldCaption": "City",
            "dataType": "STRING",
            "fieldRole": "DIMENSION",
            "fieldType": "NOMINAL",
            "defaultAggregation": "COUNT",
            "columnClass": "COLUMN",
            "logicalTableId": "Orders_ECFCA1FB690A41FE803BC071773BA862"
        },
        {
            "fieldName": "State/Province",
            "fieldCaption": "State/Province",
            "dataType": "STRING",
            "fieldRole": "DIMENSION",
            "fieldType": "NOMINAL",
            "defaultAggregation": "COUNT",
            "columnClass": "COLUMN",
            "logicalTableId": "Orders_ECFCA1FB690A41FE803BC071773BA862"
        },
        {
            "fieldName": "Region",
            "fieldCaption": "Region",
            "dataType": "STRING",
            "fieldRole": "DIMENSION",
            "fieldType": "NOMINAL",
            "defaultAggregation": "COUNT",
            "columnClass": "COLUMN",
            "logicalTableId": "Orders_ECFCA1FB690A41FE803BC071773BA862"
        },
        {
            "fieldName": "Country/Region",
            "fieldCaption": "Country/Region",
            "dataType": "STRING",
            "fieldRole": "DIMENSION",
            "fieldType": "NOMINAL",
            "defaultAggregation": "COUNT",
            "columnClass": "COLUMN",
            "logicalTableId": "Orders_ECFCA1FB690A41FE803BC071773BA862"
        }
    ],
    "extraData": {
        "parameters": [
            {
                "parameterType": "QUANTITATIVE_RANGE",
                "parameterName": "Parameter 1",
                "parameterCaption": "Top Customers",
                "dataType": "INTEGER",
                "value": 5.0,
                "min": 5.0,
                "max": 20.0,
                "step": 5.0
            },
            {
                "parameterType": "QUANTITATIVE_RANGE",
                "parameterName": "Parameter 2",
                "parameterCaption": "Profit Bin Size",
                "dataType": "INTEGER",
                "value": 200.0,
                "min": 50.0,
                "max": 200.0,
                "step": 50.0
            }
        ]
    }
}