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.

Related Topics

Faceted Search