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

# Overview

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.