$range - Upstash Documentation

$range groups documents into custom ranges. Use it when bucket boundaries are defined by business logic (for example pricing tiers).

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.
`ranges`	`Array<{ key?: string, from?: number, to?: number }>`	Yes	Non-empty array of range objects.
`keyed`	`boolean`	No	If `true`, returns buckets as an object. Default: `false`.

from is inclusive. to is exclusive.

TypeScript
Python
Redis CLI

await index.aggregate({
  aggregations: {
    price_tiers: {
      $range: {
        field: "price",
        ranges: [{ to: 30 }, { from: 30, to: 60 }, { from: 60 }],
      },
    },
  },
});

index.aggregate(
    aggregations={
        "price_tiers": {
            "$range": {
                "field": "price",
                "ranges": [{"to": 30}, {"from": 30, "to": 60}, {"from": 60}],
            }
        }
    }
)

SEARCH.AGGREGATE products '{}' '{"price_tiers": {"$range": {"field": "price", "ranges": [{"to": 30}, {"from": 30, "to": 60}, {"from": 60}]}}}'

Output

{
  "price_tiers": {
    "buckets": [
      { "key": "*-30", "docCount": 3, "to": 30 },
      { "key": "30-60", "docCount": 3, "from": 30, "to": 60 },
      { "key": "60-*", "docCount": 3, "from": 60 }
    ]
  }
}

Bucket entries can include fromAsString / toAsString and nested sub-aggregation outputs.

​Compatibility

​Arguments

​Output

Compatibility

Arguments

Output