Metadata API

Start exploring the Metadata API using GraphiQL, an interactive in-browser tool. To access GraphiQL, you must sign in (authenticate) to your Tableau Cloud site or Tableau Server.

1. Open a browser and sign in to Tableau Cloud or Tableau Server (version 2019.3 or later).
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/

Because you’ve authenticated to your Tableau Cloud site or Tableau Server, skip to Step 4: Query the Metadata API below to learn about GraphQL queries.

The Metadata API requires that you send an authentication token with each query sent. The token lets your Tableau Cloud site or Tableau Server verify your identity and ensures that you’re signed in. To get a token, you can call the REST API’s (version 3.6 and later) Sign In method, in one of the following ways:

• Using a personal access token - for more information, see the personal access token section of the Tableau REST API Help.
• Using username and password - for more information, see the username and password section of the Tableau REST API Help.

If you’re programmatically accessing the Metadata API, after your identity has been verified, you only need to use a single endpoint: http://<server-name>/api/metadata/graphql to start querying the Metadata API. For example, you might want to query the Metadata API using Tableau Server Client library (Python) demonstrated in this sample script.

Using the GraphQL language, you write a query to specify the objects, and in some cases, objects within those objects, until a unit of data can be returned.

In general, a query takes the following shape:

query your_query_name{
  <object> (<arguments>){
    <attribute>
    <attribute>{
      <attribute>
    }
  }
}

For example, suppose you work with the “adventure_works” database and you’re planning on making some updates to it. You might use the following query to better understand the relationship between the database and the potential impact any changes might have across the workbooks that connect to that database.
 

query get_workbooks {
  databases (filter: {name: "adventure_works"}){
    name
    tables{
      name
    }
    downstreamWorkbooks{
      name
    }
  }
}    

In this example, the query returns two databases. The first database has no downstream workbooks and the second database has two downstream workbooks.