Facets

Facets are aggregate information collected on a particular result set.

In Facets, you already have a search in mind, and you want to collect additional facet information along with it.

All of the facet examples given in this topic are for the query "water" on the beer-sample dataset.

FTS supports the following types of facets:

Term Facet - A term facet counts up how many of the matching documents have a particular term in a particular field. Most of the time, this only makes sense for relatively low cardinality fields, like a type or tags. It would not make sense to use it on a unique field like an ID.
Numeric Range Facet - A numeric range facet works by the user defining their own buckets (numeric ranges). The facet then counts how many of the matching documents fall into a particular bucket for a particular field.
Date Range Facet - same as numeric, but on dates instead of numbers. Full text search and Bleve expect dates to be in the format specified by RFC-3339, which is a specific profile of ISO-8601 that is more restrictive.

Most of the time, when building a term facet, you must use the keyword analyzer. Otherwise, multi-term values are tokenized, which might cause unexpected results.

Example

Term Facet - computes facet on the type field which has 2 values: beer and brewery.

curl -X POST -H "Content-Type: application/json" \
http://localhost:8094/api/index/bix/query -d \
'{
    "size": 10,
    "query": {
        "boost": 1,
        "query": "water"
     },
    "facets": {
         "type": {
             "size": 5,
             "field": "type"
         }
    }
}'

The result snippet below, only shows the facet section for clarity. Run the curl command to see the HTTP response containing the full results.

"facets": {
    "type": {
        "field": "type",
        "total": 91,
        "missing": 0,
        "other": 0,
        "terms": [
            {
                "term": "beer",
                "count": 70
            },
            {
                "term": "brewery",
                "count": 21
            }
        ]
    }
}

Numeric Range Facet - computes facet on the abv field with two buckets describing high (greater than 7) and low (less than 7).

curl -X POST -H "Content-Type: application/json" \
http://localhost:8094/api/index/bix/query -d \
'{
    "size": 10,
    "query": {
        "boost": 1,
        "query": "water"
    },
    "facets": {
        "abv": {
            "size": 5,
            "field": "abv",
            "numeric_ranges": [
                {
                    "name": "high",
                    "min": 7
                },
                {
                    "name": "low",
                    "max": 7
                }
             ]
        }
    }
}'

Results:

facets": {
    "abv": {
        "field": "abv",
        "total": 70,
        "missing": 21,
        "other": 0,
        "numeric_ranges": [
            {
                "name": "high",
                "min": 7,
                "count": 13
            },
            {
                "name": "low",
                "max": 7,
                "count": 57
            }
        ]
    }
}