Document filter special characters and the wildcard workaround

docs/api-ref.md

@@ -3006,7 +3006,7 @@ Name | Description
 :--- | :---
 `Field` | Defined in the `RequestOptions.Field` class.
 `Operator` | Defined in the `RequestOptions.Operator` class
-`Value` | The value to compare with the specified field and operator.
+`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).
 
 
 
@@ -6163,6 +6163,8 @@ Operator  |  Description
 `LessThan` | Sets the operator to less than (same as `lt` in the REST API). `TSC.RequestOptions.Operator.LessThan`
 `LessThanOrEqual` | Sets the operator to less than or equal (same as `lte` in the REST API). `TSC.RequestOptions.Operator.LessThanOrEqual`
 `In` | Sets the operator to in (same as `in` in the REST API). `TSC.RequestOptions.Operator.In`
+`Has` | Sets the operator to has (same as `has` in the REST API). `TSC.RequestOptions.Operator.Has`
+`CaseInsensitiveEquals` | Sets the operator to case-insensitive equals (same as `cieq` in the REST API). `TSC.RequestOptions.Operator.CaseInsensitiveEquals`
 
 <br>
 <br>

docs/filter-sort.md

@@ -35,7 +35,7 @@ API help](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_conc
 
 To filter on a field, you need to specify the field name, an operator criteria and a value criteria.
 
-**Note**: Ampersands and commas in filters are not supported by the REST API as they are used as delimiters.
+**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.
 
 ### Operator criteria
 
@@ -50,11 +50,55 @@ The operator can be any of the following:
 * LessThanOrEqual
 * In
 * Has
+* CaseInsensitiveEquals
+
+Not every operator is supported on every field. See the per-endpoint field tables in the [REST
+API help](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm).
 
 ### Value criteria
 
 The value that you want to filter on. This can be any valid string.
 
+### Special characters in filter values
+
+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.
+
+```py
+# 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`:
+
+```py
+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:
+
+```py
+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](#wildcard-searches)).
+
+### 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.
+
 ### Filtering example - RequestOptions
 
 The following code displays only the workbooks where the name equals Superstore:
@@ -219,3 +263,8 @@ print(len(flows))
 | 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](#special-characters-in-filter-values) and
+[Wildcard searches](#wildcard-searches) for limits on filter values.