> ## Documentation Index
> Fetch the complete documentation index at: https://upstash-dx-3081-agentkit-tanstack-ai-backends.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={null}
{"by_category": {"$terms": {"field": "category", "size": 10}}}
```

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

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

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

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

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

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

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

```json theme={null}
{"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.


## Related topics

- [Overview](/qstash/sdks/py/examples/overview.md)