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

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 }    ]  }}