Range Filters
Several of the Search APIs - Documents, Facets, States and Typeahead - support applying range filters onto the queries. Range filters allow results to be restricted to only those that fall within a given date or numeric range. This allows for more fine-grained filtering of search results.
Parameters
The range-start, range-end and range-fields parameters are used to enable range filtering in all supported APIs, whether using the Querystring GET or Form POST variants of those APIs.
Range filters are disabled by default, and only enabled when either range-start or range-end is provided.
range-fields is always optional, and when not provided the underlying search index will choose suitable fields for range filtering. By default this will be all date/numeric fields present in the index. See Filtering on Specific Fields for more discussion of this parameter.
Example Date Range Filters
The following table summarises the parameters you need to set to apply different kinds of date range filter:
range-start | range-end | Example | Effective Range |
|---|---|---|---|
X | range-start=2024-01-01 | Results on or after X (e.g. 1st Jan 2024) | |
X | range-end=2023-12-31 | Results on or before Y (e.g. 31st Dec 2023) | |
X | Y | range-start=2024-01-01&range-end=2024-12-31 | Results between X and Y (e.g. 1st Jan 2024 and 31st Dec 2024 |
The range start and end values are always inclusive so you MAY need to adjust your provided range-start and range-end values appropriately.
Partial Dates and Times
Note that in the above examples we provided only dates, and not times. Range filters may be made more specific by providing a time if desired, e.g. range-start=2024-01-01T10:00:00&range-end=2024-01-01T10:30:00, would find results only between 10:00 and 10:30 on 1st January 2024. When only a date is provided then the underlying search index substitutes appropriate time components to your range start and end marking the start and end of the specified days.
However, be aware that if you provide an incomplete date, e.g. range-start=2024&range-end=2024, the behaviour might not be as expected because the underlying search index does not substitute missing date components in the same manner as it substitutes missing time values. This range would find only documents associated with the 1st January 2024 and NOT everything in 2024 as you might expect.
Therefore, callers SHOULD always provide at least a complete date when using range filtering for date fields. For example to find all documents associated with 2024 then you would use range-start=2024-01-01&range-end=2024-12-31 to specify the first and last day of the year.
Filtering on Specific Fields
The range-fields parameter is used to configure which fields the range filter applies over. For example if we were only interested in results which started within a date range you could do range-start=2024-01-01&range-end=2024-01-31&range-fields=start to find anything with a start field value during January 2024.
This parameter can be specified multiple times to filter over multiple fields, e.g. range-start=2024-01-01&range-fields=start&range-fields=created, would find anything with a start or created value on or after 1st January 2024.
Take care when supplying your own range-fields as if the provided field exists, but has the wrong datatype for range filtering, the filter is ignored and has no effect.
Filtering on Numeric Fields
Finally, while all our examples so far have focused on using range filtering for date values, range filters are supported for any numeric field as well. For example, if you had documents with an age field containing integers you could do something like range-start=30&range-end=39&range-fields=age to filter for results where the age is between 30 and 39.