--- schema_version: "1" id: 95436017c3fc7b64255f632c85895524218c9e24b931fff042039e692d336bb5 title: Understand the Metadata Model collection: tableau version: next locale: en-us portal_url: https://docs.salesforce.com/tableau/next/en-us/api/metadata_api/docs/meta_api_model.md canonical_url: https://help.tableau.com/v0.0/api/metadata_api/en-us/docs/meta_api_model.html source_site: help.tableau.com content_type: documentation content_hash: 492a4d01981551f89e52290c0f91ab9b84c674e811bd99a1b667c640ce86e752 description: Documentation for the Tableau Metadata API --- # Understand the Metadata Model 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. 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** ## Tableau content and assets The Metadata API surfaces the content and assets that comprise your Tableau Cloud 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: - Data sources - both published and embedded - Workbooks - Sheets - Dashboards - including stories - Fields: calculated, column - as they relate to the data source, group, bin, set, hierarchy, combined, and combined set - Filters: data source - Parameters - Flows - Virtual connections - Virtual connection tables **Tableau Cloud and Tableau Server specific content** Tableau content that can only be managed through Tableau Cloud or Tableau Server includes the following: - Sites - Projects - Users - Certifications and certifiers - Data quality warnings and messages Note: Some content listed above can be managed through the [Tableau REST API \[↗\]](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm) 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: - Databases - includes local files, remote connections to servers, and web data connectors (WDC) - Tables - includes queries (custom SQL) **Note:** Cubes are not supported. ### Objects and their roles The GraphQL schema used by the Metadata API organizes content and assets on Tableau Cloud and Tableau Server by grouping them by object and role. These objects and their roles are the foundation to your GraphQL queries. #### Parent object and role 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. **Example parent objects** - Databases - Tables - Published data sources - Virtual connections - Virtual connection tables - Workbooks - Flows - Sites - Projects - Users #### Child object and role 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. **Example child objects** - Columns - Fields - Embedded data sources - Sheets - Parameters - Data source filters #### Parent/child object relationship The GraphQL schema defines the parent/child object relationship by what the objects can contain. In other words, an object is a parent object when it functions as a container for other (child) objects. Some examples of such relationships are below. **Example parent/child relationships** - Database - DatabaseTable - Column - PublishedDatasource - Field - DataSourceFilter - Parameter - DataQualityWarning - DataQualityCertification - Workbook - View - EmbeddedDatasource - Field - Parameters ### Object types and attributes The GraphQL schema organizes objects into interfaces and types. - An **interface** defines a list of attributes (known as “fields” in GraphQL) that are required for that interface. - A **type** implements an interface, and may define additional attributes. In other words, an **interface** serves as template (of sorts) for a **type**, in that it defines a list of attributes that will be common to all types that are based on it. Any **type** that uses the **interface** as a template (we say that “the **type** implements the **interface**”) will contain all the common attributes of the **interface**, plus any other attributes added by the **type**. For more information on GraphQL interfaces, objects, and fields, see [Schemas and Types \[↗\]](https://graphql.org/learn/schema/) in the [GraphQL documentation \[↗\]](http://www.graphql.org). **Examples of interfaces, types, and attributes** The table below captures some example interfaces, some example attributes (fields) they must contain, some types that implement that interface, and some attributes that the type adds.
Interface Interface attributes Type that implements the interface Fields added to those required by interface
Database CertificationNote
certifier
connectionType
contact
dataQualityCertifications
dataQualityWarning
dataQualityWarnings
description
downstreamDashboards
downstreamDatabases
downstreamDatasources
downstreamFlows
downstreamLenses
downstreamMetrics
downstreamOwners
downstreamSheets
downstreamTables
downstreamVirtualConnections
downstreamVirtualConnectionTables
downstreamWorkbooks
hasActiveWarning
id
isCertified
isControlledPermissionsEnabled
isEmbedded
isGrouped
luid
name
tags
upstreamDatabases
upstreamDataQualityWarnings
upstreamDatasources
upstreamFlows
upstreamTables
upstreamVirtualConnections
upstreamVirtualConnectionTables
vizportalId
 CloudFile fileExtension
fileId
mimeType
provider
requestUrl
DatabaseServer extendedConnectionType
hostName
port
service
File filePath
WebDataConnector connectorUrl
Table columns
description
downstreamDashboards
downstreamDatabases
downstreamDatasources
downstreamFlows
downstreamLenses
downstreamMetrics
downstreamOwners
downstreamSheets
downstreamTables
downstreamVirtualConnections
downstreamVirtualConnectionTables
downstreamWorkbooks
id
isEmbedded
name
upstreamDatabases
upstreamDatasources
upstreamFlows
upstreamTables
upstreamVirtualConnections
upstreamVirtualConnectionTables		 VirtualConnectionTable containsUnsupportedCustomSql
dataQualityCertifications
dataQualityWarnings
extractLastRefreshedAt
extractLastRefreshType
hasActiveWarning
isCertified
isExtracted
luid
owner
tags
upstreamDataQualityWarnings
uri
vizportalId
vizportalUrlId
DatabaseTable certificationNote
certifier
connectionType
contact
database
dataQualityCertifications
dataQualityWarning
dataQualityWarnings
fullName
hasActiveWarning
isCertified
luid
schema
tags
upstreamDataQualityWarnings
vizportalId
CustomSQLTable connectionType
database
isUnsupportedCustomSql
query
tables
### Other objects related to Tableau content and assets **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 Cloud site or Tableau Server. These items include the following: - Upstream and downstream content - including data sources, workbooks, sheets, virtual connections, virtual connection tables, fields, flows, and owners - Upstream and downstream assets - including databases, tables, and columns 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, use `downstreamSheetsConnection` to query sheets used by a workbook, or `upstreamLinkedFlows` and `downstreamLinkedFlows` to query flows that are directly upstream or downstream of one another. For an example query that uses lineage shortcut, see [Filtering](/v0.0/api/metadata_api/en-us/docs/meta_api_examples.html#filtering) section in the Example Queries topic. For more information about linked flows, see [Working with linked flow objects](#linkedtasks_flows) below. **Pagination objects** 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 Cloud site or Tableau Server. For an example query that uses pagination, see [Pagination](/v0.0/api/metadata_api/en-us/docs/meta_api_examples.html#pagination) section in the Example Queries topic. **Inherited objects** You can query description attributes of fields using the Metadata API. These description attributes can be inherited from other upstream objects. For example, a field attribute can be inherited from an upstream column in a table or from an upstream data source authored in Tableau Desktop. Beginning in version 2021.2, you can include a description inheritance object, `descriptionInherited`, in your query to return supplemental description information inherited from the closest upstream object. For an example query that uses the description inheritance object, see [Inheritance](/v0.0/api/metadata_api/en-us/docs/meta_api_examples.html#inheritance) section in the Examples Queries topic. ## Tableau metadata model 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 Cloud 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. ### Example metadata model Suppose you have three workbooks (parent objects) and two data sources (parent objects) published to Tableau Cloud or Tableau Server. ![Example scenario on Tableau Cloud or Tableau Server](/v0.0/api/metadata_api/en-us/docs/assets/ex_assets_server.png) 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. ![Example of metadata model for this scenario](/v0.0/api/metadata_api/en-us/docs/assets/ex_assets_all.png) **Notes:** - A sold line with an arrow indicates a ownership relationship. - A dotted line indicates a reference relationship. ### Example scenario 1: Impact analysis 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. ![Example of metadata model when published data source, John County - 1, is deleted](/v0.0/api/metadata_api/en-us/docs/assets/ex_assets_impact.png) 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. ### Example scenario 2: Lineage analysis 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. ![Example of metadata model with a focus on a sheet, Garden Senior Center](/v0.0/api/metadata_api/en-us/docs/assets/ex_assets_lineage.png) 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_. ### Additional notes about the metadata model **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 \[↗\]](https://help.tableau.com/current/pro/desktop/en-us/customsql.htm#tableau-catalog-support-for-custom-sql) in the Tableau Help. For programmatic methods to determine if the custom SQL used in a data source or flow is unsupported, see the isUnsupportedCustomSql and containsUnsupportedCustomSql booleans in the API reference. **Using the databaseTable object in a query** When you run a query using the [databaseTable](https://help.tableau.com/current/api/metadata_api/en-us/reference/databasetable.doc.html) 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 workbook lineage query results are missing upstream databases** 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. ![Example of a workbook with a focus on its upstream database](/v0.0/api/metadata_api/en-us/docs/assets/shortcuts_ex_wb_to_db.png) **Running a tags query** Unless you’re a Tableau Cloud site or Tableau Server admin, by default, results from a tags query that uses the asset attribute are obfuscated to block all sensitive data. Results are always obfuscated, whether you have the appropriate permissions to see the associated object’s metadata or not. To see the associated object’s metadata that you have the appropriate permissions to see, you can replace the asset attribute with a type-specific attribute instead. For example, suppose you have permissions to see WorkbookA. You run the following tags query, which uses the asset attribute to return all objects that use tags. ``` { tags { assets { id name } } } ``` In this example, the query returns two workbooks with its results obfuscated. ``` { tags { assets { { id: "A", name: null } { id: "B", name: null } } } } ``` Because results are always obfuscated when you use the asset attribute in a tags query, you can modify the query to be type specific to return the results you expect. In this example, you can run a query using the workbook type instead. ``` { tags { workbooks { id name } } ``` When you modify the tags query to be type specific, the query returns the tags metadata for WorkbookA. ``` { tags { workbooks { { id: "A", name: "WorkbookA" } { id: "B", name: null } } } ``` **Working with linked flow objects** Unlike `upstreamFlows` and `downstreamFlows` objects, which return all upstream and downstream flows, queries that include `upstreamLinkedFlows` and `downstreamLinkedFlows` objects return additional structural metadata about upstream and downstream flows. The `upstreamLinkedFlows` and `downstreamLinkedFlows` objects can provide information about order, distance, and relationship between flows that are directly upstream and downstream of one another. For example, suppose you have a flow called Superstore. You can run the following query to compare the information returned for the flows upstream of the Superstore flow. ``` query upstreamflows_vs_upstreamlinkedflows { flows(filter: {name:"Superstore_AllUp"}) { name id upstreamFlows{ name id } upstreamLinkedFlows{ asset{ name id } toEdges fromEdges } } } ``` The above query returns the following information. ``` { "data": { "flows": [ { "name": "Superstore_Customers", "id": "089839c4-7edd-b887-3178-fcc2367e938b", "upstreamFlows": [ { "name": "Superstore_Pods", "id": "66e8f90d-f02d-eea1-850e-2014b4b09b96" }, { "name": "Superstore_Marketing", "id": "7efe5f86-511b-760b-18d4-1a6a28c220b5" }, { "name": "Superstore_Operations", "id": "cd79250f-bc27-1d9d-7b22-aca1534863e1" }, { "name": "Superstore_Sales", "id": "e78d4c54-df3a-12a9-ef1a-9849c2625b35" } ], "upstreamLinkedFlows": [ { "asset": { "name": "Superstore_Customers", "id": "089839c4-7edd-b887-3178-fcc2367e938b" }, "toEdges": [ "e78d4c54-df3a-12a9-ef1a-9849c2625b35", "7efe5f86-511b-760b-18d4-1a6a28c220b5", "cd79250f-bc27-1d9d-7b22-aca1534863e1" ], "fromEdges": [] }, { "asset": { "name": "Superstore_Sales", "id": "e78d4c54-df3a-12a9-ef1a-9849c2625b35" }, "toEdges": [ "cd79250f-bc27-1d9d-7b22-aca1534863e1" ], "fromEdges": [ "089839c4-7edd-b887-3178-fcc2367e938b" ] }, { "asset": { "name": "Superstore_Marketing", "id": "7efe5f86-511b-760b-18d4-1a6a28c220b5" }, "toEdges": [], "fromEdges": [ "089839c4-7edd-b887-3178-fcc2367e938b" ] }, { "asset": { "name": "Superstore_Operations", "id": "cd79250f-bc27-1d9d-7b22-aca1534863e1" }, "toEdges": [ "66e8f90d-f02d-eea1-850e-2014b4b09b96" ], "fromEdges": [ "089839c4-7edd-b887-3178-fcc2367e938b", "e78d4c54-df3a-12a9-ef1a-9849c2625b35" ] }, { "asset": { "name": "Superstore_Pods", "id": "66e8f90d-f02d-eea1-850e-2014b4b09b96" }, "toEdges": [], "fromEdges": [ "cd79250f-bc27-1d9d-7b22-aca1534863e1" ] } ] } ] }, } ``` - From the upstreamFlows object, the following upstream flows are returned: Superstore\_Pods, Superstore\_Marketing, Superstore\_Operations, and Superstore\_Sales. - Whereas, from the upstreamLinkedFlows object, the following information is returned: - From the `asset` parameter, you see Superstore\_Customers is returned. This is the source flow or the flow from which you want to understand its relationship to other flows. - From the `fromEdges` parameter, you see three direct flows that Superstore\_Customer links from: Superstore\_Marketing, Superstore\_Operations, and Superstore\_Sales. In addition, you see additional flow relationships information about those three direct flows. - Superstore\_Marketing, `fromEdges` parameter shows Superstore\_Customers as its direct upstream flow and the `toEdges` parameter shows no direct downstream flows. - Superstore\_Operations, `toEdges` shows both Superstore\_Customers and Superstore\_Sales as its direct upstream flows and `toEdges` shows Superstore\_Pods directly downstream of it. - From the `toEdges` parameter, you see that Superstore\_Customers has no direct flows it links to. In other words, Superstore\_Customers is at the bottom of its relationship chain. ![Example of structual metadata returned from linked flows object](/v0.0/api/metadata_api/en-us/docs/assets/shortcuts_linked_flows.png)