$range

$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

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

Python

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

Redis CLI

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.