elasticsearch/docs/reference/search/facets/range-facet.asciidoc

[[search-facets-range-facet]]
=== Range Facets

include::deprecated.asciidoc[]

`range` facet allows to specify a set of ranges and get both the number
of docs (count) that fall within each range, and aggregated data either
based on the field, or using another field. Here is a simple example:

[source,js]
--------------------------------------------------
{
    "query" : {
        "match_all" : {}
    },
    "facets" : {
        "range1" : {
            "range" : {
                "field" : "field_name",
                "ranges" : [
                    { "to" : 50 },
                    { "from" : 20, "to" : 70 },
                    { "from" : 70, "to" : 120 },
                    { "from" : 150 }
                ]
            }
        }
    }
}
--------------------------------------------------

Another option which is a bit more DSL enabled is to provide the ranges
on the actual field name, for example:

[source,js]
--------------------------------------------------
{
    "query" : {
        "match_all" : {}
    },
    "facets" : {
        "range1" : {
            "range" : {
                "my_field" : [
                    { "to" : 50 },
                    { "from" : 20, "to" : 70 },
                    { "from" : 70, "to" : 120 },
                    { "from" : 150 }
                ]
            }
        }
    }
}
--------------------------------------------------

The `range` facet always includes the `from` parameter and excludes the
`to` parameter for each range.

==== Key and Value

The `range` facet allows to use a different field to check if its value
falls within a range, and another field to compute aggregated data per
range (like total). For example:

[source,js]
--------------------------------------------------
{
    "query" : {
        "match_all" : {}
    },
    "facets" : {
        "range1" : {
            "range" : {
                "key_field" : "field_name",
                "value_field" : "another_field_name",
                "ranges" : [
                    { "to" : 50 },
                    { "from" : 20, "to" : 70 },
                    { "from" : 70, "to" : 120 },
                    { "from" : 150 }
                ]
            }
        }
    }
}
--------------------------------------------------

==== Script Key and Value

Sometimes, some munging of both the key and the value are needed. In the
key case, before it is checked if it falls within a range, and for the
value, when the statistical data is computed per range scripts can be
used. Here is an example:

[source,js]
--------------------------------------------------
{
    "query" : {
        "match_all" : {}
    },
    "facets" : {
        "range1" : {
            "range" : {
                "key_script" : "doc['date'].date.minuteOfHour",
                "value_script" : "doc['num1'].value",
                "ranges" : [
                    { "to" : 50 },
                    { "from" : 20, "to" : 70 },
                    { "from" : 70, "to" : 120 },
                    { "from" : 150 }
                ]
            }
        }
    }
}
--------------------------------------------------

==== Date Ranges

The range facet support also providing the range as string formatted
dates.