> ## 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       | Internal candidate size used while collecting top terms.                                           |
| `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.                                                              |

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

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

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

### Output

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