Use the RequestOptions object to define filtering and sorting criteria for an endpoint,
then pass the object to your endpoint as a parameter.
You can use the TSC library to filter and sort the following endpoints:
For the above endpoints, you can filter or sort on the following fields:
Important: Not all of the fields are available for all endpoints. For more information, see the REST API help.
To filter on a field, you need to specify the field name, an operator criteria and a value criteria.
Note: Commas in filter values are not supported by the REST API, because it uses them to separate filter expressions. See Special characters in filter values for a workaround.
The operator that you want to use for that field. For example, you can use the Equals operator to get everything from the endpoint that matches exactly.
The operator can be any of the following:
Not every operator is supported on every field. See the per-endpoint field tables in the REST API help.
The value that you want to filter on. This can be any valid string.
The REST API does not accept a comma (,) in a filter value, because it uses commas to
separate expressions. A filter value that contains a comma fails with a 400065 error.
Percent-encoding the comma or putting a backslash in front of it does not help.
# Fails: the workbook name contains a comma
workbooks = server.workbooks.filter(name="Sales, Q1 & Q2")
An ampersand (&) in a name is matched as typed.
To find an item whose name contains a comma, replace the comma with an asterisk (*). The
asterisk acts as a wildcard, so the following filter finds the workbook named
Sales, Q1 & Q2:
for workbook in server.workbooks.filter(name="Sales* Q1 & Q2"):
print(workbook.name, workbook.id)
Because * matches any run of characters, the filter can return more than one item. Check
the results on the client side if you need an exact match:
wb_name = "Sales, Q1 & Q2"
pattern = wb_name.replace(",", "*")
matches = [wb for wb in server.workbooks.filter(name=pattern) if wb.name == wb_name]
This works because Equals treats * as a wildcard (see Wildcard searches).
In a filter value, * matches any run of characters, including none. For example,
server.workbooks.filter(name="Sales*") returns workbooks whose names start with Sales. This
was tested for workbook names on Tableau Cloud. Confirm the behavior on your Tableau Server
version before you rely on it for other fields.
The following code displays only the workbooks where the name equals Superstore:
req_option = TSC.RequestOptions()
req_option.filter.add(TSC.Filter(TSC.RequestOptions.Field.Name,
TSC.RequestOptions.Operator.Equals,
'Superstore'))
matching_workbooks, pagination_item = server.workbooks.get(req_option)
print(matching_workbooks[0].owner_id)
To sort on a field, you need to specify the field name and the direction criteria for the sort order.
This can be either Asc for ascending or Desc for descending.
The following code sorts the workbooks in ascending order:
req_option = TSC.RequestOptions()
req_option.sort.add(TSC.Sort(TSC.RequestOptions.Field.Name,
TSC.RequestOptions.Direction.Asc))
matching_workbooks, pagination_item = server.workbooks.get(req_option)
for wb in matching_workbooks:
print(wb.name)
The following code displays only workbooks where the name equals Superstore:
all_workbooks = server.workbooks.filter(name='Superstore')
for workbook in all_workbooks:
print(workbook.owner_id)
Starting with version 0.32, you can set the page size for the request by using
the page_size keyword argument. The default page size is 100 if not provided.
superstore_workbooks = server.workbooks.filter(name='Superstore', page_size=10)
# or
all_workbooks = server.workbooks.all(page_size=1000)
The field name can be input as normal for ascending or prefixed with - for descending.
The following code sorts the workbooks in ascending order:
matching_workbooks = server.workbooks.order_by('name')
for wb in matching_workbooks:
print(wb.name)
Sort can take multiple args, with desc direction added as a (-) prefix
workbooks = workbooks.order_by("project_name", "-created_at")
Querysets can be indexed and sliced like a list. The query is executed at when the queryset is indexed or sliced.
# Get the first item in the queryset
flow = server.flows.filter(owner_name="admin")[0]
# Get the last item in the queryset
flow = server.flows.filter(owner_name="admin")[-1]
# Get the most recent 10 runs from a flow
runs = server.flow_runs.filter(flow_id=flow.id, page_size=10).order_by("-created_at")[:10]
The following endpoints support the Django style filters and sorts:
# Return queryset with no filters
workbooks = server.workbooks.all()
# filters can be appended in new lines
workbooks = workbooks.filter(project_name=project_name)
# multiple filters can be added in a single line
workbooks = workbooks.filter(project_name=project_name, owner_name=owner_name, size__gte=1000)
# Multiple filters can be added through chaining.
workbooks = workbooks.filter(project_name=project_name).filter(owner_name=owner_name).filter(size__gte=1000)
# Find all views in a project, with a specific tag
views = server.views.filter(project_name=project_name, tags="stale")
# sort can take multiple args, with desc direction added as a (-) prefix
workbooks = workbooks.order_by("project_name", "-created_at")
# query is executed at time of iteration
for workbook in workbooks:
print(workbook)
# pagination item is still accessible
print(workbooks.total_available, workbooks.page_size, workbooks.page_number)
# methods can be chained
all_workbooks = server.workbooks.filter(project_name=project_name).order_by("-project_name")
# operators are implemented using dunderscore
all_workbooks = server.workbooks.filter(project_name__in=["Project A", "Project B"])
# How many items are in the queryset?
flows = server.flows.filter(owner_name="admin")
print(len(flows))
| Operator | Implementation |
|---|---|
| Equals | eq |
| GreaterThan | gt |
| GreaterThanOrEqual | gte |
| LessThan | lt |
| LessThanOrEqual | lte |
| In | in |
| Has | has |
| CaseInsensitiveEquals | cieq |
For example, server.users.filter(name__cieq="jsmith") matches a user named JSmith.
See Special characters in filter values and
Wildcard searches for limits on filter values.