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

# $histogram

`$histogram` groups numeric values into fixed-width interval buckets.

Use it for distribution charts when each bucket has the same width.

### Compatibility

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

Field must be `FAST`.

### Arguments

| Argument         | Type                           | Required | Description                                                |
| ---------------- | ------------------------------ | -------- | ---------------------------------------------------------- |
| `field`          | `string`                       | Yes      | Field to bucket on.                                        |
| `interval`       | `number`                       | Yes      | Bucket width.                                              |
| `offset`         | `number`                       | No       | Shift bucket boundaries.                                   |
| `minDocCount`    | `number`                       | No       | Exclude buckets with fewer docs.                           |
| `hardBounds`     | `{ min: number, max: number }` | No       | Hard clamp for bucket range.                               |
| `extendedBounds` | `{ min: number, max: number }` | No       | Emit buckets across this range, including empty ones.      |
| `keyed`          | `boolean`                      | No       | If `true`, returns buckets as an object. Default: `false`. |

For `hardBounds` and `extendedBounds`, both `min` and `max` are required.

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={"system"}
    await index.aggregate({
      aggregations: {
        price_distribution: {
          $histogram: { field: "price", interval: 25 },
        },
      },
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    index.aggregate(
        aggregations={
            "price_distribution": {
                "$histogram": {"field": "price", "interval": 25}
            }
        }
    )
    ```
  </Tab>

  <Tab title="Redis CLI">
    ```bash theme={"system"}
    SEARCH.AGGREGATE products '{}' '{"price_distribution": {"$histogram": {"field": "price", "interval": 25}}}'
    ```
  </Tab>
</Tabs>

### Output

```json theme={"system"}
{
  "price_distribution": {
    "buckets": [
      { "key": 0, "docCount": 3 },
      { "key": 25, "docCount": 4 },
      { "key": 50, "docCount": 2 }
    ]
  }
}
```

Bucket entries can include `keyAsString` and nested sub-aggregation outputs.