Filtering and Sorting in the Tableau REST API

You can filter and sort the data that gets returned from requests to the following REST API endpoints:

You can also filter query views using fields in underlying workbook data when using the Query View Data, Query View Image and Query View PDF methods. To learn more, see Filter query views.

Filtering

By default, methods like Get Users on Site return information about all the users or workbooks on a Tableau Server site. If there are many entities, the method returns them in chunks (pages). If you want information about a specific user or workbook, one option is to loop through the information returned by the call and look for the user or workbook that you're interested in.

As an alternative, starting in the REST API version 2.3 (Tableau Server 10.0), you can include a filter expression in the query string of the URI, using the following syntax:

filter=field:operator:value

The following example shows how to include a filter in a call to get users on a site:

http://MY-SERVER/api/3.11/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users?filter=siteRole:eq:Viewer

In the preceding example, the method will return only the users whose site role is Viewer.

Note: Filter expressions cannot contain ampersand (&) or comma (,) characters as these are used as field expression separators. This is true even if those characters are encoded.

Filter expressions

The following table lists the field names and operators you can use in a filter expression. Notice that the user-related calls support slightly different fields than the workbook-related calls.

  Field Operator
Users lastLogin eq
gt
gte
lt
lte
  name eq
in
siteRole eq
in
Datasources name eq
in
  favoritesTotal eq
gt
gte
lt
lte
  type eq
  createdAt eq
gt
gte
lt
lte
  ownerName eq
  updatedAt eq
gt
gte
lt
lte
tags eq
in
Groups name eq
in
  domainName eq
in
domainNickname eq
in
isLocal eq
userCount eq
gt
gte
lt
lte
minimumSiteRole eq
in
Jobs completedAt eq
gt
gte
lt
lte
  createdAt eq
gt
gte
lt
lte
  jobType eq
in
  notes has
  startedAt eq
gt
gte
lt
lte
  status eq
  subtitle eq
has
  title eq
has
Projects name eq
in
  createdAt eq
gt
gte
lt
lte
  ownerDomain eq
in
  ownerEmail eq
in
  ownerName eq
in
  parentProjectId eq
  updatedAt eq
gt
gte
lt
lte
Views name eq

in

  favoritesTotal eq
gt
gte
lt
lte
  createdAt eq
gt
gte
lt
lte
  hitsTotal eq
gt
gte
lt
lte
  ownerName eq
tags eq
in
  updatedAt eq
gt
gte
lt
lte
Workbooks createdAt eq
gt
gte
lt
lte
  favoritesTotal eq
gt
gte
lt
lte
  name eq

in

ownerName eq

in

tags eq
in
updatedAt eq
gt
gte
lt
lte
Flows name

eq
in

  ownerName eq
  projectName eq
in
  createdAt eq
gt
gte
lt
lte
  updated At eq
gt
gte
lt
lte
Metrics name

eq
in

  createdAt eq
gt
gte
lt
lte
  updatedAt eq
gt
gte
lt
lte
  ownerName eq
in
  ownerDomain eq
in
  ownerEmail eq
in
  projectName eq
in
  hitsTotal eq
gt
gte
lt
lte
  favoritesTotal eq
gt
gte
lt
lte
  tags eq
in

Filter expression notes

  • Operators are delimited with colons (:).

  • If any reserved characters following the question mark (?) in the URI are encoded, than all reserved characters must be encoded. For example, the colon character (:) would be encoded as %3A and the equals character (=) would be encoded as %3D.
  • The operators are:

    • eq—equals
    • gt—greater than
    • gte—greater than or equal
    • has—contains the specified string
    • lt—less than
    • lte—less than or equal
    • in—any of [list] (for searching tags)
  • Field names, operator names, and values are case sensitive.

  • Values should be URL-encoded. For example, to search for the workbook named Project Views, include a filter like filter=name:eq:Project+Views.

  • Substring search (the has operator) is only supported for the Query Jobs method.

  • To filter on multiple fields, combine expressions using a comma, as in this example:

    filter=lastLogin:gte:2016-01-01T00:00:00:00Z,siteRole:eq:Publisher

    Multiple expressions are combined using a logical AND. (However, see next point.)

  • If you include the same field multiple times in a filter expression, only the last reference to the field is used. For example, in the following filter for a Get Users on Site call, the siteRole field appears twice. Tableau Server will return only the users whose site role is Viewer, because that's the value in the last reference.

    filter=siteRole:eq:Publisher,siteRole:eq:Viewer

  • For date-time values, use ISO 8601(Link opens in a new window) format (for example, 2016-05-04T21:24:49Z).

Searching workbooks using tags

To search for a workbook that has one specific tag, use the tag field and the eq operator, as in the following example:

http://MY-SERVER/api/2.3/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks?filter=tags:eq:stocks

This filter finds workbooks in which at least one of the tags is stocks. (The workbooks returned by this filter might have other tags as well.)

You can also search for workbooks if they have any one of a list of tags—that is, you can create an OR search. To do this, use the in operator and provide a list of tags to search for, as in the following example:

http://MY-SERVER/api/2.3/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks?filter=tags:in:[stocks,market]

This filter finds workbooks that either have a tag stocks or a tag market (no matter what other tags the workbooks might have).

Sorting

To sort the results, include the sort parameter. The syntax is this:

sort=field:direction

You can sort on the same fields that you use to filter. The direction value is asc (ascending) or desc (descending), and is required.

You can specify multiple levels of sorting by including multiple sort expressions, as in this example:

sort=siteRole:asc,name:desc

This causes the results to be sorted first by site role in ascending order, and within site role, by name in descending order.

Combining parameters

You can combine filter, sort, and paging operators in the same call, separating them with &. The following example shows how you can combine a filter parameter, a sort parameter, and a paging parameter.

http://MY-SERVER/api/3.11/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users?filter=lastLogin:gte:2016-02-01T00:00:00Z&sort=siteRole:desc,name:desc&pageNumber=2

Filter query views

You can filter a view using fields in underlying workbook data when using the the Query View Data, Query View Image and Query View PDF methods. To filter a query view using a field, add one or more query parameters structured as follows to your method call:

?vf_<field-name>=<field-value>

The field name and field value must be exactly as shown in the workbook's underlying data. For example, you could get a query view from a workbook with a year field that only displays data from the year 2017 using the following filter:

?vf_year=2017

If the workbook in this example also included a region field for which west was a valid value, you could use the following combination of query parameters to filter the workbook query view to only show data from the year 2017 in the west region:

?vf_year=2017&vf_region=west


Thanks for your feedback!