Filters

Filters are created server-side and referenced by an opaque hashString. Pass that string back in search or bulk-operation requests; do not construct or parse it yourself.

Value Filter

POST /api/teams/{teamName}/datasets/{dataSetName}/filters/value

Match documents where a field equals a specific value.

curl -X POST https://your-host/api/teams/acme/datasets/products/filters/value \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"fieldName": "category", "value": "electronics"}'

Response:

{ "hashString": "abc123..." }

value is a string, number or boolean, compared as text against the stored value. The field must hold text or booleans: on a field that holds numbers a text comparison is wrong (129 is not 129.0) and the request is answered 400 naming the filter to use instead, a range filter with equal limits.

The match is case-insensitive unless you add "isCaseSensitive": true. Do that when the value comes from a facet: facets count distinct stored values with their casing, so a facet showing Fiction: 23 419 and FICTION: 51 is matched by the default filter with 23 470 documents, and only a case-sensitive filter on Fiction answers the 23 419 the facet showed. A case-sensitive filter is built by scanning the documents rather than from the field's index, so it costs more on a large dataset; the answers are the same.

Range Filter

POST /api/teams/{teamName}/datasets/{dataSetName}/filters/range

Match documents where a field falls within a numeric range, both ends inclusive. Equal limits match one value, which is how to ask for equality on a numeric field. The field must hold numbers: a number stored as a JSON string is text, and the request is answered 400 with the fix - store the values as numbers and load again.

curl -X POST https://your-host/api/teams/acme/datasets/products/filters/range \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"fieldName": "price", "lowerLimit": 10, "upperLimit": 100}'

Response:

{ "hashString": "def456..." }

Combining Filters

POST /api/teams/{teamName}/datasets/{dataSetName}/filters/combine

Combine two filters with AND or OR.

curl -X POST https://your-host/api/teams/acme/datasets/products/filters/combine \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "a": { "hashString": "abc123..." },
    "b": { "hashString": "def456..." },
    "useAndOperation": true
  }'

Response:

{ "hashString": "combined789..." }

Set useAndOperation to false for OR.

Negating a Filter

POST /api/teams/{teamName}/datasets/{dataSetName}/filters/not

Match every document the given filter does not. The body is the filter's token; the result is a token like any other and can be combined further.

curl -X POST https://your-host/api/teams/acme/datasets/products/filters/not \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "hashString": "abc123..." }'

Response:

{ "hashString": "not789..." }

The hashString is opaque

Treat it as a token: obtain it from a filter endpoint, pass it back in a search or bulk operation, and do not parse, construct or modify it. Its internal form is not part of the API contract and may change without notice.

Tokens are durable — one keeps working after the server has evicted the filter from its cache, and across a restart — so a client may hold one for as long as the dataset's fields are unchanged. A token the server cannot honour is answered 400 with code: unknownFilter; re-create the filter and use the new token.

Using a Filter in Search

{
  "text": "wireless",
  "maxNumberOfRecordsToReturn": 20,
  "filter": { "hashString": "combined789..." }
}

A hashString the server cannot resolve — mistyped, truncated, or naming a field that has since been removed or un-marked as Filterable — is answered 400 with code: unknownFilter. The search is not run without the filter. Re-create the filter and retry with the token you get back; never retry the search with the filter omitted.

The same applies to every endpoint that takes a token: filters/combine, filters/not, boosts/from-filter, filters/delete, documents/delete-by-filter and documents/update-by-filter.

Pre-loading Filters

POST /api/teams/{teamName}/datasets/{dataSetName}/filters/load — loads all filterable fields into memory for faster repeated filtering (204). Call once after indexing.

GET /api/teams/{teamName}/datasets/{dataSetName}/filters/count — returns the count of currently cached filters as {"count": n}.

Releasing Filters

POST /api/teams/{teamName}/datasets/{dataSetName}/filters/delete — release a specific filter (body: { "hashString": "..." }; 204).

DELETE /api/teams/{teamName}/datasets/{dataSetName}/filters — release all cached filters (204).