Get Started


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

In this section

Requirements

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

For Tableau Online

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 Online.

For Tableau Server

After the requirements have been met, 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 Tableau Online or Tableau Server.

Before you can begin writing these queries, you need to understand what kind of Tableau Online 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 see with and do using the Metadata API depends on whether your Tableau Online site or Tableau Server is licensed with the Data Management Add-on.

  Licensed Not Licensed
See You can see your Tableau content and external assets. You can also see external assets you’ve been granted explicit permissions to see. If “derived permissions” is enabled, you can see your Tableau content and external assets.
Manage permissions and edit You can manage permissions for or edit external assets that you have been granted explicit permissions to manage permissions or edit. You can’t manage permissions for or edit external assets.

For more information on “derived permissions” see one of the following topics:

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 body

To form a query body, 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 body example

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

For more examples, see Example Queries topic.

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 Tableau Online or Tableau Server. The data you can see, specifically about external assets, is scoped to the permissions you’ve been granted.

  1. Open a browser and sign in to Tableau Server 2019.3 (or later) or Tableau Online.
  2. Copy the following partial URL: /metadata/graphiql/
  3. In the browser’s address bar, delete everything after the “.com”.
  4. 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 Online or Tableau Online 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

  1. 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.
  2. 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.
  3. Query Variables pane: Use this pane to define the variables that you pass to your queries.
  4. Toolbar: Use the toolbar to run queries, see a history of queries that you’ve run, and to explore the GraphQL schema.
  5. Middle pane: See the results of and validate your queries in the right pane.
  6. 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.