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
filterskey 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:
Truewill 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
filterskey 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
tois not given. - to
- optional
- Exclusive upper bound of the range. Is required if
fromis 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
filterskey 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
fromortois not given. - from
- optional
- Inclusive lower bound of the range. Is required if
tois not given. - to
- optional
- Exclusive upper bound of the range. Is required if
fromis 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!