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.

bash
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:

json
{ "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.

bash
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:

json
{ "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.

bash
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.

bash
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.

bash
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:

json
{
  "hashString": "abc123...",
  "canonical": "brand IN [\"nike\", \"puma\"] AND price BETWEEN 100 AND 2000 AND NOT category = \"outlet\""
}
  • =, !=, <, <=, >, >=, IN [ ... ], BETWEEN a AND b and within(location, 59.91, 10.75, 1000) for a position filter.
  • AND, OR, NOT and parentheses; NOT binds tightest, OR loosest. Keywords in any case.
  • Text in double quotes with JSON's escapes inside (\", \\, \n, \u00e5 and the rest), so a value written by JSON.stringify or 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; MATCHCASE after a value or a list matches it: brand = "Nike" MATCHCASE.
  • On a numeric field = and IN compare as numbers; on any other field a value is text. On an array field one element is enough. != and NOT include 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:

json
{
  "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:

json
{
  "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.

bash
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:

json
{ "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.

bash
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:

json
{ "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.

json
{
  "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:

json
{
  "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.

PropertyTypeDefault
field
string
—
value
string
—
min
double
—
max
double
—
isRange
boolean
—

BoostProxy

PropertyTypeDefault
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`.

PropertyTypeDefault
name
string
—
enabled
boolean
—
conditions
object[]
—
join
string
—
strength
string
—
activeFrom
date
—
activeUntil
date
—

CombinedFilterProxy

PropertyTypeDefault
filters
object[]
—
useAndOperation
boolean
—

FilterExpressionProxy

PropertyTypeDefault
expression
string
—
parameters
object
—

FilterFieldUpdateProxy

PropertyTypeDefault
filter
object
—
fieldName
string
—
value
any
—

FilterProxy

PropertyTypeDefault
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.

PropertyTypeDefault
field
string
—
value
string
—
min
double
—
max
double
—

FiltersRequest

PropertyTypeDefault
text
string
—

InFilterProxy

PropertyTypeDefault
fieldName
string
—
values
any[]
—
isCaseSensitive
boolean
—

PositionFilterProxy

PropertyTypeDefault
fieldName
string
—
latitude
float
—
longitude
float
—
withinMeter
float
—

RangeFilterProxy

PropertyTypeDefault
fieldName
string
—
lowerLimit
double
—
upperLimit
double
—

ValueFilterProxy

PropertyTypeDefault
fieldName
string
—
value
any
—
isCaseSensitive
boolean
—