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

# $dateHistogram

`$dateHistogram` groups date values into fixed time buckets.

Use it for time-series analytics like events per hour/day.

### Compatibility

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

Field must be `FAST`.

### Arguments

| Argument         | Type                           | Required | Description                                                |
| ---------------- | ------------------------------ | -------- | ---------------------------------------------------------- |
| `field`          | `string`                       | Yes      | Date field to bucket on.                                   |
| `fixedInterval`  | `string`                       | Yes      | Interval string such as `"1m"`, `"1h"`, `"1d"`.            |
| `offset`         | `string`                       | 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: {
        by_day: {
          $dateHistogram: {
            field: "createdAt",
            fixedInterval: "1d",
          },
        },
      },
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    index.aggregate(
        aggregations={
            "by_day": {
                "$dateHistogram": {
                    "field": "createdAt",
                    "fixedInterval": "1d",
                }
            }
        }
    )
    ```
  </Tab>

  <Tab title="Redis CLI">
    ```bash theme={"system"}
    SEARCH.AGGREGATE logs '{}' '{"by_day": {"$dateHistogram": {"field": "createdAt", "fixedInterval": "1d"}}}'
    ```
  </Tab>
</Tabs>

### Output

```json theme={"system"}
{
  "by_day": {
    "buckets": [
      { "key": 1704067200000, "keyAsString": "2024-01-01T00:00:00Z", "docCount": 14 },
      { "key": 1704153600000, "keyAsString": "2024-01-02T00:00:00Z", "docCount": 9 }
    ]
  }
}
```