This documentation contains work-in-progress information for future Elastic Stack and Cloud releases. Use the version selector to view supported release docs. It also contains some Elastic Cloud serverless information. Check out our serverless docs for more details.

› ›

Search API filters

edit

Search API filters

edit

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

edit

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 on true.

Example - Filtering for "world_heritage_site"s on the "parks" query.

curl -X POST '<ENTERPRISE_SEARCH_BASE_URL>/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 '<ENTERPRISE_SEARCH_BASE_URL>/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

edit

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.

Example - Filtering results to only national parks that have a their established_date between 1900 and 1950.

curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/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

edit

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, 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 '<ENTERPRISE_SEARCH_BASE_URL>/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 '<ENTERPRISE_SEARCH_BASE_URL>/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

edit

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.

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 '<ENTERPRISE_SEARCH_BASE_URL>/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"

edit

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

edit

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

edit

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

edit

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

edit

Clauses 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 '<ENTERPRISE_SEARCH_BASE_URL>/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" }
        ]
      }
    ]
  }
}'

« Search API facets Search API group »