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

# $terms

`$terms` groups documents by distinct field values.

Each distinct value becomes one bucket with its own `docCount`.

### Compatibility

| Field Type | Supported |
| - | - |
| TEXT | No |
| U64/I64/F64 | Yes |
| DATE | Yes |
| BOOL | Yes |
| KEYWORD | Yes |
| FACET | No |

Field must be `FAST`.

### Arguments

| Argument | Type | Required | Description |
| - | - | - | - |
| `field` | `string` | Yes | Field to bucket on. |
| `size` | `number` | No | Max number of buckets returned. |
| `segmentSize` | `number` | No | Number of candidate terms collected per index segment before merging. Raising it improves count accuracy at higher cost; lowering it is cheaper but less accurate. See [Count accuracy](#count-accuracy). |
| `showTermDocCountError` | `boolean` | No | Include `docCountErrorUpperBound` in output. |
| `minDocCount` | `number` | No | Buckets with fewer docs are excluded. |
| `order` | `object` | No | One-key order object: `{ "count": "desc" }`, `{ "key": "asc" }`, or `{ "<subAggAlias>": "desc" }`. |
| `missing` | `string \| number` | No | Bucket key used when the field is missing. |
| `include` | `string \| string[]` | No | Include regex or explicit value list. |
| `exclude` | `string \| string[]` | No | Exclude regex or explicit value list. |

> [tab] TypeScript
>
> ```ts theme={"system"}
> await index.aggregate({
>   aggregations: {
>     by_category: {
>       $terms: { field: "category", size: 5 },
>     },
>   },
> });
> ```

> [tab] Python
>
> ```python theme={"system"}
> index.aggregate(
>     aggregations={
>         "by_category": {
>             "$terms": {"field": "category", "size": 5}
>         }
>     }
> )
> ```

> [tab] Redis CLI
>
> ```bash theme={"system"}
> SEARCH.AGGREGATE products '{}' '{"by_category": {"$terms": {"field": "category", "size": 5}}}'
> ```

### Output

```json theme={"system"}
{
  "by_category": {
    "buckets": [
      { "key": "electronics", "docCount": 120 },
      { "key": "books", "docCount": 83 }
    ],
    "sumOtherDocCount": 42
  }
}
```

* `sumOtherDocCount` is the number of matching documents that fell outside the returned buckets.

### Count accuracy

> [!WARNING]
>
> `$terms` bucket counts are **approximate**. Terms are tallied per index segment and then merged, so a term's `docCount` can be slightly off, especially for terms near the `size` cutoff.

`docCountErrorUpperBound` reports the maximum possible error on the returned counts (set `showTermDocCountError: true` for per-bucket values), and `sumOtherDocCount` is the number of matching documents not included in the returned buckets. Raising `segmentSize` reduces the error at the cost of more work per query. For an exact count of a specific term, use [`SEARCH.COUNT`](https://upstash.com/docs/redis/commands/search/search-count) instead of reading it from a bucket.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.