Skip to content

Commit 0352626

Browse files
jacalataclaude
andauthored
Document filter special characters and the wildcard workaround (#1906)
* Document filter special characters, wildcard searches and cieq The filter docs only said ampersands and commas are unsupported, with no workaround, and did not say which fields support wildcard searches or the cieq and has operators. Document the asterisk workaround for values containing & or , (with a client-side exact-match check), the REST API's like operator and the fields it applies to, and add the missing CaseInsensitiveEquals and Has operators to the operator lists. Closes #1200 Co-Authored-By: Claude Code <noreply@anthropic.com> * Update the filter and sort endpoint and field list The list named four endpoints and seven fields, far fewer than the library supports. Describe the endpoints by what they accept and point at RequestOptions.Field for the full set of fields. Co-Authored-By: Claude Code <noreply@anthropic.com> * Record observed wildcard behaviour of Equals filters on Tableau Cloud Checked against a Tableau Cloud site (REST API 3.30): an Equals filter treats * as a wildcard at the start, end and middle of a workbook name, which makes the documented workaround for values containing & or , work, while like, cieq and has are rejected with a 400 on workbook names. Document this and remove the untested-workaround caveat. Related to #1200 Co-Authored-By: Claude Code <noreply@anthropic.com> * Correct the filter docs: ampersands work, only commas need a workaround Tested against Tableau Cloud: TSC percent-encodes the query string, so an ampersand in a filter value is accepted. A comma is rejected even when encoded or preceded by a backslash. The earlier text said both characters failed. Co-Authored-By: Claude Code <noreply@anthropic.com> * Explain that view filters use different value rules Readers of the special-character and wildcard sections could apply them to vf() export filters, where a comma separates alternatives, a backslash escapes it, and asterisks are literal. Co-Authored-By: Claude Code <noreply@anthropic.com> * Correct the case-sensitivity note for filter values Equals on workbook, data source, project and user names, and on workbook content URLs, ignores case. Equals on a group name is case-sensitive on Tableau Server. Refs #1200 Co-Authored-By: Claude Code <noreply@anthropic.com> * Use generic names in the filter examples Co-Authored-By: Claude Code <noreply@anthropic.com> * Add an In operator example and note that vf encodes ampersands Co-Authored-By: Claude Code <noreply@anthropic.com> * Correct the In list comma note: the value splits silently Co-Authored-By: Claude Code <noreply@anthropic.com> * Qualify & encoding by REST API version and fix Value row Values can contain &, but only from REST API 3.7 when TSC encodes the query string. The Value row said & is not allowed. Co-Authored-By: Claude Code <noreply@anthropic.com> * Scope the Equals wildcard note to what was tested Prefix, suffix and middle * matched on workbook names (Tableau Cloud) and project names (REST API 3.31), ignoring letter case. Co-Authored-By: Claude Code <noreply@anthropic.com> * Say the wildcard behavior is not documented per version Co-Authored-By: Claude Code <noreply@anthropic.com> * Limit filter docs to confirmed behavior Remove the operator and field scope claims, the case-sensitivity paragraph, the like operator table, the view filter section, the In list section and the version-specific encoding and wildcard claims. Keep the comma failure, the asterisk workaround, and the Has and CaseInsensitiveEquals operator rows. Co-Authored-By: Claude Code <noreply@anthropic.com> --------- Co-authored-by: Claude Code <noreply@anthropic.com>
1 parent 76a0ab9 commit 0352626

2 files changed

Lines changed: 53 additions & 2 deletions

File tree

‎docs/api-ref.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3006,7 +3006,7 @@ Name | Description
30063006
:--- | :---
30073007
`Field` | Defined in the `RequestOptions.Field` class.
30083008
`Operator` | Defined in the `RequestOptions.Operator` class
3009-
`Value` | The value to compare with the specified field and operator.
3009+
`Value` | The value to compare with the specified field and operator. Values cannot contain `,`; see [Special characters in filter values](filter-sort#special-characters-in-filter-values).
30103010

30113011

30123012

@@ -6163,6 +6163,8 @@ Operator | Description
61636163
`LessThan` | Sets the operator to less than (same as `lt` in the REST API). `TSC.RequestOptions.Operator.LessThan`
61646164
`LessThanOrEqual` | Sets the operator to less than or equal (same as `lte` in the REST API). `TSC.RequestOptions.Operator.LessThanOrEqual`
61656165
`In` | Sets the operator to in (same as `in` in the REST API). `TSC.RequestOptions.Operator.In`
6166+
`Has` | Sets the operator to has (same as `has` in the REST API). `TSC.RequestOptions.Operator.Has`
6167+
`CaseInsensitiveEquals` | Sets the operator to case-insensitive equals (same as `cieq` in the REST API). `TSC.RequestOptions.Operator.CaseInsensitiveEquals`
61666168

61676169
<br>
61686170
<br>

‎docs/filter-sort.md‎

Lines changed: 50 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ API help](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_conc
3535

3636
To filter on a field, you need to specify the field name, an operator criteria and a value criteria.
3737

38-
**Note**: Ampersands and commas in filters are not supported by the REST API as they are used as delimiters.
38+
**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](#special-characters-in-filter-values) for a workaround.
3939

4040
### Operator criteria
4141

@@ -50,11 +50,55 @@ The operator can be any of the following:
5050
* LessThanOrEqual
5151
* In
5252
* Has
53+
* CaseInsensitiveEquals
54+
55+
Not every operator is supported on every field. See the per-endpoint field tables in the [REST
56+
API help](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm).
5357

5458
### Value criteria
5559

5660
The value that you want to filter on. This can be any valid string.
5761

62+
### Special characters in filter values
63+
64+
The REST API does not accept a comma (`,`) in a filter value, because it uses commas to
65+
separate expressions. A filter value that contains a comma fails with a `400065` error.
66+
Percent-encoding the comma or putting a backslash in front of it does not help.
67+
68+
```py
69+
# Fails: the workbook name contains a comma
70+
workbooks = server.workbooks.filter(name="Sales, Q1 & Q2")
71+
```
72+
73+
An ampersand (`&`) in a name is matched as typed.
74+
75+
To find an item whose name contains a comma, replace the comma with an asterisk (`*`). The
76+
asterisk acts as a wildcard, so the following filter finds the workbook named
77+
`Sales, Q1 & Q2`:
78+
79+
```py
80+
for workbook in server.workbooks.filter(name="Sales* Q1 & Q2"):
81+
print(workbook.name, workbook.id)
82+
```
83+
84+
Because `*` matches any run of characters, the filter can return more than one item. Check
85+
the results on the client side if you need an exact match:
86+
87+
```py
88+
wb_name = "Sales, Q1 & Q2"
89+
pattern = wb_name.replace(",", "*")
90+
matches = [wb for wb in server.workbooks.filter(name=pattern) if wb.name == wb_name]
91+
```
92+
93+
This works because `Equals` treats `*` as a wildcard (see [Wildcard searches](#wildcard-searches)).
94+
95+
### Wildcard searches
96+
97+
In a filter value, `*` matches any run of characters, including none. For example,
98+
`server.workbooks.filter(name="Sales*")` returns workbooks whose names start with `Sales`. This
99+
was tested for workbook names on Tableau Cloud. Confirm the behavior on your Tableau Server
100+
version before you rely on it for other fields.
101+
58102
### Filtering example - RequestOptions
59103

60104
The following code displays only the workbooks where the name equals Superstore:
@@ -219,3 +263,8 @@ print(len(flows))
219263
| LessThanOrEqual | lte |
220264
| In | in |
221265
| Has | has |
266+
| CaseInsensitiveEquals | cieq |
267+
268+
For example, `server.users.filter(name__cieq="jsmith")` matches a user named `JSmith`.
269+
See [Special characters in filter values](#special-characters-in-filter-values) and
270+
[Wildcard searches](#wildcard-searches) for limits on filter values.

0 commit comments

Comments
 (0)