$dateHistogram - Upstash Documentation

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

TypeScript
Python
Redis CLI

await index.aggregate({
  aggregations: {
    by_day: {
      $dateHistogram: {
        field: "createdAt",
        fixedInterval: "1d",
      },
    },
  },
});

index.aggregate(
    aggregations={
        "by_day": {
            "$dateHistogram": {
                "field": "createdAt",
                "fixedInterval": "1d",
            }
        }
    }
)

SEARCH.AGGREGATE logs '{}' '{"by_day": {"$dateHistogram": {"field": "createdAt", "fixedInterval": "1d"}}}'

Output

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

​Compatibility

​Arguments

​Output

Compatibility

Arguments

Output