> ## 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.

# Aggregations

> Compute analytics over indexed data with metric and bucket aggregations, from averages and sums to terms, ranges, and histograms in Upstash Redis Search.

Aggregations let you compute analytics over your indexed data — metrics like averages, sums, and statistics,
as well as bucket-based groupings like terms, ranges, and histograms.

They are useful when you want to answer questions like:

* "What is the average price?"
* "How many unique users do we have?"
* "How many orders fall into each price range?"
* "How does traffic change per hour/day?"

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={"system"}
    const result = await index.aggregate({
      aggregations: {
        avg_price: { $avg: { field: "price" } },
      },
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    result = index.aggregate(
        aggregations={"avg_price": {"$avg": {"field": "price"}}},
    )
    ```
  </Tab>

  <Tab title="Redis CLI">
    ```bash theme={"system"}
    SEARCH.AGGREGATE products '{}' '{"avg_price": {"$avg": {"field": "price"}}}'
    ```
  </Tab>
</Tabs>

Aggregation requests have two phases:

1. **Document selection**: Optional `filter` selects which documents participate.
2. **Aggregation computation**: the selected set is reduced into metric values and/or buckets.

Each aggregation is defined with an **alias** (the key you choose for the result) and an **operator** that specifies what to compute.

### Response Format

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={"system"}
    const result = await index.aggregate({
      aggregations: {
        avg_price: { $avg: { field: "price" } },
        by_category: { $terms: { field: "category", size: 5 } },
      },
    });

    // result is an object keyed by alias:
    // {
    //   avg_price: { value: 49.99 },
    //   by_category: {
    //     buckets: [
    //       { key: "electronics", docCount: 42 },
    //       { key: "clothing", docCount: 31 },
    //     ],
    //   },
    // }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    result = index.aggregate(
        aggregations={
            "avg_price": {"$avg": {"field": "price"}},
            "by_category": {"$terms": {"field": "category", "size": 5}},
        },
    )

    # result is a dict keyed by alias:
    # {
    #   "avg_price": {"value": 49.99},
    #   "by_category": {
    #     "buckets": [
    #       {"key": "electronics", "docCount": 42},
    #       {"key": "clothing", "docCount": 31},
    #     ],
    #   },
    # }
    ```
  </Tab>

  <Tab title="Redis CLI">
    ```bash theme={"system"}
    SEARCH.AGGREGATE products '{}' '{"avg_price": {"$avg": {"field": "price"}}, "by_category": {"$terms": {"field": "category", "size": 5}}}'

    # Response (`redis-cli --json`) is an object keyed by alias:
    # {"avg_price":{"value":49.99},"by_category":{"buckets":[{"key":"electronics","docCount":42},{"key":"clothing","docCount":31}]}}
    ```
  </Tab>
</Tabs>

## Filtering

Use `filter` to restrict which documents participate in the aggregation.

Filtering uses the same query syntax as [queries](./querying).

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={"system"}
    const result = await index.aggregate({
      filter: { inStock: true },
      aggregations: {
        avg_price: { $avg: { field: "price" } },
      },
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    result = index.aggregate(
        filter={"inStock": True},
        aggregations={
            "avg_price": {"$avg": {"field": "price"}},
        },
    )
    ```
  </Tab>

  <Tab title="Redis CLI">
    ```bash theme={"system"}
    SEARCH.AGGREGATE products '{"inStock": true}' '{"avg_price": {"$avg": {"field": "price"}}}'
    ```
  </Tab>
</Tabs>

## Multiple Aggregations in One Request

You can compute multiple top-level aggregations in one call by defining multiple aliases under `aggregations`.

Each alias is computed against the same filtered document set.

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={"system"}
    const result = await index.aggregate({
      aggregations: {
        avg_price: { $avg: { field: "price" } },
        price_stats: { $stats: { field: "price" } },
        by_category: { $terms: { field: "category", size: 5 } },
        price_ranges: {
          $range: {
            field: "price",
            ranges: [{ to: 50 }, { from: 50 }],
          },
        },
      },
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    result = index.aggregate(
        aggregations={
            "avg_price": {"$avg": {"field": "price"}},
            "price_stats": {"$stats": {"field": "price"}},
            "by_category": {"$terms": {"field": "category", "size": 5}},
            "price_ranges": {
                "$range": {
                    "field": "price",
                    "ranges": [{"to": 50}, {"from": 50}],
                }
            },
        },
    )
    ```
  </Tab>

  <Tab title="Redis CLI">
    ```bash theme={"system"}
    SEARCH.AGGREGATE products '{}' '{"avg_price": {"$avg": {"field": "price"}}, "price_stats": {"$stats": {"field": "price"}}, "by_category": {"$terms": {"field": "category", "size": 5}}, "price_ranges": {"$range": {"field": "price", "ranges": [{"to": 50}, {"from": 50}]}}}'
    ```
  </Tab>
</Tabs>

## Nested Aggregations

Bucket operators can include sub-aggregations via `$aggs`, so you can compute per-bucket metrics.

* `$terms`, `$range`, `$histogram`, and `$dateHistogram` support nested `$aggs`.
* `$facet` does not support nested `$aggs`.
* Metric operators do not support nested `$aggs`.

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={"system"}
    const result = await index.aggregate({
      aggregations: {
        by_category: {
          $terms: { field: "category" },
          $aggs: {
            avg_price: { $avg: { field: "price" } },
            min_price: { $min: { field: "price" } },
          },
        },
      },
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    result = index.aggregate(
        aggregations={
            "by_category": {
                "$terms": {"field": "category"},
                "$aggs": {
                    "avg_price": {"$avg": {"field": "price"}},
                    "min_price": {"$min": {"field": "price"}},
                },
            },
        },
    )
    ```
  </Tab>

  <Tab title="Redis CLI">
    ```bash theme={"system"}
    SEARCH.AGGREGATE products '{}' '{"by_category": {"$terms": {"field": "category"}, "$aggs": {"avg_price": {"$avg": {"field": "price"}}, "min_price": {"$min": {"field": "price"}}}}}'
    ```
  </Tab>
</Tabs>

## Operator Families

### Metric Aggregations

Metric aggregations return numeric summaries.

| Operator                                                                       | Typical use                    |
| ------------------------------------------------------------------------------ | ------------------------------ |
| [`$avg`](./aggregation-operators/metric-aggregations/avg)                      | Mean value                     |
| [`$sum`](./aggregation-operators/metric-aggregations/sum)                      | Total                          |
| [`$min`](./aggregation-operators/metric-aggregations/min)                      | Smallest value                 |
| [`$max`](./aggregation-operators/metric-aggregations/max)                      | Largest value                  |
| [`$count`](./aggregation-operators/metric-aggregations/count)                  | Number of values               |
| [`$cardinality`](./aggregation-operators/metric-aggregations/cardinality)      | Number of distinct values      |
| [`$stats`](./aggregation-operators/metric-aggregations/stats)                  | Basic summary stats            |
| [`$extendedStats`](./aggregation-operators/metric-aggregations/extended-stats) | Stats + variance/std deviation |
| [`$percentiles`](./aggregation-operators/metric-aggregations/percentiles)      | Distribution cut points        |

See the [metric overview](./aggregation-operators/metric-aggregations/overview).

### Bucket Aggregations

Bucket aggregations partition documents into groups.

| Operator                                                                       | Typical use         |
| ------------------------------------------------------------------------------ | ------------------- |
| [`$terms`](./aggregation-operators/bucket-aggregations/terms)                  | Top values by field |
| [`$range`](./aggregation-operators/bucket-aggregations/range)                  | Custom ranges       |
| [`$histogram`](./aggregation-operators/bucket-aggregations/histogram)          | Fixed numeric bins  |
| [`$dateHistogram`](./aggregation-operators/bucket-aggregations/date-histogram) | Fixed time bins     |
| [`$facet`](./aggregation-operators/bucket-aggregations/facet)                  | Hierarchical facets |

See the [bucket overview](./aggregation-operators/bucket-aggregations/overview).