IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Search API boosts Search API filters »

› ›

Search API facets

edit

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. 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 'https://[instance id].ent-search.[region].[provider].cloud.es.io/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 'https://[instance id].ent-search.[region].[provider].cloud.es.io/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 'https://[instance id].ent-search.[region].[provider].cloud.es.io/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 'https://[instance id].ent-search.[region].[provider].cloud.es.io/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 »