> ## Documentation Index
> Fetch the complete documentation index at: https://upstash-dx-3081-agentkit-tanstack-ai-backends.mintlify.site/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={null}
    await index.aggregate({
      aggregations: {
        by_day: {
          $dateHistogram: {
            field: "createdAt",
            fixedInterval: "1d",
          },
        },
      },
    });
    ```
  </Tab>

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

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

### Output

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


## Related topics

- [Overview](/redis/search/aggregation-operators/bucket-aggregations/overview.md)
- [$composite](/redis/search/aggregation-operators/bucket-aggregations/composite.md)
- [Aggregations](/redis/search/aggregations.md)
- [SEARCH.AGGREGATE](/redis/commands/search/search-aggregate.md)
- [$histogram](/redis/search/aggregation-operators/bucket-aggregations/histogram.md)