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

TypeScript

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

Python

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

Redis CLI

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