Search API filters
editSearch API filters
editApply conditions to field values to filter results.
Type | Value Filter | Range Filter | Geo Filter |
---|---|---|---|
|
Yes |
No |
No |
|
Yes |
Yes |
No |
|
Yes |
Yes |
No |
|
No |
No |
Yes |
Value Filter
editReturn documents that contain a specific field value.
Available on text, number, and date fields.
Supports arrays.
-
query
(required) - Each request is considered a query against your engine. The query provides scope for the facet.
-
filters
(required) - The filters key opens up the object where you define the fields upon which to filter.
-
field key
(required) - The field from your schema upon which to apply your filter.
-
field value
(required) - The value upon which to filter. The value must be an exact match, even casing: True will not match on true.
Example - Filtering for "world_heritage_site"s on the "parks" query.
curl -X POST 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/search' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \ -d '{ "query": "parks", "filters" : { "world_heritage_site": [ "true" ] } }'
Example - Filtering for "California" and "Alaska" using an array on the "parks" query.
curl -X POST 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/search' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \ -d '{ "query": "parks", "filters" : { "states": [ "California", "Alaska" ] } }'
Range Filter
editReturn documents over a range of dates or numbers.
Available on number or date fields.
-
query
(required) - Each request is considered a query against your engine. The query provides scope for the facet.
-
filters
(required) - The filters key opens up the object where you define the fields upon which to filter.
-
field key
(required) - The field from your schema upon which to apply your filter.
-
from
(optional) - Inclusive lower bound of the range. Is required if to is not given.
-
to
(optional) - Exclusive upper bound of the range. Is required if from is not given.
Example - Filtering results to only national parks that have a their established_date
between 1900
and 1950
.
curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/search' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \ -d '{ "query": "park", "filters": { "date_established": { "from": "1900-01-01T12:00:00+00:00", "to": "1950-01-01T00:00:00+00:00" } } }'
Geo Filter
editReturn documents relative to their location.
-
query
(required) - Each request is considered a query against your engine. The query provides scope for the facet.
-
filters
(required) - The filters key opens up the object where you define the fields upon which to filter.
-
field key
(required) - The field from your schema upon which to apply your filter.
-
center
(required) -
The mode of the distribution, specified as a latitude-longitude pair. See Geolocation fields.
-
unit
(required) - The base unit of measurement: mm, cm, m (meters), km, in, ft, yd, or mi (miles).
-
distance
(optional) - A number representing the distance unit. Is required if from or to is not given.
-
from
(optional) - Inclusive lower bound of the range. Is required if to is not given.
-
to
(optional) - Exclusive upper bound of the range. Is required if from is not given.
Example - Filtering results for "parks" to those within 300 kilometers of Elastic’s San Francisco office.
curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/search' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \ -d '{ "query": "parks", "filters": { "location": { "center": "37.386483, -122.083842", "distance": 300, "unit": "km" } } }'
Example - Filtering results for "parks" between 0 and 1000 metres from Elastic’s San Francisco office.
curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/search' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \ -d '{ "query": "parks", "filters": { "location": { "center": "37.386483, -122.083842", "unit": "m", "from": 0, "to": 1000 } } }'
Combining Filters
editThere are three boolean clauses that are supported to allow for more flexibility when searching.
any |
At least one of the filters must match. This functions as an OR condition. |
all |
All of the filters must match. This functions as an AND condition. |
none |
All of the filters must not match. This functions as a NOT condition. |
Example - Searching for "parks" which are in "California" and are "World Heritage Sites". They must be over 40000 acres or more than 500 square kilometers. The park can not be "Yosemite".
curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/search' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \ -d '{ "query": "parks", "filters": { "all": [ { "states": "California" }, { "world_heritage_site": "true" } ], "any": [ { "acres": { "from": 40000 } }, { "square_km": { "from": 500 } } ], "none": [ { "title": "Yosemite" } ] } }'
Arrays as "OR"
editWhen building filters, you can use all three of: any
, all
, or none
.
The following filter shows two arrays nested under the all
field.
Given that it is an all
field, it creates an "AND" between the two arrays.
Within each array, its items are applied using an "OR" condition.
"filters": { "all": [ { "states": ["Washington", "Idaho"] }, { "world_heritage_site": ["true"] } ] }
The filter is saying: ( "Washington" OR "Idaho" ) AND "world_heritage_site".
When present as a filtering option, or when nested under any condition, an array is an OR:
"filters": { "states": ["Washington", "Idaho"] }
This filter is saying: Washington OR Idaho.
Arrays vs. Objects
editBe mindful of the 32 filters limit when building large filtered queries.
Instead of stacking objects, you can use an array when values share a field.
Each array can contain 1024 values.
If need be, you can use 32 full arrays to filter on a total of 32,768 values.
Array behaviour varies depending on whether you are using any
, all
, or none
...
Arrays: Any
editYou can stack objects within an any
parameter, like so:
"filters" : { "any": [ { "sku": 1 }, { "sku": 2 }, { "sku": 3 }, { "sku": 4 }, { "sku": 5 }, { "sku": 6 } ... ... ] }
Or, you can include them in an array for greater efficiency:
"filters" : { "any": [ "sku": [1, 2, 3, 4, 5, 6 ...] ] }
Arrays: All, None
editIf you use an array within an all
or none
parameter, like so:
"filters" : { "all": [ "sku": [1, 2, 3, 4, 5, 6 ...] ] }
It is equivalent to nesting an any
object under the all
or none
object:
"filters" : { "all": { "any": [ { "sku": 1 }, { "sku": 2 }, { "sku": 3 }, { "sku": 4 }, { "sku": 5 }, { "sku": 6 } ] } }
The intention is to chain OR statements.
Nesting Filters
editClauses can be nested within each other to have even more expressive filtering.
Filter can have up to 5 levels of nesting.
Example - Nesting ANY and ALL filters.
curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/search' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \ -d '{ "query": "parks", "filters": { "any": [ { "all": [ { "states": "California" }, { "world_heritage_site": "true" } ] } ] } }'