$histogram

$histogram groups numeric values into fixed-width interval buckets.

Use it for distribution charts when each bucket has the same width.

Compatibility

Field Type	Supported
TEXT	No
U64/I64/F64	Yes
DATE	Yes
BOOL	No
KEYWORD	No
FACET	No

Field must be FAST.

Arguments

Argument	Type	Required	Description
field	string	Yes	Field to bucket on.
interval	number	Yes	Bucket width.
offset	number	No	Shift bucket boundaries.
minDocCount	number	No	Exclude buckets with fewer docs.
hardBounds	{ min: number, max: number }	No	Hard clamp for bucket range.
extendedBounds	{ min: number, max: number }	No	Emit buckets across this range, including empty ones.
keyed	boolean	No	If true, returns buckets as an object. Default: false.

For hardBounds and extendedBounds, both min and max are required.

TypeScript

await index.aggregate({
  aggregations: {
    price_distribution: {
      $histogram: { field: "price", interval: 25 },
    },
  },
});

Python

index.aggregate(
    aggregations={
        "price_distribution": {
            "$histogram": {"field": "price", "interval": 25}
        }
    }
)

Redis CLI

SEARCH.AGGREGATE products '{}' '{"price_distribution": {"$histogram": {"field": "price", "interval": 25}}}'

Output

{
  "price_distribution": {
    "buckets": [
      { "key": 0, "docCount": 3 },
      { "key": 25, "docCount": 4 },
      { "key": 50, "docCount": 2 }
    ]
  }
}

Bucket entries can include keyAsString and nested sub-aggregation outputs.