GraphQL for Advanced Tableau Metadata Analysis

Applying GraphQL (Metadata API)

Even with the REST API and PostgreSQL repository, understanding the full picture of Tableau metadata can remain challenging. Whether on-prem or Cloud, GraphQL (Tableau Metadata API) gives you powerful, flexible ways to work with metadata in a single round-trip. For a high-level comparison of all three access methods across both platforms, see Part 2: Tableau Cloud vs On-Premise — Metadata Access Comparison.

Why GraphQL?

The key difference between REST and GraphQL is flexibility and depth: unlike the REST API, GraphQL lets you get complex answers in a single request, and you don’t need a Python environment to run it.

With the REST API you often need multiple calls and complicated loops to piece together the whole structure. With GraphQL, a single query fetches complex nested relationships in one shot.

Getting Started and Practical Examples

To get started, make sure the Metadata API service is enabled on your Tableau Server:

tsm maintenance metadata-services enable

Once activated, navigate to https://<your-tableau-server>/api/metadata/graphiql to access the built-in GraphQL explorer, where you can quickly test and iterate on queries.

Here’s a simple query that returns workbook lineage all the way down to the underlying database tables:

query {
  workbooks {
    name
    projectName
    owner {
      name
    }
    embeddedDatasources {
      name
      upstreamTables {
        name
        database {
          name
        }
      }
    }
  }
}

And here’s an example of what you receive in response:

{
  "data": {
    "workbooks": [
      {
        "name": "Sales Performance Dashboard",
        "projectName": "Finance",
        "owner": {
          "name": "john.smith"
        },
        "embeddedDatasources": [
          {
            "name": "Sales_Data",
            "upstreamTables": [
              {
                "name": "sales_transactions",
                "database": {
                  "name": "analytics.company-prod.snowflakecomputing.com"
                }
              },
              {
                "name": "product_catalog",
                "database": {
                  "name": "analytics.company-prod.snowflakecomputing.com"
                }
              }
            ]
          },
          {
            "name": "Marketing_Data",
            "upstreamTables": [
              {
                "name": "campaign_performance",
                "database": {
                  "name": "analytics.company-prod.snowflakecomputing.com"
                }
              }
            ]
          }
        ]
      }
    ]
  }
}

This single query immediately provides essential lineage details:

• Workbook name, project, and owner.
• Data sources (logical, business-ready views in Tableau built by combining and transforming different physical or logical sources).
• All upstream database tables (the data marts coming directly from your DWH).

Impact Analysis and Data Governance

GraphQL helped us proactively manage changes in our dashboards. When data engineers planned schema updates to critical tables, we ran a quick query to identify affected dashboards before the change happened — proactive analysis prevented unexpected breakages.

We also automated queries to extract all the fields used in each workbook (including the underlying formulas and calculations — GraphQL is the only way to extract calculation expressions) and stored the results in our internal database. This created a comprehensive metadata lineage catalog, which is valuable for:

• Automatic dependency checks: analysts and developers can quickly review dependencies and compare metric formulas across workbooks. This helped us find discrepancies between the same metrics in different dashboards and enforce standards going forward.
• Enhanced governance & cost reduction: this catalog replaced manual reference updates and reduced the need for Explorer (web-edit) licenses for roles that don’t require BI development.

Conclusion: A Stronger BI Product

By combining Tableau’s REST API for routine automation, GraphQL for deep lineage analysis, and PostgreSQL repository for granular auditing and permissions management, we significantly strengthened our BI environment.

We now can:

• Effectively track and control user permissions and row-level security, ensuring data security and compliance.
• Quickly identify inactive or duplicate user accounts, optimizing license management.
• Proactively manage data schema changes, preventing unexpected dashboard failures.
• Automatically document and govern metric definitions, replacing manual effort and reducing costs.

Whether you’re running Tableau Cloud or on-premises Tableau Server, mastering metadata dramatically improves governance, transparency, and user trust in your Business Intelligence product. My journey in mastering Tableau metadata transformed our BI practice, and I hope my experience inspires you to start your own metadata journey.