Tableau (MCP only; EOL soon)

Retrieves a list of all published Pulse Metric Definitions using the Tableau REST API. Use this tool when a user requests to list all Tableau Pulse Metric Definitions on the current site. **Parameters:** - `view` (optional): The range of metrics to return for a definition. The default is 'DEFINITION_VIEW_BASIC' if not specified. - `DEFINITION_VIEW_BASIC` - Return only the specified metric definition. - `DEFINITION_VIEW_FULL` - Return the metric definition and the specified number of metrics. - `DEFINITION_VIEW_DEFAULT` - Return the metric definition and the default metric. - `limit` (optional): Maximum number of metric definitions to return. If not specified, all definitions are returned. - `pageSize` (optional): Number of results per page. Controls how many definitions are fetched in each API request during pagination. **Example Usage:** - List all Pulse Metric Definitions on the current site - List all Pulse Metric Definitions on the current site with the default view: view: 'DEFINITION_VIEW_DEFAULT' - List the first 50 Pulse Metric Definitions: limit: 50 - List all Pulse Metric Definitions on the current site with the full view: view: 'DEFINITION_VIEW_FULL' In the response you will only get up to 5 metrics, so if you want to see more you need to retrieve all the Pulse Metrics from another tool. - List all Pulse Metric Definitions on the current site with the basic view: view: 'DEFINITION_VIEW_BASIC' - See all metrics for my Pulse Metric Definitions: view: 'DEFINITION_VIEW_FULL' In the response you will only get up to 5 metrics, so if you want to see more you need to retrieve all the Pulse Metrics from another tool.

list-all-pulse-metric-definitions

Retrieves a list of custom views for a Tableau workbook including their metadata such as name, owner, and the view they are found in. Supports optional filtering via field:operator:value expressions (e.g., viewId:eq:<view_id>) for precise and flexible custom view discovery. The tool always includes the workbookId in the final filter expression based on the required workbookId argument. Including the workbookId field in the filter will be ignored. Use this tool when a user requests to list, search, or filter Tableau custom views for a workbook. **Supported Filter Fields and Operators** | Field | Operators | |---------------------|----------------------| | ownerId | eq | | viewId | eq | **Supported Operators** - `eq`: equals - `gt`: greater than - `gte`: greater than or equal - `in`: any of [list] (for searching tags) - `lt`: less than - `lte`: less than or equal **Filter Expression Notes** - Filter expressions can't contain ampersand (&) or comma (,) characters even if those characters are encoded. - Operators are delimited with colons (:). For example: `filter=name:eq:Project Views` - Field names, operator names, and values are case-sensitive. - To filter on multiple fields, combine expressions using a comma: `filter=lastLogin:gte:2016-01-01T00:00:00Z,siteRole:eq:Publisher` - Multiple expressions are combined using a logical AND. - If you include the same field multiple times, only the last reference is used. - For date-time values, use ISO 8601 format (e.g., `2016-05-04T21:24:49Z`). - Wildcard searches (starts with, ends with, contains) are supported in recent Tableau versions: - Starts with: `?filter=name:eq:mark*` - Ends with: `?filter=name:eq:*-ample` - Contains: `?filter=name:eq:mark*ex*` **Example Usage:** - List all custom views for a given workbook: workbookId: "222ea993-9391-4910-a167-56b3d19b4e3b" - List custom views from the view with viewId "9460abfe-a6b2-49d1-b998-39e1ebcc55ce": workbookId: "222ea993-9391-4910-a167-56b3d19b4e3b" filter: "viewId:eq:9460abfe-a6b2-49d1-b998-39e1ebcc55ce" - List custom views for the owner with ownerId "bbdee366-4a50-4c2c-a5c8-746da5b64483": workbookId: "222ea993-9391-4910-a167-56b3d19b4e3b" filter: "ownerId:eq:bbdee366-4a50-4c2c-a5c8-746da5b64483"

list-custom-views

Retrieves a list of published data sources from a specified Tableau site using the Tableau REST API. Supports optional filtering via field:operator:value expressions (e.g., name:eq:Views) for precise and flexible data source discovery. To list results based on usage popularity or relevance, use the search-content tool instead. **Supported Filter Fields and Operators** | Field | Operators | |------------------------|-------------------------------------------| | authenticationType | eq, in | | connectedWorkbookType | eq, gt, gte, lt, lte | | connectionTo | eq, in | | connectionType | eq, in | | contentUrl | eq, in | | createdAt | eq, gt, gte, lt, lte | | databaseName | eq, in | | databaseUserName | eq, in | | description | eq, in | | favoritesTotal | eq, gt, gte, lt, lte | | hasAlert | eq | | hasEmbeddedPassword | eq | | hasExtracts | eq | | isCertified | eq | | isConnectable | eq | | isDefaultPort | eq | | isHierarchical | eq | | isPublished | eq | | name | eq, in | | ownerDomain | eq, in | | ownerEmail | eq | | ownerName | eq, in | | projectName | eq, in | | serverName | eq, in | | serverPort | eq | | size | eq, gt, gte, lt, lte | | tableName | eq, in | | tags | eq, in | | type | eq | | updatedAt | eq, gt, gte, lt, lte | **Supported Operators** - `eq`: equals - `gt`: greater than - `gte`: greater than or equal - `in`: any of [list] (for searching tags) - `lt`: less than - `lte`: less than or equal **Filter Expression Notes** - Filter expressions can't contain ampersand (&) or comma (,) characters even if those characters are encoded. - Operators are delimited with colons (:). For example: `filter=name:eq:Project Views` - Field names, operator names, and values are case-sensitive. - To filter on multiple fields, combine expressions using a comma: `filter=lastLogin:gte:2016-01-01T00:00:00Z,siteRole:eq:Publisher` - Multiple expressions are combined using a logical AND. - If you include the same field multiple times, only the last reference is used. - For date-time values, use ISO 8601 format (e.g., `2016-05-04T21:24:49Z`). - Wildcard searches (starts with, ends with, contains) are supported in recent Tableau versions: - Starts with: `?filter=name:eq:mark*` - Ends with: `?filter=name:eq:*-ample` - Contains: `?filter=name:eq:mark*ex*` **Example Usage:** - List data sources with the name "Project Views": filter: "name:eq:Project Views" - List data sources in the "Finance" project: filter: "projectName:eq:Finance" - List data sources created after January 1, 2023: filter: "createdAt:gt:2023-01-01T00:00:00Z" - List data sources with the name "Project Views" in the "Finance" project and created after January 1, 2023: filter: "name:eq:Project Views,projectName:eq:Finance,createdAt:gt:2023-01-01T00:00:00Z" **Pagination** This tool returns a single 1000-item page per call. Use `pageNumber` to select which 1-based page to fetch (default 1). The response is a flat object `{ data, totalAvailable }`; to collect every project, keep incrementing `pageNumber` until you have gathered `totalAvailable` items. To get just the count of datasources matching a request, read `totalAvailable` from a single call with `limit: 1` — the count is returned regardless of page size, and a small `limit` keeps the response tiny.

list-datasources

Retrieves a list of projects on a Tableau site including their metadata such as name, description, parent project, content permissions, owner, and timestamps. Supports optional filtering via field:operator:value expressions (e.g., name:eq:Default) for precise project discovery. To list results based on usage popularity or relevance, use the search-content tool instead. **Supported Filter Fields and Operators** | Field | Operators | |-------------------|----------------------| | createdAt | eq, gt, gte, lt, lte | | name | eq, in | | ownerDomain | eq, in | | ownerEmail | eq, in | | ownerName | eq, in | | parentProjectId | eq, in | | topLevelProject | eq | | updatedAt | eq, gt, gte, lt, lte | **Supported Operators** - `eq`: equals - `gt`: greater than - `gte`: greater than or equal - `in`: any of [list] (for searching tags) - `lt`: less than - `lte`: less than or equal **Filter Expression Notes** - Filter expressions can't contain ampersand (&) or comma (,) characters even if those characters are encoded. - Operators are delimited with colons (:). For example: `filter=name:eq:Project Views` - Field names, operator names, and values are case-sensitive. - To filter on multiple fields, combine expressions using a comma: `filter=lastLogin:gte:2016-01-01T00:00:00Z,siteRole:eq:Publisher` - Multiple expressions are combined using a logical AND. - If you include the same field multiple times, only the last reference is used. - For date-time values, use ISO 8601 format (e.g., `2016-05-04T21:24:49Z`). - Wildcard searches (starts with, ends with, contains) are supported in recent Tableau versions: - Starts with: `?filter=name:eq:mark*` - Ends with: `?filter=name:eq:*-ample` - Contains: `?filter=name:eq:mark*ex*` **Example Usage:** - List projects with the name "Default": filter: "name:eq:Default" - List top-level projects only: filter: "topLevelProject:eq:true" - List child projects of a specific parent: filter: "parentProjectId:eq:abc-123" - List projects updated after January 1, 2023: filter: "updatedAt:gt:2023-01-01T00:00:00Z" **Pagination** This tool returns a single 1000-item page per call. Use `pageNumber` to select which 1-based page to fetch (default 1). The response is a flat object `{ data, totalAvailable }`; to collect every project, keep incrementing `pageNumber` until you have gathered `totalAvailable` items. To get just the count of projects matching a request, read `totalAvailable` from a single call with `limit: 1` — the count is returned regardless of page size, and a small `limit` keeps the response tiny.

list-projects

Retrieves a list of specific Pulse Metric Definitions using the Tableau REST API from a list of metric definition IDs. Use this tool when a user requests information about specific Pulse Metric Definitions on the current site. **Parameters:** - `metricDefinitionIds` (required): A list of metric definition IDs to retrieve. - `view` (optional): The range of metrics to return for a definition. The default is 'DEFINITION_VIEW_BASIC' if not specified. - `DEFINITION_VIEW_BASIC` - Return only the specified metric definition. - `DEFINITION_VIEW_FULL` - Return the metric definition and the specified number of metrics. - `DEFINITION_VIEW_DEFAULT` - Return the metric definition and the default metric. **Example Usage:** - Can you show me details about Pulse Metric Definition with id 'BBC908D8-29ED-48AB-A78E-ACF8A424C8C3' metricDefinitionIds: ['BBC908D8-29ED-48AB-A78E-ACF8A424C8C3'] - List Pulse Metric Definitions from a list of metric definition IDs: metricDefinitionIds: ['BBC908D8-29ED-48AB-A78E-ACF8A424C8C3', 'BBC908D8-29ED-48AB-A78E-ACF8A424C8C4'] - List these Pulse Metric Definitions with the default view: metricDefinitionIds: ['BBC908D8-29ED-48AB-A78E-ACF8A424C8C3', 'BBC908D8-29ED-48AB-A78E-ACF8A424C8C4'], view: 'DEFINITION_VIEW_DEFAULT' - List these Pulse Metric Definitions with the full view: metricDefinitionIds: ['BBC908D8-29ED-48AB-A78E-ACF8A424C8C3', 'BBC908D8-29ED-48AB-A78E-ACF8A424C8C4'], view: 'DEFINITION_VIEW_FULL', In the response you will only get up to 5 metrics, so if you want to see more you need to retrieve all the Pulse Metrics from another tool. - List these Pulse Metric Definitions with the basic view: metricDefinitionIds: ['BBC908D8-29ED-48AB-A78E-ACF8A424C8C3', 'BBC908D8-29ED-48AB-A78E-ACF8A424C8C4'], view: 'DEFINITION_VIEW_BASIC' - See all metrics for these Pulse Metric Definitions with the full view: metricDefinitionIds: ['BBC908D8-29ED-48AB-A78E-ACF8A424C8C3', 'BBC908D8-29ED-48AB-A78E-ACF8A424C8C4'], view: 'DEFINITION_VIEW_FULL' In the response you will only get up to 5 metrics, so if you want to see more you need to retrieve all the Pulse Metrics from another tool.

list-pulse-metric-definitions-from-definition-ids

Retrieves a list of published Pulse Metric Subscriptions for the current user using the Tableau REST API. Use this tool when a user requests to list Tableau Pulse Metric Subscriptions for the current user. **Example Usage:** - List all Pulse Metric Subscriptions for the current user on the current site - List all of my Pulse Metric Subscriptions **Note:** - This tool does not directly provide information about Pulse Metric Definitions. If you need to know information about Pulse Metric Defintiions associated with your subscriptions you need to: 1. Retrieve Pulse Metrics from the metric ids returned in the Pulse Metric Subscriptions. 2. Retrieve Pulse Metric Definitions from the metric definition id returned in the Pulse Metrics.

list-pulse-metric-subscriptions

Retrieves a list of published Pulse Metrics from a Pulse Metric Definition using the Tableau REST API. Use this tool when a user requests to list Tableau Pulse Metrics for a specific Pulse Metric Definition on the current site. **Parameters:** - `pulseMetricDefinitionID` (required): The ID of the Pulse Metric Definition to list metrics for. It should be the ID of the Pulse Metric Definition, not the name. Example: BBC908D8-29ED-48AB-A78E-ACF8A424C8C3 **Example Usage:** - List all Pulse Metrics for this Pulse Metric Definition

list-pulse-metrics-from-metric-definition-id

Retrieves a list of published Pulse Metrics from a list of metric IDs using the Tableau REST API. Use this tool when a user requests to list Tableau Pulse Metrics for a list of metric IDs on the current site. **Parameters:** - `metricIds` (required): The list of Pulse Metric IDs to list metrics for. It should be the list of metric IDs, not the names or metric definition ids. Example: ['CF32DDCC-362B-4869-9487-37DA4D152552', 'CF32DDCC-362B-4869-9487-37DA4D152553'] - For data in a Pulse Metric Subscription, use the metric_id field. **Example Usage:** - List all Pulse Metrics from a list of Pulse Metric IDs **Note:** - This tool is recommended for use with data in Pulse Metric Subscriptions. - 00000000-0000-0000-0000-000000000000 is not a valid datasource id. - If you need a valid datasource id, you may need to retrieve the Pulse Metric Definition for the Pulse Metric which should have a valid datasource information.

list-pulse-metrics-from-metric-ids

Retrieves a list of views on a Tableau site including their metadata such as name, owner, and the workbook they are found in. Supports optional filtering via field:operator:value expressions (e.g., name:eq:Overview) for precise and flexible view discovery. To list results based on usage popularity or relevance, use the search-content tool instead. **Supported Filter Fields and Operators** | Field | Operators | |---------------------|----------------------| | caption | eq, in | | contentUrl | eq, in | | createdAt | eq, gt, gte, lt, lte | | favoritesTotal | eq, gt, gte, lt, lte | | fields | eq, in | | hitsTotal | eq, gt, gte, lt, lte | | name | eq, in | | ownerDomain | eq, in | | ownerEmail | eq, in | | ownerName | eq, in | | projectName | eq, in | | sheetNumber | eq, gt, gte, lt, lte | | sheetType | eq, in | | tags | eq, in | | title | eq, in | | updatedAt | eq, gt, gte, lt, lte | | viewUrlname | eq, in | | workbookDescription | eq, in | | workbookName | eq, in | **Supported Operators** - `eq`: equals - `gt`: greater than - `gte`: greater than or equal - `in`: any of [list] (for searching tags) - `lt`: less than - `lte`: less than or equal **Filter Expression Notes** - Filter expressions can't contain ampersand (&) or comma (,) characters even if those characters are encoded. - Operators are delimited with colons (:). For example: `filter=name:eq:Project Views` - Field names, operator names, and values are case-sensitive. - To filter on multiple fields, combine expressions using a comma: `filter=lastLogin:gte:2016-01-01T00:00:00Z,siteRole:eq:Publisher` - Multiple expressions are combined using a logical AND. - If you include the same field multiple times, only the last reference is used. - For date-time values, use ISO 8601 format (e.g., `2016-05-04T21:24:49Z`). - Wildcard searches (starts with, ends with, contains) are supported in recent Tableau versions: - Starts with: `?filter=name:eq:mark*` - Ends with: `?filter=name:eq:*-ample` - Contains: `?filter=name:eq:mark*ex*` **Example Usage:** - List views with the name "Overview": filter: "name:eq:Overview" - List views in the "Finance" project: filter: "projectName:eq:Finance" - List views created after January 1, 2023: filter: "createdAt:gt:2023-01-01T00:00:00Z" - List views with the name "Overview" in the "Finance" project and created after January 1, 2023: filter: "name:eq:Overview,projectName:eq:Finance,createdAt:gt:2023-01-01T00:00:00Z" **Pagination** This tool returns a single 1000-item page per call. Use `pageNumber` to select which 1000-item page to fetch (1-based, default 1). The response is a flat object `{ data, totalAvailable }`; paginate by incrementing `pageNumber` until you have collected `totalAvailable` items. To get just the count of views matching a request, read `totalAvailable` from a single call with `limit: 1` — the count is returned regardless of page size, and a small `limit` keeps the response tiny.

list-views

Retrieves a list of workbooks on a Tableau site including their metadata such as name, description, and information about the views contained in the workbook. Supports optional filtering via field:operator:value expressions (e.g., name:eq:Superstore) for precise and flexible workbook discovery. To list results based on usage popularity or relevance, use the search-content tool. **Supported Filter Fields and Operators** | Field | Operators | |-------------------|----------------------| | createdAt | eq, gt, gte, lt, lte | | contentUrl | eq, in | | displayTabs | eq | | favoritesTotal | eq, gt, gte, lt, lte | | hasAlerts | eq | | hasExtracts | eq | | name | eq, in | | ownerDomain | eq, in | | ownerEmail | eq, in | | ownerName | eq, in | | projectName | eq, in | | sheetCount | eq, gt, gte, lt, lte | | size | eq, gt, gte, lt, lte | | subscriptionTotal | eq, gt, gte, lt, lte | | tags | eq, in | | updatedAt | eq, gt, gte, lt, lte | **Supported Operators** - `eq`: equals - `gt`: greater than - `gte`: greater than or equal - `in`: any of [list] (for searching tags) - `lt`: less than - `lte`: less than or equal **Filter Expression Notes** - Filter expressions can't contain ampersand (&) or comma (,) characters even if those characters are encoded. - Operators are delimited with colons (:). For example: `filter=name:eq:Project Views` - Field names, operator names, and values are case-sensitive. - To filter on multiple fields, combine expressions using a comma: `filter=lastLogin:gte:2016-01-01T00:00:00Z,siteRole:eq:Publisher` - Multiple expressions are combined using a logical AND. - If you include the same field multiple times, only the last reference is used. - For date-time values, use ISO 8601 format (e.g., `2016-05-04T21:24:49Z`). - Wildcard searches (starts with, ends with, contains) are supported in recent Tableau versions: - Starts with: `?filter=name:eq:mark*` - Ends with: `?filter=name:eq:*-ample` - Contains: `?filter=name:eq:mark*ex*` **Example Usage:** - List workbooks with the name "Superstore": filter: "name:eq:Superstore" - List workbooks in the "Finance" project: filter: "projectName:eq:Finance" - List workbooks created after January 1, 2023: filter: "createdAt:gt:2023-01-01T00:00:00Z" - List workbooks with the name "Superstore" in the "Finance" project and created after January 1, 2023: filter: "name:eq:Superstore,projectName:eq:Finance,createdAt:gt:2023-01-01T00:00:00Z" **Pagination** This tool returns a single 1000-item page per call. Use `pageNumber` to select which 1000-item page to fetch (1-based, default 1). The response is a flat object `{ data, totalAvailable }`; paginate by incrementing `pageNumber` until you have collected `totalAvailable` items. To get just the count of workbooks matching a request, read `totalAvailable` from a single call with `limit: 1` — the count is returned regardless of page size, and a small `limit` keeps the response tiny.

list-workbooks

Publishes a TWB or TWBX workbook from a local file path or staged upload id to the specified Tableau project. Use list-projects to discover project IDs. TWB workbooks are validated up front and uploaded only when validation succeeds, with any blocking errors returned instead of publishing. TWBX workbooks are uploaded directly and validated by Tableau as part of publishing, since Tableau cannot pre-validate extracts packaged inside a TWBX.

publish-workbook

# Query Tableau Data Source Tool Executes VizQL queries against Tableau data sources to answer business questions from published data. This tool allows you to retrieve aggregated and filtered data with proper sorting and grouping. ## Prerequisites Before using this tool, you should: 1. Understand available fields and their types 2. Understand what parameters are available and their types 3. Understand the data structure and field relationships ## Best Practices ### Data Volume Management - **Always prefer aggregation** - Use aggregated fields (SUM, COUNT, AVG, etc.) instead of raw row-level data to reduce response size - **Profile data before querying** - When unsure about data volume, first run a COUNT query to understand the scale: ```json { "fields": [ { "fieldCaption": "Order ID", "function": "COUNT", "fieldAlias": "Total Records" } ] } ``` - **Use TOP filters for rankings** - When users ask for "top N" results, use TOP filter type to limit results at the database level - **Apply restrictive filters** - Use SET, QUANTITATIVE, or DATE filters to reduce data volume before processing - **Avoid row-level queries when possible** - Only retrieve individual records when specifically requested and the business need is clear ### Field Usage Guidelines - **Prefer existing fields** - Use fields already modeled in the data source rather than creating custom calculations - **Use bins for distribution analysis** - Create bins to group continuous data into discrete ranges (e.g., age groups, price ranges) - **Validate field availability** - Always check field metadata before constructing queries ### Field Types #### Dimension Fields Basic fields without aggregation: ```json { "fieldCaption": "Category", "fieldAlias": "Product Category" } ``` #### Measure Fields Fields with aggregation functions (SUM, AVG, COUNT, etc.): ```json { "fieldCaption": "Sales", "function": "SUM", "fieldAlias": "Total Sales", "maxDecimalPlaces": 2 } ``` #### Calculated Fields Custom fields defined using Tableau calculation syntax: ```json { "fieldCaption": "Profit Margin", "calculation": "SUM([Profit]) / SUM([Sales])", "fieldAlias": "Margin %" } ``` #### Bin Fields Group continuous data into discrete ranges: ```json { "fieldCaption": "Sales", "binSize": 1000, "fieldAlias": "Sales Range" } ``` This creates bins of $1,000 intervals (0-1000, 1000-2000, etc.) ### Query Construction - **Group by meaningful dimensions** - Ensure grouping supports the business question being asked - **Order results logically** - Use sortDirection and sortPriority to present data in a meaningful way - **Use appropriate date functions** - Choose the right date aggregation (YEAR, QUARTER, MONTH, WEEK, DAY, or TRUNC_* variants) - **Leverage filter capabilities** - Use the extensive filter options to narrow results ## Data Profiling Strategy When a query might return large amounts of data, follow this profiling approach: **Step 1: Count total records** ```json { "fields": [ { "fieldCaption": "Primary_Key_Field", "function": "COUNT", "fieldAlias": "Total Records" } ] } ``` **Step 2: Count by key dimensions** ```json { "fields": [ { "fieldCaption": "Category", "fieldAlias": "Category" }, { "fieldCaption": "Order ID", "function": "COUNT", "fieldAlias": "Record Count" } ] } ``` **Step 3: Apply appropriate aggregation or filtering based on counts** ## Parameters Parameters are dynamic values defined in the Tableau datasource that can be used to control calculations, filters, and query behavior. They allow for interactive, user-controlled queries without modifying the query structure. ### When to Use Parameters - **Dynamic filtering** - Let users control date ranges, regions, or categories - **What-if analysis** - Adjust values like growth rates, targets, or thresholds - **Calculation control** - Switch between different metrics or calculation methods - **User preferences** - Currency selection, display units, or other settings ### Parameter Types - **LIST** - Predefined values (e.g., regions, categories) - **ANY_VALUE** - Free-form values matching data type - **QUANTITATIVE_RANGE** - Numeric values with optional min/max/step - **QUANTITATIVE_DATE** - Date values with optional range constraints ### Usage Example ```json { "datasourceLuid": "abc123", "query": { "fields": [...], "filters": [...], "parameters": [ { "name": "Selected Year", "value": 2024 }, { "name": "Currency", "value": "USD" } ] } } ``` - Parameters affect entire query; filters restrict returned data ## Bins Bins group continuous numerical data into discrete ranges, enabling distribution analysis and histogram creation. Unlike parameters and filters, bins are created dynamically in the query. ### Creating Bin Fields To create a bin field in a query, you **must** include: 1. A **measure field** with the base field and aggregation function 2. A **bin field** with the same fieldCaption and a binSize property **Example:** ```json { "fields": [ { "fieldCaption": "Sales", "function": "SUM", "fieldAlias": "Total Sales" }, { "fieldCaption": "Sales", "binSize": 1000, "fieldAlias": "Sales Range" } ] } ``` This creates bins of $1,000 intervals (0-1000, 1000-2000, etc.) ### When to Use Bins - Analyzing distribution patterns (age groups, price ranges, score brackets) - Creating histograms or frequency distributions - Grouping continuous numerical data into meaningful categories - User asks questions like "How many customers in each age range?" or "What's the distribution of order sizes?" ### Bin Restrictions - **Cannot override existing bin fields** - If a bin field already exists in the datasource, query it without binSize - **binSize must be positive** - Only values > 0 are allowed - **Measure fields only** - Can only bin numeric/quantitative fields - **Choose appropriate bin sizes** - Consider your data range (e.g., bin size 100 for values 0-10,000) ### Querying Existing Bin Fields If a bin field already exists in the datasource (e.g., "Profit (bin)"), query it as a regular dimension field: ```json { "fields": [ { "fieldCaption": "Profit (bin)" }, { "fieldCaption": "Profit", "function": "SUM" } ] } ``` To control existing bin field behavior, use parameters if available (e.g., "Profit Bin Size"). ## Filter Types and Usage ### Filter Context Property All filters support an optional `context` property (boolean) that controls how filters are applied: - **`context: true`** - Filter applies to the overall query context (dimension/scope filters) - **`context: false`** - Filter applies after context is established (ranking/limiting filters) **When to use:** - Set `context: true` on dimension filters (SET, DATE, QUANTITATIVE) that define the scope of analysis - Set `context: false` on TOP filters to rank/limit results within the established context - Omit `context` property for simple queries with single filters **Example: Finding top products within a region:** ```json { "filters": [ { "field": { "fieldCaption": "State" }, "filterType": "SET", "values": ["California"], "context": true // Establish California as the context }, { "field": { "fieldCaption": "Product Name" }, "filterType": "TOP", "howMany": 1, "direction": "TOP", "context": false, // Find top product within California "fieldToMeasure": { "fieldCaption": "Sales", "function": "SUM" } } ] } ``` ### SET Filters Filter by specific values: ```json { "field": {"fieldCaption": "Region"}, "filterType": "SET", "values": ["North", "South", "East"], "exclude": false } ``` ### MATCH Filters Filter strings using patterns: ```json { "field": {"fieldCaption": "City"}, "filterType": "MATCH", "startsWith": "San" } ``` ### TOP Filters Get top/bottom N records by a measure: ```json { "field": {"fieldCaption": "Customer Name"}, "filterType": "TOP", "howMany": 10, "direction": "TOP", "fieldToMeasure": {"fieldCaption": "Sales", "function": "SUM"} } ``` ### QUANTITATIVE Filters Filter numeric ranges: ```json { "field": {"fieldCaption": "Sales"}, "filterType": "QUANTITATIVE_NUMERICAL", "quantitativeFilterType": "RANGE", "min": 1000, "max": 50000, "includeNulls": false } ``` ### DATE Filters Filter relative date periods: ```json { "field": {"fieldCaption": "Order Date"}, "filterType": "DATE", "periodType": "MONTHS", "dateRangeType": "LAST" } ``` ## Limitations - **QUANTITATIVE_NUMERICAL min/max operators are inclusive** - For strictly greater-than or less-than logic, use a small offset (for example, min: 10.01 for > 10, or max: 9.99 for < 10). - **MATCH filters cannot apply functions to a field** - Unlike all other filters, which can filter on fields with functions applied to them, MATCH filters can only filter by field name or ad hoc calculations. ## Example Queries ### Example 1: Data Profiling Before Large Query **Question:** "Show me all customer orders this year" **Step 1 - Profile the data volume:** ```json { "datasourceLuid": "abc123", "query": { "fields": [ { "fieldCaption": "Order ID", "function": "COUNT", "fieldAlias": "Total Orders This Year" } ], "filters": [ { "field": {"fieldCaption": "Order Date"}, "filterType": "DATE", "periodType": "YEARS", "dateRangeType": "CURRENT" } ] } } ``` **If count is manageable (< 10,000), proceed with detail query. If large, suggest aggregation:** ```json { "datasourceLuid": "abc123", "query": { "fields": [ { "fieldCaption": "Customer Name" }, { "fieldCaption": "Order Date", "function": "TRUNC_MONTH", "sortDirection": "DESC", "sortPriority": 1 }, { "fieldCaption": "Sales", "function": "SUM", "fieldAlias": "Monthly Sales" } ], "filters": [ { "field": {"fieldCaption": "Order Date"}, "filterType": "DATE", "periodType": "YEARS", "dateRangeType": "CURRENT" } ] } } ``` ### Example 2: Top Customers Query (Using TOP Filter) **Question:** "Who are our top 10 customers by revenue?" ```json { "datasourceLuid": "abc123", "query": { "fields": [ { "fieldCaption": "Customer Name" }, { "fieldCaption": "Sales", "function": "SUM", "fieldAlias": "Total Revenue", "sortDirection": "DESC", "sortPriority": 1 } ], "filters": [ { "field": {"fieldCaption": "Customer Name"}, "filterType": "TOP", "howMany": 10, "direction": "TOP", "fieldToMeasure": {"fieldCaption": "Sales", "function": "SUM"} } ] } } ``` ### Example 3: Top N Dimension Query (Using TOP Filter and context property) **Question:** "What is the top selling product in California?" ```json { "datasourceLuid": "abc123", "query": { "fields": [ { "fieldCaption": "Product Name" }, { "fieldCaption": "Sales", "function": "SUM", "fieldAlias": "Total Sales", "sortDirection": "DESC", "sortPriority": 1 } ], "filters": [ { "field": { "fieldCaption": "State" }, "filterType": "SET", "values": ["California"], "context": true }, { "field": { "fieldCaption": "Product Name" }, "filterType": "TOP", "howMany": 1, "direction": "TOP", "context": false, "fieldToMeasure": { "fieldCaption": "Sales", "function": "SUM" } } ] } } ``` ### Example 4: Time Series with Aggregation **Question:** "What are our monthly sales trends?" ```json { "datasourceLuid": "abc123", "query": { "fields": [ { "fieldCaption": "Order Date", "function": "TRUNC_MONTH", "fieldAlias": "Month", "sortDirection": "ASC", "sortPriority": 1 }, { "fieldCaption": "Sales", "function": "SUM", "fieldAlias": "Monthly Sales" }, { "fieldCaption": "Order ID", "function": "COUNT", "fieldAlias": "Order Count" } ] } } ``` ### Example 5: Filtered Category Analysis **Question:** "What's the performance by product category for high-value orders?" ```json { "datasourceLuid": "abc123", "query": { "fields": [ { "fieldCaption": "Category" }, { "fieldCaption": "Sales", "function": "SUM", "fieldAlias": "Total Sales" }, { "fieldCaption": "Sales", "function": "AVG", "fieldAlias": "Average Order Value", "maxDecimalPlaces": 2 }, { "fieldCaption": "Order ID", "function": "COUNT", "fieldAlias": "Order Count" } ], "filters": [ { "field": {"fieldCaption": "Sales"}, "filterType": "QUANTITATIVE_NUMERICAL", "quantitativeFilterType": "MIN", "min": 500 } ] } } ``` ### Example 6: Distribution Analysis Using Bins **Question:** "How are our sales distributed across different price ranges?" ```json { "datasourceLuid": "abc123", "query": { "fields": [ { "fieldCaption": "Sales", "binSize": 1000, "fieldAlias": "Sales Range", "sortDirection": "ASC", "sortPriority": 1 }, { "fieldCaption": "Order ID", "function": "COUNT", "fieldAlias": "Number of Orders" }, { "fieldCaption": "Sales", "function": "SUM", "fieldAlias": "Total Sales in Range" } ] } } ``` ### Example 7: Using Parameters for Dynamic Analysis **Question:** "Show me sales for the selected region and year" ```json { "datasourceLuid": "abc123", "query": { "fields": [ { "fieldCaption": "Category" }, { "fieldCaption": "Sales", "function": "SUM", "fieldAlias": "Total Sales", "sortDirection": "DESC", "sortPriority": 1 } ], "parameters": [ { "name": "Selected Region", "value": "West" }, { "name": "Analysis Year", "value": 2024 } ] } } ``` ## Calculations **Create calculations when you need to:** - Segment data in ways not captured by existing fields - Convert data types (e.g., string to date) - Aggregate data with custom logic beyond standard functions - Filter results based on computed conditions - Calculate ratios or derived metrics - Perform analysis and the required data is not present in any existing field - Transform values during visualization - Quickly categorize data into custom groups **Avoid calculations if you can achieve the same result by:** - Applying standard aggregation functions (SUM, AVG, COUNT, etc.) to existing fields - Combining existing fields and filters together Note: Calculated Fields created as part of a query cannot be referenced in other calculations or filters. ## Error Prevention and Data Management **When to profile data first:** - User asks for "all records" or similar broad requests - Query involves high-cardinality fields without filters - Request could potentially return row-level data for large tables **Suggest aggregation when:** - Profile queries return very high counts (> 10,000 records) - User asks questions that can be answered with summaries - Performance or response size might be an issue **Don't call this tool if:** - The requested fields are not available in the data source - The question requires data not present in the current data source - Field validation shows incompatible field types for the requested operation **Instead:** - Use metadata tools to understand available fields - Suggest alternative questions that can be answered with available data - Recommend appropriate aggregation levels for the business question

query-datasource

Creates a short-lived staged upload URL for a Tableau TWB or TWBX workbook. Upload the workbook bytes to the returned URL, then call publish-workbook with the returned workbookUploadId.

request-workbook-upload

Resets saved OAuth consent for the current user on the Tableau authorization server. After resetting consent, the current session remains valid. The next OAuth authorization flow will re-prompt the user for consent. This tool requires no input — it operates on the token already associated with the current session and never exposes the raw token value. **Important:** Call this tool before revoking the access token. Revocation invalidates the token required to authenticate the consent reset request. **When to use:** - Clearing previously granted OAuth consent as part of session teardown - Resetting consent state during testing or development - Cleaning up OAuth grants when a user's access should be fully removed

reset-consent

Revokes the access token used to authenticate the current session. After revocation the session is invalidated. Subsequent Tableau API calls within this session may fail. Clients should disconnect from the MCP server after calling this tool. This tool requires no input — it operates on the token already associated with the current session and never exposes the raw token value. **When to use:** - Signing a user out of the MCP session - Revoking access after detecting suspicious activity - Clean session teardown from an MCP client or orchestration layer

revoke-access-token

This tool searches and ranks Tableau content across many content types at once — including workbooks, views, datasources, projects, lenses, flows, tables, databases, virtual connections, data roles, and collections. Use this tool for keyword or free-text discovery: when you want to find content by name or topic, when you do not know which content type an item is, when you want to search several content types in a single call, or when you want the most relevant or most-viewed items surfaced first. It returns a single ranked page (the top N matches — default 100, max 2000) rather than an exhaustive enumeration of every match, so it is best suited to finding the most relevant items rather than returning every matching item. **Parameters:** - `terms` (optional): A string containing one or more search terms that the search uses as the basis for determining which items are relevant to return. - `filter` (optional): Allows you to limit search results based on: - `contentTypes`: Filter by content types. Supported types are: 'lens', 'datasource', 'virtualconnection', 'collection', 'project', 'flow', 'datarole', 'table', 'database', 'view', 'workbook' - `ownerIds`: Filter by specific owner IDs (array of integers) - `modifiedTime`: Filter by last modified times using ISO 8601 date-time strings. Can be either a range (with startDate/endDate) or an array of specific date-times to include - `limit` (optional): The maximum number of items to return in the search response (default: 100, max: 2000). - `orderBy` (optional): An array of `{ method, sortDirection }` objects that controls how results are sorted. If omitted, results are sorted by their "relevance score" in descending order — Tableau's internal ranking of how well each item matches your search terms. `sortDirection` is 'asc' (ascending) or 'desc' (descending) and defaults to 'asc'. The first element is the primary sort; any additional elements are tiebreakers, applied in order. Available sorting methods: - `hitsTotal`: Number of times a content item has been viewed since it was created - `hitsSmallSpanTotal`: Number of times a content item was viewed in the last month - `hitsMediumSpanTotal`: Number of times a content item was viewed in the last 3 months - `hitsLargeSpanTotal`: Number of times a content item was viewed in the last year - `downstreamWorkbookCount`: Number of workbooks in a given project. This value is only available when the content type filter includes 'database' or 'table' **Example Usage:** - Top 5 most-viewed workbooks (all time): `{ limit: 5, filter: { contentTypes: ["workbook"] }, orderBy: [{ method: "hitsTotal", sortDirection: "desc" }] }` - Free-text search for the most relevant content: `{ terms: "quarterly sales" }` - Find only workbooks and views matching a topic: `{ terms: "revenue", filter: { contentTypes: ["workbook", "view"] } }` - Surface the most-viewed datasources this month (no search terms): `{ filter: { contentTypes: ["datasource"] }, orderBy: [{ method: "hitsSmallSpanTotal", sortDirection: "desc" }] }` - Multi-key sort — most-viewed all-time first, using views this year as a tiebreaker: `{ orderBy: [{ method: "hitsTotal", sortDirection: "desc" }, { method: "hitsLargeSpanTotal", sortDirection: "desc" }] }` - Content owned by specific users, modified in a date range: `{ filter: { ownerIds: [123, 456], modifiedTime: { startDate: "2026-01-01T00:00:00Z", endDate: "2026-06-30T23:59:59Z" } } }`

search-content