> ## Documentation Index
> Fetch the complete documentation index at: https://upstash-cloud-4725.mintlify.site/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                 |
| [`$composite`](./composite)          | Paginated combinations of several sources |
| [`$facet`](./facet)                  | Hierarchical FACET paths                  |

### Input Format

Most bucket operators take an object with a `field` property and operator-specific parameters. `$composite` instead takes a `sources` array, and each source specifies its own field.

**`$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"}}}
```

**`$composite`** — paginated buckets across several sources:

```json theme={"system"}
{"by_category_and_price": {"$composite": {"size": 100, "sources": [{"category": {"$terms": {"field": "category"}}}, {"price": {"$histogram": {"field": "price", "interval": 10}}}]}}}
```

### Behavior Notes

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