$histogram - Upstash Documentation

$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.

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

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

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.