Skip to main content
Bag of words connects to Tableau Server or Tableau Cloud, discovers the published data sources on a site, and queries them through the VizQL Data Service (Headless BI). Field-level descriptions, roles, and calculated-field formulas come from the Metadata API, so the agent knows what each field means before it asks a question.
The Tableau connector is part of the Enterprise Edition.

​
How it works

Bag of words signs in to the site with a Personal Access Token and receives a session token, then:
  1. Lists the published data sources on the site (paginated REST call), optionally narrowed to one project.
  2. For each data source, reads its fields from VizQL read-metadata and enriches them from the Metadata API (/api/metadata/graphql) — descriptions, field roles, and calculated-field formulas.
  3. Runs queries through VizQL query-datasource.
Each published data source becomes one schema entry named Project/Data source (for example Finance/Superstore).
Tableau is not queried with SQL. The agent builds VizQL requests — a list of fields with aggregation functions plus filters (SET, TOP, QUANTITATIVE, DATE) — and Tableau evaluates them against the published data source, applying the model’s joins and calculations.
Re-indexing is incremental: data sources that are already in the catalog are rebuilt from the stored definition, and only new ones pay for a fresh metadata round-trip. Renames and project moves still propagate, because the listing is always re-read.

​
Before you start

  • The site’s server URL and its site name (the contentUrl that appears in the browser address bar after /site/). The Default site has no site name.
  • A Personal Access Token created by a user with access to the data sources you want to expose.
  • The Metadata API enabled on the server. Tableau Cloud has it on; on Tableau Server a server administrator must enable metadata services, otherwise field descriptions and formulas come back empty.
  • VizQL Data Service (Headless BI) available for the site — this is what executes queries.
  • Network access from Bag of words to the Tableau server over HTTPS.

​
Step 1 — Create a Personal Access Token

In Tableau, open the user menu → My Account Settings → Personal Access Tokens → Create Token.
1

Name the token

The token name is what you enter as pat_name in Bag of words.
2

Copy the secret

Copy the token secret immediately — Tableau shows it once. This is pat_token.
A Personal Access Token expires if it goes unused for the period set by your server administrator, and it inherits the permissions of the user who created it. Use a service account rather than a personal login for a shared connection.
3

Check the user's content permissions

The token can only see what its owner can see. Give that account at least Connect/View on the projects whose published data sources you want the agent to reach.

​
Connect in Bag of words

Go to Settings → Data Sources → Add data source → Tableau. See Connecting a data source for the general flow. Test Connection signs in, probes the VizQL health endpoint, and tries a query against the first data source it finds. A VizQL query endpoint that answers 404 does not fail the test — it is reported as a feature or permission gap while sign-in is confirmed working.

​
Authentication modes

Supply both fields together — the token name alone cannot sign in. Because the mode is available at both scopes, you can configure one shared token for the whole workspace (system), or have each user supply their own token (user) so Tableau applies that person’s own content permissions and row-level security. Per-user credentials on a connector like this require Enterprise — see Authentication.

​
Troubleshooting

Check site_name first: it must be the site’s contentUrl, not its display name, and must be blank for the Default site. Then confirm the token has not expired or been revoked. On older on-prem servers, lower api_version — a server that predates the requested REST API version rejects the sign-in call.
Neither VizQL read-metadata nor the Metadata API returned anything for it. Confirm the Metadata API is enabled on the server and that VizQL Data Service is available for the site, and that the token’s owner has permission on that data source.
Types come from VizQL and descriptions, roles, and calculated-field formulas come from the Metadata API. If only the descriptive half is missing, the Metadata API is unavailable or the token’s owner cannot read that content through it.
If default_project_id is set, only that project is discovered — clear it to see the whole site. Otherwise the token’s owner simply cannot see the rest of the content.
Raise timeout_sec. VizQL evaluates the aggregation on the Tableau side, so a heavy data source can exceed the 30-second default.