To get started, review the requirements necessary to use the Tableau Metadata API.
In this section
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
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.
tsm maintenance metadata-services enable
Notes: When running this command, keep the following points in mind:
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.
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.
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. |
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.
http://<server-name>/api/metadata/graphql
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 useMetadataApiToQueryOrdersDatabases{
databases (filter: {name: "adventureworks"}){
name
tables{
name
}
}
}
For more query examples, see the Example Queries topic.
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}}"}
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}}
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'
For more information on typical GraphQL requests and expected interactions, see HTTP Methods, Headers, and Body on the GraphQL.org website.
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"
}
]
}
]
}
}
Your query results are scoped to the permissions you’ve been granted. For more information, see How Permissions Work topic.
See Common Errors topic.
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.
/metadata/graphiql/
.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.
The GraphiQL query tool is comprised of several parts.