Facet Search by Histogram Aggregation

A multi-bucket values source-based aggregation.

Histogram aggregation is a multi-bucket values source-based aggregation that can be applied on numeric values extracted from the documents. It dynamically builds fixed size (also known as interval) buckets over the values.

Table 1. Request Body Description
Parameter	Value	Required	Value Type
`fieldName`	Facet attribute (same as `"facet"` in the basic facet request).	Yes	String
`faceType`	`"histogram"`	Yes	ENUM
`interval`	Interval of histogram, and it should be >`0`.	Yes	double
`offset`	Offset of the start value of the histogram. By default, it starts from `0`. By default, the bucket keys start with `0` and then continue in even-spaced steps of the interval. For example, if the interval is `10`, then the first buckets (assuming there is data inside them) are [0, 10), [10, 20), [20, 30). The bucket boundaries can be shifted by using the offset option. This can be best illustrated with an example. If there are 10 documents with values ranging from 5 to 14, using interval 10 will result in two buckets with 5 documents each. If an additional offset of 5 is used, there will be only one single bucket [5, 15) containing all the 10 documents.	No	double
`minDocCount`	Minimum docs count in histogram bar. If the bucket contains less documents than specified, the counter for the interval is skipped. Default value = `0`.	No	long
`missing`	The missing parameter defines how documents that are missing a value should be treated. By default, they are ignored.	No	Object

Response Format

The response for histogram aggregation contains a list of key-value for histogram buckets.

Example

POST /api/{tenantId}/entities/_facets
[
  {
    "fieldName": "attributes.height",
    "facetType": "histogram",
    "interval": 100,
    "offset": 5,
    "minDocCount": 1,
    "missing": 0
  }
]

Response

{
  "attributes.height": {
    "105.0": 2,
    "205.0": 1,
    "405.0": 1
  }
}

Result Explanation

Two documents that have an attribute “height” value range of 5-104; one document that has a value range of 105-204; zero documents with a value range of 205-304; one document with value range of 305-404. The interval of 205-304 (key “304”) is not present in the results because of "minDocCount": 1, and no values are in this interval.

Unify and manage your data

Facet Search by Histogram Aggregation

Footer