Search API facets
editSearch API facets
editWe have a conceptual Facets guide, too.
Create value and range facets.
Type | Value Facet | Range Facet |
---|---|---|
|
Yes |
No |
|
Yes |
Yes |
|
Yes |
Yes |
|
No |
Yes |
Value Facet
editProvides the counts of each value for a field.
When faceting on an array field, each unique value will be included in the response.
Each value is only counted once.
Available on text, number, date fields.
-
query
(required) - Each request is considered a query against your engine. The query provides scope for the facet.
-
facets
(required) - The facets key opens up the object where you define your facet field.
-
field key
(required) - The field from your schema upon which to apply your facet.
-
type
(required) - Type of facet, in this case it will be value.
-
name
(optional) - Name given to facet.
-
size
(optional) -
How many facets would you like to return? Can be between 1 and 250 (or the value of the
app_search.engine.total_facet_values_returned.limit
configuration setting). 10 facets is the default. -
sort
(optional) - JSON object where the key is either count or value and the value is asc or desc. The default is sorting by descending count.
Example - Getting the top five states which have matches on the query "parks" in a facet named "top-five-states".
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", "facets": { "states": [ { "type": "value", "name": "top-five-states", "sort": { "count": "desc" }, "size": 5 } ] } }'
Example Response
{ "meta": { "alerts": [], "warnings": [], "page": { "current": 1, "total_pages": 5, "total_results": 46, "size": 10 }, "request_id": "c98ba1eaa5c8bbc098e0be36644b04f7" }, "results": [ ## Truncated! ], "facets": { "states": [ { "type": "value", "name": "top-five-states", "data": [ { "value": "California", "count": 8 }, { "value": "Alaska", "count": 5 }, { "value": "Utah", "count": 4 }, { "value": "Colorado", "count": 3 }, { "value": "Washington", "count": 3 } ] } ] } }
Range Facet
editReturns counts of documents within the provided ranges.
Each number is only counted once.
Dates match RFC3339 format.
Available on number, date, geolocation fields.
-
query
(required) - Each request is considered a query against your engine. The query provides scope for the facet.
-
facets
(required) - The facets key opens up the object where you define your facet field.
-
field key
(required) - The field from your schema upon which to apply your facet.
-
type
(required) - Type of facet, in this case it will be range.
-
name
(optional) - Name given to facet.
-
ranges
(required) - An array of range objects.
-
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.
-
name
(optional) - Name given to the range.
Range Facet on a Number Field
editExample - Getting the counts for small and large parks, based on acreage, for the "park" query, within a facet named "min-and-max-range".
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", "facets": { "acres": [ { "type": "range", "name": "min-and-max-range", "ranges": [ { "from": 1, "to": 10000 }, { "from": 10000 } ] } ] } }'
Example Response
{ "meta": { "alerts": [], "warnings": [], "page": { "current": 1, "total_pages": 5, "total_results": 46, "size": 10 }, "request_id": "92bfcf6d-307c-4ca6-b12c-ac21283244e3" }, "results": [ ## Truncated! ], "facets": { "acres": [ { "type": "range", "name": "min-and-max-range", "data": [ { "to": 10000, "from": 1, "count": 2 }, { "from": 10000, "count": 44 } ] } ] } }
Range Facet on a Date Field
editExample - Getting a list of "parks" that were established between 1900
and 1950
. RFC3339 formatted dates. The facet is named "half-century".
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", "facets": { "date_established": [ { "type": "range", "name": "half-century", "ranges": [ { "from": "1900-01-01T12:00:00+00:00", "to": "1950-01-01T00:00:00+00:00" } ] } ] } }'
Example Response
{ "meta": { "alerts": [], "warnings": [], "page": { "current": 1, "total_pages": 5, "total_results": 46, "size": 10 }, "request_id": "bb038d5920f65692ccafd569ce86c3a7" }, "results": [ ## Truncated! ], "facets": { "date_established": [ { "type": "range", "name": "half-century", "data": [ { "to": "1950-01-01T00:00:00.000Z", "from": "1900-01-01T12:00:00.000Z", "count": 15 } ] } ] } }
Range Facet on a Geolocation Field
edit-
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 (mile).
Example - Getting a facet count of "parks" relative to their location in meters to the Elastic San Francisco office. The three ranged buckets are labelled: "Nearby", "A Longer Drive", and "Perhaps fly?". The facet is named "geo-range-from-san-francisco".
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", "facets": { "location": [ { "type": "range", "name": "geo-range-from-san-francisco", "center": "37.386483, -122.083842", "unit": "m", "ranges": [ { "from": 0, "to": 100000, "name": "Nearby" }, { "from": 100000, "to": 300000, "name": "A longer drive." }, { "from": 300000, "name": "Perhaps fly?" } ] } ] } }'
Example Response
{ "meta": { "alerts": [], "warnings": [], "page": { "current": 1, "total_pages": 5, "total_results": 46, "size": 10 }, "request_id": "afd0b735-85e8-4705-94d6-faea30eb1d63" }, "results": [ ## Truncated! ], "facets": { "location": [ { "type": "range", "name": "geo-range-from-san-francisco", "data": [ { "to": 100000, "from": 0, "name": "Nearby", "count": 0 }, { "to": 300000, "from": 100000, "name": "A longer drive.", "count": 2 }, { "from": 300000, "name": "Perhaps fly?", "count": 44 } ] } ] } }
Errors
edit
|
If the faceting field is not in the schema. If the requested facets JSON object is malformed. If a value facet is on a field type that is not text, number, or date. If a range facet is on a field type that is not number, date, or geolocation. If a range facet does not provide ranges in an acceptable format for the field type. |