ℹ️ For new users, we recommend using our native Elasticsearch tools, rather than the standalone App Search product. We are actively developing new features and capabilities in the Elastic Stack to help you build powerful search applications. Refer to this blog for more information.

« Search API boosts Search API filters »

› ›

Search API facets

edit

IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.

Search API facets

edit

We have a conceptual Facets guide, too.

Create value and range facets.

Type	Value Facet	Range Facet
`text`	Yes	No
`number`	Yes	Yes
`date`	Yes	Yes
`geolocation`	No	Yes

Value Facet

edit

Provides 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

edit

Returns 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

edit

Example - 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

edit

Example - 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

facets

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.

« Search API boosts Search API filters »