Using Fields in the REST API

You can control the type and amount of data that gets returned from requests to the following REST API endpoints:

Get Users on Site

[API reference | Field list]
Query Datasources

[API reference | Field list]
Query Views for Site

[API reference | Field list]
Query Workbooks for Site

[API reference | Field list]
Query Projects

[API reference | Field list]
Query Jobs

[API reference | Field list]
Query Groups

[API reference | Field list]
Get Favorites for user

[API reference | Field list]
List Metrics for Site

[API reference | Field list]

Fields and resources

Fields are the named elements and attributes associated with Tableau Server resources, such as workbooks, data sources, projects, views, and owners. For example, the fields of the workbooks resource includes the workbook id, the workbook name. Depending upon the resource, the fields can include additional attributes and elements for child or sub-resources, such as the project name (project.name) and id (project.id), and description (project.description), .or owner attributes, and tags .

By default, methods like Query Workbooks for Site return information about all of the workbooks on a Tableau Server site. If you are only interested in a subset of these, for example the names of the workbooks, you could search through the response data for the workbook names. But if there are a large number of workbooks, you could be looking through pages of data. You could filter the response data by using filtering and sorting, but that requires that you know what the names are to setup the filters. Starting in REST API 2.5 (Tableau 10.2), you can add field expressions to the query string of the URI. By adding a field expression, you can tailor the response to return only the data for the resource elements you are interested in.

You add a field expression as a query string using the following general format:

<URI>?fields=<field-expression>

For example, you could use a field expression to query a Tableau Server for the just the names of the workbooks:

http://localhost/api/2.5/sites/1a10f5b9-029b-43e4-a620-773d1690338c/workbooks?fields=name

In this case, the method queries a Tableau Server site and only the names of workbooks are returned in the response packet.

<tsResponse http://tableau.com/api/ts-api-2.5.xsd">
    <pagination pageNumber="1" pageSize="100" totalAvailable="11" />
    <workbooks>
        <workbook name="Superstore" />
        <workbook name="Regional" />
        <workbook name="Backgrounder" />
        <workbook name="ClusterController" />
        <workbook name="Config" />
        <workbook name="VizqlServer" />
        <workbook name="Netstat" />
        <workbook name="Apache" />
        <workbook name="VizqlDesktop" />
    </workbooks>
</tsResponse>

Creating field expressions

You can create field expressions to use with a set of REST API query methods for Tableau Server resources. The resources are workbooks, data sources, views, and users. Each resource has a set of fields (for example, the name or id of a workbook or owner. In addition, each resource can contain additional elements (or sub-resources). For example, a workbook contains project resource. You can combine fields and resources to create complex field expressions. For example, you can query for the names of all the workbooks and the names of the projects associated with those workbooks.

Field expression syntax

A field expression has the following syntax:

fields=[keyword,][field, | resource, | resource.field,]...

Note: Field names, keywords, and resources are case sensitive.

keyword

(Optional) The keyword option can take two values. If you do not specify a field expression with your query, the response returns a default set of fields. If specified, the keyword must appear as the first value in the field expression.

Keyword Description

_all_ Returns all the available fields for the requested resource and any additional nested-resources. You can use this value to determine what the available fields are for a given resource.

_default_ Returns the default fields for the requested resource and the default fields for any additional nested resources. The default fields are the same fields that are returned by the query method before any field expression is added. You can combine the _default_ keyword in field expressions with additional fields or resources to return all the default fields and ones that are not part of the default set (for example, Fields=_default_,owner.name).

Keyword	Description
`_all_`	Returns all the available fields for the requested resource and any additional nested-resources. You can use this value to determine what the available fields are for a given resource.
`_default_`	Returns the default fields for the requested resource and the default fields for any additional nested resources. The default fields are the same fields that are returned by the query method before any field expression is added. You can combine the `_default_` keyword in field expressions with additional fields or resources to return all the default fields and ones that are not part of the default set (for example, `Fields=_default_,owner.name`).

field

Specifies the element of the resource that should be returned from the query. The fields that are available depend upon the method and resource that is the object of the query, and whether the query keyword asks for all fields (_all_) or the default fields (_default_).

resource

Specifies the additional (or nested) resource that should be returned from the query. The additional resources depend upon the method and resource that is the object of the query, and whether the query keyword asks for all fields (_all_) or the default fields (_default_). You do not need to specify the resource already queried by the method. For example, if you use Query Workbooks for Site, you do not need to specify workbook as a resource.

Resources and fields by method

The following table shows the fields and resources that are available for the currently supported endpoints. The default fields and resources are included when you call the method without a field expression, or when you specify the keyword _default_ in the field expression. Additional fields are returned when you use the _all_ keyword in the field expression.

To specify fields for the supported resources, you use the dot notation, for example, project.id or owner.siteRole.

To specify non-default fields that are elements of a resource, such as the name of the owner of a project or the id of a workbook containing a specified view, you can combine the default keyword with additional fields to return just the information you are interested in (for example, ?fields=_default_,owner.name)

Query Datasources Fields (Fields in bold face are included in the response by default.)
Datasource Use either: `datasource.field` or: `field` `contentUrl` `id` `name` `type` `description` `createdAt` `updatedAt` `encryptExtracts` `isCertified` `useRemoteQueryAgent` `webPageUrl` `size` `tag` `favoritesTotal` `databaseName` `connectedWorkbooksCount` `hasAlert` `hasExtracts` `isPublished` `serverName`	Owner Use: `_default_,owner.sub-field` `owner.id` `owner.name` `owner.fullName` `owner.siteRole` `owner.lastLogin` `owner.email`	Project Use: `_default_,project.sub-field` `project.id` `project.name` `project.description`
Get Users on Site Fields (Fields in bold face are included in the response by default.)
User Use either: `user.field` or `field` `externalAuthUserId` `id` `name` `siteRole` `lastLogin` `fullName` `email` For servers configured with site-specific SAML(Link opens in a new window): `authSetting`
Query Views for Site Fields (Fields in bold face are included in the response by default.)
View Use either: `view.field` or `field` `id` `name` `contentUrl` `createdAt` `updatedAt` `tags` `sheetType` `usage`	Workbook Use: `_default_,workbook.sub-field` `workbook.id` `workbook.description` `workbook.name` `workbook.contentUrl` `workbook.showTabs` `workbook.size` `workbook.createdAt` `workbook.updatedAt` `workbook.sheetCount` `workbook.hasExtracts` `workbook.tags`	Owner Use: `_default_,owner.sub-field` `owner.id` `owner.name` `owner.fullName` `owner.siteRole` `owner.lastLogin` `owner.email`	Project Use: `_default_,project.sub-field` `project.id` `project.name` `project.description`
Query Workbooks for Site Fields (Fields in bold face are included in the response by default.)
Workbook Use either: `workbook.field` or `field` `description` `id` `name` `contentUrl` `showTabs` `webpageUrl` `size` `createdAt` `updatedAt` `encryptExtracts` `defaultViewId` `tag` `sheetCount` `hasExtracts`	Owner Use: `_default_,owner.sub-field` `owner.id` `owner.name` `owner.fullName` `owner.siteRole` `owner.lastLogin` `owner.email`	Project Use: `_default_,project.sub-field` `project.id` `project.name` `project.description`
Query Projects Fields (Fields in bold face are included in the response by default.)
Project Use either: `project.field` or `field` `id` `name` `description` `createdAt` `updatedAt` `contentPermissions` `parentProjectId` `topLevelProject` `writeable`	Owner Use: `_default_,owner.sub-field` `owner.id` `owner.name` `owner.fullName` `owner.siteRole` `owner.lastLogin` `owner.email`	Contents Counts Use: `_default_,contentsCounts.sub-field` `contentsCounts.projectCount` `contentsCounts.viewCount` `contentsCounts.datasourceCount` `contentsCounts.workbookCount`
Query Jobs Fields (Fields in bold face are included in the response by default.)
Background Job Use either: `job.field` or `field` `id` `status` `createdAt` `startedAt` `endedAt` `priority` `jobType` `title` `subtitle`
Query Groups Fields (Fields in bold face are included in the response by default.)
Group Use either: `group.field` or `field` `id` `name` `domain name` `userCount` `minimumSiteRole`
Get Favorites for user Fields (Fields in bold face are included in the response by default.)
Favorites Use either: `favorite.field` or `field` `label` `parentProjectName` `targetOwnerName`	Datasource Use: `_default_,datasource.sub-field` `datasource.id` `datasource.name` `datasource.description` `datsource.contentUrl` `datasource.type` `datasource.createdAt` `datasource.updatedAt` `datsource.encryptExtracts` `datasource.isCertified` `datasource.useRemoteQueryAgent` `datasource.webpageUrl` `datasource.serverName` `datasource.databaseName`	Project Use: `_default_,project.sub-field` `project.id` `project.name` `project.description`	User Use: `_default_,user.sub-field` `user.id` `user.name` `user.fullName` `user.siteRole` `LastLogin` `Email`	Workbook Use: `_default_,workbook.sub-field` `workbook.id` `workbook.name` `workbook.description` `workbook.contentUrl` `workbook.showTabs` `workbook.tags` `workbook.size` `workbook.createdAt` `workbook.updatedAt` `sheetCount` `hasExtracts`	View Use: `_default_,view.sub-field` `view.id` `view.name` `view.contentUrl` `view.createdAt` `view.updatedAt`
List metrics for site Fields (Fields in bold face are included in the response by default.)
Metrics Use either: `metric.field` or `field` `id` `name`	Owner Use: `_default_,owner.sub-field` `owner.id` `owner.name` `owner.fullName` `owner.siteRole` `owner.lastLogin` `owner.email`	project Use: `_default_,owner.sub-field` `project.id` `project.name` `project.description`

Combining field expression with filtering and sorting

You can combine field expressions with filtering and sorting to further refine the data you want returned from the method. For example, you can filter on the date a workbook was last updated and then combine that with the field expression to return just the names of the workbooks that meet that criteria. You combine expressions using an ampersand (&). The URI and query string to return workbook names that were updated after a specified date might look like the following:

http://localhost/api/2.5/sites/1a10f5b9-029b-43e4-a620-773d1690338c/workbooks?filter=updatedAt:gte:2016-10-27T00:49:27Z&fields=name

Note that the fields supported by the ?filter= and ?sort= expressions might differ from the fields and resources that you can use in ?fields= expressions. For information about the fields that can be used for filtering and sorting see, Filtering and Sorting in the Tableau REST API.

Examples of using fields in the REST API

Example 1: The following URI shows the query to return just the id of the workbooks on the Tableau Server.

http://localhost/api/2.5/sites/1a10f5b9-029b-43e4-a620-773d1690338c/workbooks?fields=id

Example 2: The following example returns the default fields and the additional specified fields (owner name, project description) for the resource workbooks.

http://localhost/api/2.5/sites/1a10f5b9-029b-43e4-a620-773d1690338c/workbooks?fields=_default_,owner.name,project.description

Example 3: The following example returns the name of the workbooks and the default fields for the projects associated with the workbooks. In this case, the default fields are the project name and id. Because this URI queries the workbook resource, it is not necessary to specify workbook.name. You could also use ?fields=name.

http://localhost/api/2.5/sites/1a10f5b9-029b-43e4-a620-773d1690338c/workbooks?fields=workbook.name,project

Example 4: The following example combines the field expression and sorting. The query returns the names and usage data of the views and sorts the response by the workbook name.

http://localhost/api/2.5/sites/1a10f5b9-029b-43e4-a620-773d1690338c/views?fields=name,usage&sort=name:asc

Thanks for your feedback!

Your feedback has been successfully submitted. Thank you!

Tableau REST API Help