Get Started

To get started, review the requirements necessary to use the Tableau Metadata API.

In this section

Prerequisites
Enable the Tableau Metadata API for Tableau Server
About querying the Metadata API
- Who can query the Metadata API
Query the API directly using GraphQL endpoint
Explore the Metadata API schema using GraphiQL
- About the GraphiQL query tool

Prerequisites

To use the Tableau Metadata API, the following requirements must be met:

For Tableau Cloud

Authentication token: An authentication token is required to programmatically access the Metadata API through the GraphQL endpoint. The Metadata API uses the same authentication process and token as the Tableau REST API. For more information, see How to Authenticate.

Note: Metadata API is always enabled for Tableau Cloud.

For Tableau Server

Tableau Server 2019.3 or later.
Tableau REST API must not be disabled.
The Metadata API must be enabled. For more information about enabling the Metadata API, see the section below.
Authentication token to programmatically access the Metadata API through the GraphQL endpoint. The Metadata API uses the same authentication process and token as the Tableau REST API. For more information, see How to Authenticate.

Enable the Tableau Metadata API for Tableau Server

The Metadata API is installed with Tableau Server but disabled by default.

A server admin must enable the Metadata API on Tableau Server using the tsm maintenance metadata-services enable command through the Tableau Services Manager (TSM) command line interface (CLI). For more information, see tsm maintenance topic in the Tableau Server Help.

Running the command begins initial ingestion, which is a component of the indexing process for the Metadata API.

Open a command prompt as an admin on the initial node (where TSM is installed) in the cluster.
Run the command: tsm maintenance metadata-services enable

Notes: When running this command, keep the following points in mind:

This command stops and starts some services used by Tableau Server, which causes certain functionality, such as the Recommendations capability, to be temporarily unavailable.
A new index of metadata is created at this time. Running this command any subsequent times will create and replace the previous index.

After the requirements have been met and the Metadata API has been enabled (for Tableau Server only) you can learn about the GraphQL schema or start querying the Metadata API.

About querying the Metadata API

To get the information you need from the Metadata API, you need to be able to write queries. Queries fetch metadata about the content published to your Tableau Cloud site or Tableau Server.

Before you can begin writing these queries, you need to understand what kind of Tableau Cloud or Tableau Server metadata is available through the Metadata API and the ways for accessing the metadata. For more information, see Understand the Metadata Model.

Who can query the Metadata API

In general, all authorized users can query the Metadata API. For Tableau Server specifically, only after the Metadata API has been enabled, any authorized user can query the Metadata API.

However, what you can query and see with the Metadata API depends on whether your Tableau Cloud site or Tableau Server is licensed with Data Management.

	With Data Management	Without Data Management
See metadata	You can see your Tableau content and related external assets. You can also see external assets you’ve been granted explicit permissions to see.	You can see Tableau content. If “derived permissions” is enabled, you can also see related external assets. For more information about derived permissions: - For Tableau Cloud: Permissions on external assets using derived permissions - For Tableau Server: Permissions on external assets using derived permissions
Edit metadata and manage permissions	You can edit metadata and manage permissions for external assets that you’ve been granted explicit permissions to edit or manage permissions directly from your Tableau Cloud site or Tableau Server, or using the metadata methods in the REST API.	Not supported.

Query the API directly using GraphQL endpoint

Unlike a REST API, the Metadata API has a single [GraphQL] endpoint.

Note: To use the GraphQL endpoint, you must authenticate using the Tableau REST API. For more information, see How to Authenticate topic.

URI

http://<server-name>/api/metadata/graphql

Query

To form a query, you must specify the objects, and in some cases, objects within those objects until a unit of data can be returned.

query <query-name>{
  <object> (<arguments>){
    <attribute>
    <attribute>{
      <attribute>
    }
  }
}

Query example

query useMetadataApiToQueryOrdersDatabases{
  databases (filter: {name: "adventureworks"}){
    name
    tables{
      name
    }
  }
}

For more query examples, see the Example Queries topic.

Submitting the query

POST and Content-Type application/json

You typically submit GraphQL queries using POST and an HTTP Content-Type header of application/json, with the JSON-encoded query in the HTTP request body. A typical HTTP request body with a JSON-encoded simple GraphQL query might look like:

{"query":"query myquery{databases {name id}}"}

POST and Content-Type application/graphql

You can also submit GraphQL queries using POST and an HTTP Content-Type header of application/graphql. A typical HTTP request body with the same simple GraphQL query as above would be:

query myquery{databases {name id}}

GET

You can also submit GraphQL queries using GET and a querystring, with no request body at all. The querystring is a field-value pair where the field is query and the value is the GraphQL query, URL encoded. A typical HTTP request using the same simple GraphQL query as above would result in a URI and querystring like:

https://tableau.example.com/api/metadata/graphql?query=query%20myquery%7Bdatabases%7Bname%20id%7D%7D'

More information

For more information on typical GraphQL requests and expected interactions, see HTTP Methods, Headers, and Body on the GraphQL.org website.

Query response

The query returns only the data you specify in same shape as your query.

For the query example used above, you will see the following query response.

{
  "data": {
    "databases": [
      {
        "name": "adventureworks",
        "tables": [
          {
            "name": "AWBuildVersion"
          }
        ]
      },
      {
        "name": "adventureworks",
        "tables": [
          {
            "name": "SalesTerritory"
          },
          {
            "name": "Department"
          },
          {
            "name": "Culture"
          },
          {
            "name": "Address"
          },
          {
            "name": "Product"
          }
        ]
      },
      {
        "name": "adventureworks",
        "tables": [
          {
            "name": "CustomerAddress"
          },
          {
            "name": "Address"
          },
          {
            "name": "Customer"
          }
        ]
      }
    ]
  }
}

Permissions

Your query results are scoped to the permissions you’ve been granted. For more information, see How Permissions Work topic.

Errors

See Common Errors topic.

Explore the Metadata API schema using GraphiQL

One way to quickly get started with GraphQL queries and explore the Metadata API is to test queries against the schema. You can explore the schema using GraphiQL, which is an interactive in-browser tool. You can change the query as you like and see the results immediately.

Note: To access GraphiQL, you must sign in (authenticate) to your Tableau Cloud site or Tableau Server. The data you can see, specifically about external assets, is scoped to the permissions you’ve been granted.

Open a browser and sign in to Tableau Cloud or Tableau Server 2019.3 (or later).
Copy the following partial URL: /metadata/graphiql/
In the browser’s address bar, delete everything after the “.com”.
Paste the partial URL after the “.com” and press ENTER or RETURN.

For example, if your site’s name is “MYCO” and the site URL is:

https://us-west-2b.online.tableau.com/#/site/MYCO/explore

Change the URL to:

https://us-west-2b.online.tableau.com/metadata/graphiql/

Note: You can access the GraphiQL tool from Tableau Catalog in Tableau Cloud site or Tableau Server by clicking Query metadata (GraphiQL) in the upper-right corner of the External Assets page.

About the GraphiQL query tool

The GraphiQL query tool is comprised of several parts.

Parts of the GraphiQL interface

History pane: After you have written and run a query, it’s saved to a list so that you can reuse the query at another time. To toggle the History pane, click the History button in the toolbar.
Left pane: Build queries in the left pane. To run a query, click the play button (Execute Query) in the Toolbar. For more information about writing queries, see Example Queries.
Query Variables pane: Use this pane to define the variables that you pass to your queries.
Toolbar: Use the toolbar to run queries, see a history of queries that you’ve run, and to explore the GraphQL schema.
Middle pane: See the results of and validate your queries in the right pane.
Right pane: Toggle this pane by clicking Documentation Explorer to show the GraphQL schema. You can search the schema to see the objects that are implemented by the Metadata API and the metadata that you can query.