> ## Documentation Index
> Fetch the complete documentation index at: https://upstash-worktree-docs-descriptions.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Group documents into buckets with $terms, $range, $histogram, $dateHistogram, and $facet aggregations for segmented analytics in Upstash Redis Search.

Bucket aggregations group matching documents into buckets.

Use bucket aggregations when you want segmented analytics (for example by category, price tier, or time window).

### Available Operators

| Operator                             | What it groups by             |
| ------------------------------------ | ----------------------------- |
| [`$terms`](./terms)                  | Distinct field values         |
| [`$range`](./range)                  | Explicit `from` / `to` ranges |
| [`$histogram`](./histogram)          | Fixed numeric intervals       |
| [`$dateHistogram`](./date-histogram) | Fixed date/time intervals     |
| [`$facet`](./facet)                  | Hierarchical FACET paths      |

### Input Format

Every bucket operator takes an object with a `field` property and operator-specific parameters:

**`$terms`** — group by distinct values:

```json theme={"system"}
{"by_category": {"$terms": {"field": "category", "size": 10}}}
```

**`$range`** — custom range buckets:

```json theme={"system"}
{"price_ranges": {"$range": {"field": "price", "ranges": [{"to": 50}, {"from": 50, "to": 100}, {"from": 100}]}}}
```

**`$histogram`** — fixed numeric intervals:

```json theme={"system"}
{"price_buckets": {"$histogram": {"field": "price", "interval": 10}}}
```

**`$dateHistogram`** — fixed time intervals:

```json theme={"system"}
{"by_month": {"$dateHistogram": {"field": "createdAt", "fixedInterval": "30d"}}}
```

### Behavior Notes

* Bucket operators can contain nested `$aggs` for per-bucket metrics.
* `$terms`, `$range`, `$histogram`, and `$dateHistogram` support nested `$aggs`.
* `$facet` does not support nested `$aggs` and cannot be used as a sub-aggregation.