Search Workbook Fields
Searches fields and calculations in the workbook currently open in the connected Tableau Studio instance. Matches are case-insensitive. Each hit includes explicit Rows, Columns, and Marks placements across worksheets. The search reads the live workbook; it does not use cached files or published site content. This is a read-only operation.
APIs called
This tool reads the workbook open in the running Tableau Studio instance, not the Tableau Cloud or Server REST API. Under the hood the workbook document is fetched from the local Tableau Studio External Client API — a REST API the running Tableau Studio instance serves at http://127.0.0.1:<port>/v<x>, where <x> is the latest API version. There are no OAuth scopes: the call is authorized by the running Tableau Studio instance's per-session bearer token over the loopback interface. Matching fields and collecting shelf placements is done in process against that document.
- Settles on which Tableau Studio session to target before anything is sent. Resolved in-process (not an API call).
- Reads the open workbook document. Authorized by the session's loopback bearer token; requires a workbook to be open.
GET /v<x>/workbook/document— read the open workbook document. API reference
- Searches field captions, local names, formulas, folders, and datasource names, and records Rows, Columns, and Marks placements. Parsed in-process; not an API call.
Required arguments
query
Case-insensitive text to find in workbook fields. Type: string. Minimum length: 1 after trim.
Example
"Sales"
Optional arguments
session
Identifier of the target Tableau Studio session. When omitted, the session is resolved automatically (for example, when it is pinned or exactly one Tableau Studio instance is connected).
Example
"studio-1"
limit
Maximum number of matches to return. Type: integer. Range: 1–100. Default: 20. When more fields match, truncated is true and totalMatches still reports the full count.
Example
20
Notes and caveats
- Live workbook only. The search does not read cache files and does not query published Tableau Cloud or Server content.
- Placements are shelf and Marks encodings only. The
usageScopein the result isworksheet shelves and mark encodings only.
Example result
Matches found
{
"query": "Sales",
"totalMatches": 1,
"truncated": false,
"usageScope": "worksheet shelves and mark encodings only",
"matches": [
{
"datasource": "Sample - Superstore",
"caption": "Sales",
"localName": "Sales",
"columnRef": "[Sample - Superstore].[Sales]",
"role": "measure",
"datatype": "real",
"matchedOn": ["caption", "localName"],
"placements": [
{ "worksheet": "Overview", "location": "columns" }
]
}
]
}
Related
list-available-fields— list datasource fields available for authoring (does not report worksheet placements).