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. Facets count the same way,
so a value taken from a facet and sent as a default value filter returns the facet's count: Fiction
and FICTION are one facet entry, shown as first written. 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.
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..." }IN Filter
POST /api/teams/{teamName}/datasets/{dataSetName}/filters/in
Match documents whose field holds one of a set of values - one request and one filter for the whole set, where value filters combined with OR take a request per value and per combine.
curl -X POST https://your-host/api/teams/acme/datasets/products/filters/in \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"fieldName": "brand", "values": ["nike", "puma"], "isCaseSensitive": false}'On an array field one element in the set is enough. On a numeric field the values must be numbers
and compare as numbers. Duplicates and order do not matter: the same set gives the same token,
and like a value filter's the token describes the filter. An empty list, a value that is not a
number on a numeric field, or isCaseSensitive on a numeric field is answered 400 with the
reason.
Position Filter
POST /api/teams/{teamName}/datasets/{dataSetName}/filters/position
Match documents whose position lies within a distance, in metres, of a given position: "a shop
within 1 km". A position is an object with the numbers latitude and longitude in decimal
degrees, e.g. {"location": {"latitude": 59.91, "longitude": 10.75}}. fieldName names the
object, and both location.latitude and location.longitude must be Filterable.
curl -X POST https://your-host/api/teams/acme/datasets/shops/filters/position \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"fieldName": "location", "latitude": 59.9133, "longitude": 10.7389, "withinMeter": 1000}'The distance is measured on a sphere, the short way round across the antimeridian, both ends
inclusive. A document without a position does not match. Like a range filter's, the token
describes the filter and is honoured after the cache has let it go. A latitude outside ±90, a
longitude outside ±180, a negative distance, or a field without a position is answered 400
with the reason.
Filter Expressions
POST /api/teams/{teamName}/datasets/{dataSetName}/filters/expression
The filters above, written as one expression. It makes the same filter, with the same token, as the routes do one by one, so it can stand alone or be combined further.
curl -X POST https://your-host/api/teams/acme/datasets/products/filters/expression \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"expression": "brand IN [\"nike\", \"puma\"] AND price BETWEEN 100 AND 2000 AND NOT category = \"outlet\""}'Response:
{
"hashString": "abc123...",
"canonical": "brand IN [\"nike\", \"puma\"] AND price BETWEEN 100 AND 2000 AND NOT category = \"outlet\""
}=,!=,<,<=,>,>=,IN [ ... ],BETWEEN a AND bandwithin(location, 59.91, 10.75, 1000)for a position filter.AND,OR,NOTand parentheses; NOT binds tightest, OR loosest. Keywords in any case.- Text in double quotes with JSON's escapes inside (
\",\\,\n,\u00e5and the rest), so a value written byJSON.stringifyor any JSON serializer drops in as it is. Numbers with.,true/false. A field name as written - nested fields with.- or in backticks:`Produsent/Importør` = "Tine". - Case is folded;
MATCHCASEafter a value or a list matches it:brand = "Nike" MATCHCASE. - On a numeric field
=andINcompare as numbers; on any other field a value is text. On an array field one element is enough.!=andNOTinclude the documents that have no value.
canonical is the filter written back as the engine reads it - values case-folded as they are
compared, ranges by their limits - for logs and tests. Posted again it gives the same token.
A filter you already hold goes into an expression as a placeholder, $name, with its token in
parameters:
{
"expression": "($region OR $near) AND brand = \"nike\"",
"parameters": {
"region": { "hashString": "def456..." },
"near": { "hashString": "ghi789..." }
}
}An expression that makes no filter is answered 400 with code: invalidFilterExpression, the
first error as detail, every error under errors and a pointer under the first:
{
"status": 400,
"code": "invalidFilterExpression",
"detail": "Unknown field 'typ1'. Did you mean 'type1'?",
"errors": [
{ "kind": "unknownField", "message": "Unknown field 'typ1'. Did you mean 'type1'?",
"start": 0, "length": 4, "suggestion": "type1" }
],
"pointer": "typ1 = \"fire\"\n^^^^"
}kind is one of syntax, unknownField, fieldNotFilterable, typeMismatch, invalidNumber,
emptyRange, limitExceeded, unknownParameter, invalidValue. start and length count
UTF-16 code units, as a JavaScript string does. A syntax error is reported alone, with what to
write instead; errors of meaning are reported all at once. A placeholder's token that does not
resolve is 400 unknownFilter, as anywhere else a token is taken.
You need not create the filter first: a search takes the expression itself (below).
Combining Filters
POST /api/teams/{teamName}/datasets/{dataSetName}/filters/combine
Combine two or more filters with AND or OR into one filter, in one request.
curl -X POST https://your-host/api/teams/acme/datasets/products/filters/combine \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"filters": [
{ "hashString": "abc123..." },
{ "hashString": "def456..." },
{ "hashString": "ghi789..." }
],
"useAndOperation": true
}'Response:
{ "hashString": "combined789..." }Set useAndOperation to false for OR. A filter listed twice counts once, and the order does not
matter: the same set gives the same token. One filter gives its own token; an empty list is 400.
An AND that holds a filter on an array field - which has no field index, so loading it means walking every document - checks that filter only on the documents the other filters leave. Put a selective filter beside it and the AND costs what the selective filter costs.
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..." }
}Or give the expression in the search itself, with filterExpression and, for its placeholders,
filterParameters. Given beside filter, a document must match both:
{
"text": "wireless",
"maxNumberOfRecordsToReturn": 20,
"filter": { "hashString": "combined789..." },
"filterExpression": "price < 500 OR NOT category = \"outlet\""
}The same two properties are on vector and hybrid searches. An expression that makes no filter is
400 invalidFilterExpression, as above, and the search is not run.
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, buries/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).
Schemas
BoostCondition
One condition of a boost rule: a filterable field matched either by an exact IndxServer.Models.BoostCondition.Value (string/keyword fields) or by a numeric IndxServer.Models.BoostCondition.Min/IndxServer.Models.BoostCondition.Max range. Exactly one of the two forms is used: if IndxServer.Models.BoostCondition.Min or IndxServer.Models.BoostCondition.Max is set it's a range, otherwise IndxServer.Models.BoostCondition.Value is an exact match.
| Property | Type | Default |
|---|---|---|
field | string | — |
value | string | — |
min | double | — |
max | double | — |
isRange | boolean | — |
BoostProxy
| Property | Type | Default |
|---|---|---|
boostStrength | string | — |
filterProxy | object | — |
BoostRule
A persisted, per-dataset ranking rule: when a search has `enableBoost` on, documents matching this rule's combined condition get their score lifted by IndxServer.Models.BoostRule.Strength. Rules are managed in the UI and applied server-side; see `BoostRuleStore`.
| Property | Type | Default |
|---|---|---|
name | string | — |
enabled | boolean | — |
conditions | object[] | — |
join | string | — |
strength | string | — |
activeFrom | date | — |
activeUntil | date | — |
CombinedFilterProxy
| Property | Type | Default |
|---|---|---|
filters | object[] | — |
useAndOperation | boolean | — |
FilterExpressionProxy
| Property | Type | Default |
|---|---|---|
expression | string | — |
parameters | object | — |
FilterFieldUpdateProxy
| Property | Type | Default |
|---|---|---|
filter | object | — |
fieldName | string | — |
value | any | — |
FilterProxy
| Property | Type | Default |
|---|---|---|
hashString | string | — |
FilterSuggestion
One filter the description asked for: a value (text, or true/false) or a number range, either end open. Field and value are the dataset's own, checked against what it holds.
| Property | Type | Default |
|---|---|---|
field | string | — |
value | string | — |
min | double | — |
max | double | — |
FiltersRequest
| Property | Type | Default |
|---|---|---|
text | string | — |
InFilterProxy
| Property | Type | Default |
|---|---|---|
fieldName | string | — |
values | any[] | — |
isCaseSensitive | boolean | — |
PositionFilterProxy
| Property | Type | Default |
|---|---|---|
fieldName | string | — |
latitude | float | — |
longitude | float | — |
withinMeter | float | — |
RangeFilterProxy
| Property | Type | Default |
|---|---|---|
fieldName | string | — |
lowerLimit | double | — |
upperLimit | double | — |
ValueFilterProxy
| Property | Type | Default |
|---|---|---|
fieldName | string | — |
value | any | — |
isCaseSensitive | boolean | — |