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

TypeScript
Python
Redis CLI

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.

​Compatibility

​Arguments

​Output

Compatibility

Arguments

Output