# $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
await index.aggregate({
  aggregations: {
    price_distribution: {
      $histogram: { field: "price", interval: 25 },
    },
  },
});
```
</Tab>

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

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

</Tabs>

### Output

```json
{
  "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.