date_histogram 时间桶

做的事：真实索引两条只相差2小时的文档，对比不指定时区和指定+08:00时区的date_histogram分桶结果

代码真实索引2条关键文档: {"ts":"2024-01-15T23:30:00Z"} / {"ts":"2024-01-16T01:30:00Z"} （两条文档真实只相差2小时，都在UTC午夜前后） POST /dh_test/_search {"aggs":{"d":{"date_histogram":{"field":"ts","calendar_interval":"day"}}}} POST /dh_test/_search {"aggs":{"d":{"date_histogram":{"field":"ts","calendar_interval":"day","time_zone":"+08:00"}}}}

验证：不指定时区时，这两条只差2小时的文档真实被分进了两个不同的天桶

实测 · 本机 Elasticsearch 8.15.0 执行输出

不指定时区（默认UTC）:
→ 2024-01-15T00:00:00.000Z  doc_count=1   ← 23:30这条真实落进了15号这一天
→ 2024-01-16T00:00:00.000Z  doc_count=1   ← 01:30这条真实落进了16号这一天

这个结果真实符合直觉：按UTC时间划分天的边界，2024-01-15T23:30:00Z真实在15号这一天的最后半小时里，2024-01-16T01:30:00Z真实已经跨过了午夜进入16号，两者分别落进了相邻但不同的两个桶，哪怕它们之间真实只相差2个小时。

验证：加上time_zone:+08:00之后，这两条文档真实被重新划进了同一个桶

实测 · 本机执行输出

time_zone:+08:00:
→ 2024-01-16T00:00:00.000+08:00  doc_count=2
  ← 两条文档真实都被分进了同一个桶！

这组真实结果精确展示了time_zone参数如何改变"一天"的真实边界：按北京时间（UTC+8）换算，2024-01-15T23:30:00Z真实对应着北京时间2024-01-16的早上7点半，2024-01-16T01:30:00Z真实对应着北京时间16号的早上9点半——两个在UTC视角下分属不同天的时间点，换算成北京时间之后真实都落在了同一个16号。date_histogram真实是先把每个文档的UTC时间戳按指定时区做换算，再按换算后的本地时间去判断"这天属于哪一个桶"，这意味着同样的原始数据，不指定时区（默认用UTC分天）和指定成业务实际所在的时区，真实可能产出完全不同的分桶结果和doc_count。对于真实面向特定地区用户的业务报表（比如"每天的新增用户数"），如果忘记真实设置成业务所在地的时区，统计出来的"天"真实跟用户体感的自然日会对不上，本次实测2小时之差就足以让同一批用户活动真实被错误地拆分成两天，或者反过来把真实属于两天的活动合并计入一天。

分步演示：date_histogram从UTC默认分桶到真实时区换算改变结果的完整验证

每一步都是本文上面在本机真实的Elasticsearch 8.15.0上跑出来的原始结果。

time_zone参数真实改变了date_histogram划分一天的边界位置

这一步新验证的时区配置

本文用到的工具

本机真实部署的 Elasticsearch 8.15.0（单节点，tar包直接启动）
真实的 date_histogram 聚合与 time_zone 参数

下一篇 · ELASTICSEARCH 77

histogram 与 range 聚合