Getting Started Guide

Metadata API

Nivel de dificultad
Beginner
Lenguajes de programación
GraphQL

Introduction

The metadata services discovers and indexes all of the content - data sources, workbooks, and dashboards - on your Tableau Cloud site or Tableau Server to gather metadata about the content and their associated databases and tables (also referred to as external assets). The Metadata API enables you to discover and query content and their external assets, using GraphQL, so that you can better understand relationships and lineage, and perform impact analysis.

Note: The Metadata API is already enabled in Tableau Cloud.

Before you can start querying the Metadata API, a server admin must run the tsm maintenance metadata-services enable command to enable it. Running the command begins the process of indexing the contents of Tableau Server. After the indexing process is complete, you can start querying the 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.



    

Test in your own Sandbox

Última actualización: 17 Abril, 2024