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 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 useMetadataApiToQueryOrdersDatabases{
databases (filter: {name: "adventureworks"}){
name
tables{
name
}
}
}
For more examples, see Example Queries topic.
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.