At the core of Tableau is data - your data. Your data can come in different formats and structures, categorized at varying levels of detail, and can have relationships with other data. This is the kind of metadata that you can expect to surface from the Metadata API using GraphQL.
In order to successfully create effective GraphQL queries, you need to understand how Tableau interprets and interacts with content and assets. Understanding this can inform the most efficient way for you to access metadata at the level of detail that you need.
Because the Metadata API uses GraphQL, this section describes the fundamental objects that are available to you to use in a GraphQL query.
In this section
The Metadata API surfaces the content and assets that comprise your Tableau Online site or Tableau Server, the content and asset roles, and how the content and assets relate to each other.
General Tableau content
Tableau content is unique to the Tableau platform. Content includes the following:
Tableau Online and Tableau Server specific content
Tableau content that can only be managed through Tableau Online or Tableau Server includes the following:
Note: Some content listed above can be managed through the Tableau REST API as well.
External assets associated with Tableau content
The Metadata API treats information about any data that comes from outside of the Tableau environment as external assets. External assets include the following:
Note: Cubes are not supported.
The GraphQL schema used by the Metadata API organizes content and assets on Tableau Online and Tableau Server by grouping them by object and role. These objects and their roles are the foundation to your GraphQL queries.
Parent objects, a mix of both content and assets, can be managed independently of other objects and play the role of a container. Parent objects can refer to other parent objects, can refer to child objects, and can also own child objects.
Child objects, also a mix of both content and assets, cannot be managed independently of their parent object. Therefore, child objects play a dependent role on their parent object.
Some child objects can own other child objects, can refer to other child objects, and in some cases, refer to certain parent objects.
The GraphQL schema defines the parent/child object relationship by what the objects can own or contain. In other words, an object is a parent object when it functions as a container for other (child) objects.
|Parent object||Can own or contain objects...|
Parallel to parent/child object role and relationship, the GraphQL schema organizes objects by object type and the attributes that it can inherit from the object.
To do this, objects are implemented in the GraphQL schema using “interfaces.” From each interface, object types inherit attributes and properties. This means that the object types that have the same interface have a logical association with each other and share common attributes and properties. In addition to the shared attributes and properties, object types can also have unique attributes and properties.
Examples of object types and their inherited attributes
The table below captures example objects, object types (interface), and their common and unique attributes and properties.
|Object||Object type or interface||Common attributes and properties||Unique attributes and properties|
|Warnable (data quality warning)||
Lineage shortcut objects
The Metadata API enables you to see relationships between the content and asset that you’re evaluating with other items on your Tableau Online site or Tableau Server. These items include the following:
You can quickly access this type of information by using shortcut objects defined in the GraphQL schema. These lineage or relationship objects use the upstream or downstream prefix. For example, you can use
upstreamTablesConnection to query the tables used by a data source or use
downstreamSheetsConnection to query sheets used by a workbook.
For an example query that uses lineage shortcut, see Filtering section in the Example Queries topic.
The Metadata API enables you to traverse through relationships within the data that you’re querying using pagination. The GraphQL schema defines pagination objects as those objects that use the Connection suffix. For example, you can use the
databasesConnection to get a list of paginated results of database assets on your Tableau Online site or Tableau Server.
For an example query that uses pagination, see Pagination section in the Example Queries topic.
Together, all objects, the roles they play, the relationships they have with each other and their attributes and properties define the metadata model for a particular set of objects. The metadata model is a snapshot (or in GraphQL terms, a graph) of how Tableau interprets and relates a set of objects on your Tableau Online site or Tableau Server. From the metadata model, you can understand the dependencies and relationships in your data.
To see how the metadata model used by the Metadata API works, review the following example scenarios.
Suppose you have three workbooks (parent objects) and two data sources (parent objects) published to Tableau Online or Tableau Server.
For this scenario, the two published data source objects refer to the three workbook objects. The workbook objects own four sheet objects. These sheet objects in turn refer to two field objects that are owned by the published data source objects.
Here’s what the metadata model for this scenario might look like.
In an impact analysis scenario, the metadata model can help you answer how data might be affected if a part of the metadata model changes.
In this scenario, you might want to know what could happen if the published data source, John County - 1, is deleted.
As you know now from the metadata model, sheet objects are owned by workbook objects, and sheet objects can refer to the field objects. In this scenario, the field objects are owned by the published data source objects. Published data source objects own field objects. Therefore, if John County - 1 is deleted, the child objects, F1, Hills Library, and Garden Library, are directly affected and their existence compromised because of their dependency on that data source object. The other child objects, F2, Garden Senior Center, and Cliff Senior Center, though they might be affected by the data source object being deleted, their existence is not compromised.
During this analysis, you can see that because John County - 1 doesn’t own the workbook objects that connect to it, the workbook objects themselves, both Sakura District and Maple District can continue to exist in the absence of the published data source object.
In a lineage flow analysis scenario, you can look at particular part of the metadata model and identify where the data is coming from and how the data reacts or is affected by different parts of the metadata model.
In this scenario, you might want to know where a data point from a sheet object, Garden Senior Center, in a workbook object, Maple District, is coming from.
Based on what you know from the metadata model, attributes are inherited from the parent object . Therefore, if you start from Garden Senior Center sheet object, you can move to the referring field object, F2, to see that it’s owned by a published data source object. In this case, John County - 2 is the source for the data point.
During this analysis, you are able to freely include or exclude parts of the metadata model in order to understand the lineage flow for Garden Senior Center. For example, you can choose to exclude Garden Library sheet object even though it’s also owned by the same workbook object, Maple District.
When using custom SQL
The metadata model interprets customSQL queries as tables.
When custom SQL queries are defined in your data source or flow, the queries have to fit a set of criteria to be recognized and interpreted by the Metadata API. For more information, see Tableau Catalog support for custom SQL in the Tableau Help.
When you run a query using the databaseTable object, for some databases, the schema attribute might not return the correct schema name for the table. This issue can occur when the selected schema, while creating or editing a data source, workbook, or flow, is changed after adding the table.
When the selected schema changes after adding the table, the schema attribute your query returns is the name of the last selected schema instead of the actual schema that the table is using.
Databases that might return the incorrect schema in the scenario described above include Amazon Athena and Exasol.
When you run a lineage query to determine upstream databases (D1 and D2) from a workbook (WB), only the databases (D1) whose fields (F1) are used in a workbook’s sheet (S) are returned. Databases (D2) that might be referenced by the workbook, but whose fields aren’t used by a sheet directly, won’t show as upstream.