Facets

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

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://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",
  "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

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

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://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",
  "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

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://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",
  "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

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, 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://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",
  "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

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.