Filters
Apply conditions to field values to filter results.
Type | Value Filter | Range Filter | Geo Filter |
---|---|---|---|
text |
Yes | No | No |
number |
Yes | Yes | No |
date |
Yes | Yes | No |
geolocation |
No | No | Yes |
Value Filter
Return 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 ontrue
.
curl -X POST 'https://host-2376rb.api.swiftype.com/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" ]
}
}'
curl -X POST 'https://host-2376rb.api.swiftype.com/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" ]
}
}'
curl -X POST 'https://host-2376rb.api.swiftype.com/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" ]
}
}'
curl -X POST 'https://host-2376rb.api.swiftype.com/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" ]
}
}'
curl -X POST 'https://host-2376rb.api.swiftype.com/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" ]
}
}'
curl -X POST 'https://host-2376rb.api.swiftype.com/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" ]
}
}'
curl -X POST 'https://host-2376rb.api.swiftype.com/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" ]
}
}'
curl -X POST 'https://host-2376rb.api.swiftype.com/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" ]
}
}'
curl -X POST 'https://host-2376rb.api.swiftype.com/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" ]
}
}'
curl -X POST 'https://host-2376rb.api.swiftype.com/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" ]
}
}'
curl -X POST 'https://host-2376rb.api.swiftype.com/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" ]
}
}'
curl -X POST 'https://host-2376rb.api.swiftype.com/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
Return 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.
established_date
between 1900
and 1950
.
curl -X GET 'https://host-2376rb.api.swiftype.com/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"
}
}
}'
established_date
between 1900
and 1950
.
curl -X GET 'https://host-2376rb.api.swiftype.com/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"
}
}
}'
established_date
between 1900
and 1950
.
curl -X GET 'https://host-2376rb.api.swiftype.com/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"
}
}
}'
established_date
between 1900
and 1950
.
curl -X GET 'https://host-2376rb.api.swiftype.com/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"
}
}
}'
established_date
between 1900
and 1950
.
curl -X GET 'https://host-2376rb.api.swiftype.com/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"
}
}
}'
established_date
between 1900
and 1950
.
curl -X GET 'https://host-2376rb.api.swiftype.com/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
Return 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 as a string in "[latitude], [longitude]" format.
- unit
- required
- The base unit of measurement:
mm
,cm
,m
(meters),km
,in
,ft
,yd
, ormi
(miles). - distance
- optional
- A number representing the distance unit. Is required if
from
orto
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.
curl -X GET 'https://host-2376rb.api.swiftype.com/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"
}
}
}'
curl -X GET 'https://host-2376rb.api.swiftype.com/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"
}
}
}'
curl -X GET 'https://host-2376rb.api.swiftype.com/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"
}
}
}'
curl -X GET 'https://host-2376rb.api.swiftype.com/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"
}
}
}'
curl -X GET 'https://host-2376rb.api.swiftype.com/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"
}
}
}'
curl -X GET 'https://host-2376rb.api.swiftype.com/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"
}
}
}'
curl -X GET 'https://host-2376rb.api.swiftype.com/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
}
}
}'
curl -X GET 'https://host-2376rb.api.swiftype.com/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
}
}
}'
curl -X GET 'https://host-2376rb.api.swiftype.com/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
}
}
}'
curl -X GET 'https://host-2376rb.api.swiftype.com/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
}
}
}'
curl -X GET 'https://host-2376rb.api.swiftype.com/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
}
}
}'
curl -X GET 'https://host-2376rb.api.swiftype.com/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
There 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. |
curl -X GET 'https://host-2376rb.api.swiftype.com/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" }
]
}
}'
curl -X GET 'https://host-2376rb.api.swiftype.com/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" }
]
}
}'
curl -X GET 'https://host-2376rb.api.swiftype.com/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" }
]
}
}'
curl -X GET 'https://host-2376rb.api.swiftype.com/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" }
]
}
}'
curl -X GET 'https://host-2376rb.api.swiftype.com/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" }
]
}
}'
curl -X GET 'https://host-2376rb.api.swiftype.com/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"
When 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
Be 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
You 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
If 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
Clauses can be nested within each other to have even more expressive filtering.
Filter can have up to 5 levels of nesting.
curl -X GET 'https://host-2376rb.api.swiftype.com/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" }
]
}
]
}
}'
curl -X GET 'https://host-2376rb.api.swiftype.com/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" }
]
}
]
}
}'
curl -X GET 'https://host-2376rb.api.swiftype.com/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" }
]
}
]
}
}'
curl -X GET 'https://host-2376rb.api.swiftype.com/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" }
]
}
]
}
}'
curl -X GET 'https://host-2376rb.api.swiftype.com/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" }
]
}
]
}
}'
curl -X GET 'https://host-2376rb.api.swiftype.com/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" }
]
}
]
}
}'
Stuck? Looking for help? Contact support or check out the App Search community forum!