Example Queries


In this section

GraphQL basics

If you’re new to GraphQL, check out the many resources to learn GraphQL. For example, Introduction to GraphQL. To get you started, here are some common GraphQL query-related concepts you should understand.

Schema

The GraphQL schema tells you what queries are allowed. The schema defines the objects, object types, and attributes that you can get from the Tableau Metadata API.

Object

The building block of a query is the object. Objects are a collection of data assets accessible from the Metadata API. Objects have object types and attributes.

Queries

GraphQL operations come in the form of queries. Queries are also objects, specifically root objects in GraphQL. However, queries are special objects because they define the entry point of every GraphQL query.

For example, suppose you have the following GraphQL query:

query {    
    hello
}

The operation above begins with the required query root object. The object being requested is hello. The result of the query is:

"data": {    
    "hello": "world"
},

As you can see, GraphQL returns data in a similar shape as the query itself.

Common queries to get your started

After identifying the data that you’re interested in, you can write a query to access the information.

What types of database and table assets are used on my site?

To answer what types of databases and tables are used on your site, you might use the following query:

query getDatabasesOnMySite{
    databases {
        id
        name
    }
}
query getTablesTablesOnMySite{
    tables {
        id
        name
    }
}

Here, databases and tables are objects and id and name are attributes in the Metadata API that you can query.

Find a table

To find a specific table, such as the Orders table, you can pass a filter parameter with a value of “Orders” through the tables object. Your query might look like the following:

query ShowMeOneTableCalledOrders{
  tables (filter: {name: "Orders"}){
    name
    columns {
      name
    }
  }
}

Here, tables is the object and name and columns are attributes in the Metadata API that you can query. The filter parameter that you pass through the table object uses the format (filter: {name: "<name-of-the-table>"}).

Find a table in a workbook using query variables

To find a specific table in a workbook using a dynamic value instead of a static value in the filter parameter, you can use a query variable. A query variable is value that you can define outside of the query so that it can be changed dynamically. This query variable is a second object that’s passed through the same query.

The query variable uses the following formats depending on where the query variable is being used:

For example, suppose you want to use a query variable to find the Sample_Superstore workbook. You might use the following query, where the query variable is “$workbookname” and the value for the variable in this example is “Sample_Superstore”.

query ShowMeAnyTable($workbookName: String, $sheetName: String){
  workbooks(filter: {name: $workbookName}){
    name
    embeddedDataSources {
      fields {
        name
        ...on CalculatedField {
          formula
        }
      }
    }
  sheets(filter: {name: $sheetName}){
    name
    worksheetFields {
      name
      formula
      }
    }
  }
}

Filtering

A filter sorts through and retrieves only the data that meets a set of specified criteria.

For example, suppose you’re looking for a published data source named “Orders.” You might use the following query to find information about the published data source:

query FilteredQuery {
  publishedDatasources(filter: {name: "Orders"}) {
    name
    hasExtracts
    upstreamTables
  }
}

Here, the filter parameter that you pass through the publishedDataSources object uses the format (filter: {name: "<name-of-the-data-source>"}).

Suppose you’re looking for multiple published data sources, “Orders” and “Education.” You might use the following query to find information about these published data sources:

query FilteredWithinQuery {
  publishedDatasources(filter: {nameWithin: ["Orders", "Education"]}) {
    name
    hasExtracts
    upstreamTables
  }
}

To filter for multiple published data sources, the filter parameter that you pass through the publishedDataSources object uses the format (filter: {namewithin: ["<name-of-the-data-source1>", "<name-of-the-data-source2>"]}).

Pagination

Pagination enables you to traverse through relationships among the data that you’re querying. The Metadata API defines pagination objects as those that have “Connection” appended to it.

There are two common methods for pagination that these objects can support: offset and cursors.

Paginate using offset method

Using the offset method, you can specify the number of items you want and where to start counting the items you want retrieved. This method allows for larger queries. However, it also might affect performance of the query as the query gets larger.

For example, suppose you want to retrieve data about published data sources. In the publishedDataSourcesConnections object parameter you can specify the number of items you want using “first” and where to start counting the items you want retrieved using “offset”.

The following query gives you the first ten items.

query PaginatedQueryOffsetPage1 {
  publishedDatasourcesConnection(first: 10, offset: 0) {
    nodes {
      name
    }
  }
}

Here, the pagination format you can use for offset is (first: <value>, offset: <value>).

The following query gives you the next ten items, for a total of 20 items.

query PaginatedQueryOffsetPage2 {
  publishedDatasourcesConnection(first: 10, offset: 10) {
    nodes {
      name
    }
  }
}

Paginate using cursor method

Using cursors, you can retrieve data by specifying the page size and then using a “cursor” to keep track of where the next set of data should be retrieved from. This method is faster than the offset method when you need return results for large lists.

For example, suppose you want to retrieve data about published data sources. In the publishedDataSourcesConnection object parameter, you can specify the number of items you want using “first”.

Then, instead of counting pages using “offset” like in the offset method, you pass in “after” when using the cursor method, which is a value that is returned by the pageInfo attribute in the publishedDataSourcesConnection object.

query PaginatedQueryCursorPage1 {
  publishedDatasourcesConnection(first: 10, orderBy: {field: NAME, direction: ASC}) {
    nodes {
      name
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Notes:

When you include “after” in the parameter, the value of the “endCursor” is passed into a subsequent query.

query PaginatedQueryCursorPage2 {
  publishedDatasourcesConnection(first: 10, after: null, orderBy: {field: NAME, direction: ASC}) {
    nodes {
      name
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Permissions

There are two permission modes available in the Metadata API:

Obfuscate mode

If you do not specify a permissions mode in a query, the default permission mode, obfuscate, is applied. Obfuscate returns all results, but will hide any sensitive attributes on external assets that you do not have permissions to see. For more information, see Access Metadata about Related Asset section of the How Permissions Work topic.

You can explicitly specify the obfuscate permissions mode by passing the permissions mode parameter through the object using the format (permissionMode: OBFUSCATE_RESULTS) like in the example below.

query ObfuscatePermissionsQuery {
  databases(permissionMode: OBFUSCATE_RESULTS) {
    tables{
      downstreamDatasources{
        name
      }
    }
  }
}

In the example query above, although you might not have permissions to all the databases, the obfuscate permissions mode returns all the related data sources that you have permissions to see.

Filter mode

If you specify the filter permissions mode, only the results whose attributes of external assets you have permissions to see are returned.

You can specify the filter permissions mode by passing the permissions mode parameter through the object using the format (permissionMode: FILTER_RESULTS) like in the example below.

query FilteredPermissionsQuery {
  databases(permissionMode: FILTER_RESULTS) {
    tables{
      downstreamDatasources{
        name
      }
    }
  }
}

In the example query above, because you might not have permissions to all the database, the filter permissions mode returns only the data sources that are related to the databases and tables that you have permissions to see. This means, a query like this might omit data sources that you might have permissions to see.