--- schema_version: "1" id: 939d6a019f0d3d23336bf6f24e6897776eac314524cf998b80e514be08e805b0 title: Request Data Source Metadata collection: tableau version: next locale: en-us portal_url: https://docs.salesforce.com/tableau/next/en-us/api/vizql-data-service/docs/vds_get_data_source_info.md canonical_url: https://help.tableau.com/v0.0/api/vizql-data-service/en-us/docs/vds_get_data_source_info.html source_site: help.tableau.com content_type: documentation content_hash: b5e4318e65c22f2aa26ef379442388937f311cb8c26daf1817182a5e7f486f33 description: Documentation for the VizQL Data Service --- # Request Data Source Metadata 🕐 _2 min read_ ## Get the data structure in the data source The [Request data source metadata](https://help.tableau.com/v0.0/api/vizql-data-service/en-us/reference/index.html#operation/ReadMetadata) 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](https://help.tableau.com/v0.0/api/vizql-data-service/en-us/docs/vds_configuration.html#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](https://help.tableau.com/v0.0/api/vizql-data-service/en-us/docs/vds_configuration.html#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 } ] } } ```