StarRocks days_diff 函数详解按秒精度计算两个时间点的天数差【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocksdays_diff是 StarRocks 内置的日期时间函数用于计算两个日期时间表达式之间的天数差expr1 - expr2。与只取日期部分的datediff不同days_diff会精确到秒参与计算并对结果向下取整非常适合需要按完整 24 小时为单位统计时间跨度的业务场景。读完本文你将掌握days_diff的语法、边界语义、与datediff/date_diff的差异以及它在 StarRocks 源码中的真实实现原理。函数定位精确到秒、向下取整的天数差days_diff返回两个日期表达式之间的天数差expr1 − expr2结果精确到天。其核心语义特征是计算精确到秒并对结果向下取整floor到最近的整数。这意味着它衡量的是两个时间点之间跨越了多少个完整的 24 小时周期而不是简单的日历日之差。该函数对应的文档位于 days_diff.md在 FE 端的函数注册表中被声明为DAYS_DIFF见 FunctionSet.javaBE 端的向量化实现则位于 time_functions.cpp 与 time_functions.h。语法BIGINT days_diff(DATETIME expr1,DATETIME expr2);返回类型为BIGINTexpr1与expr2均需为DATETIME或DATE类型函数计算expr1 − expr2因此当expr1早于expr2时返回负值。参数说明参数含义类型要求expr1结束时间DATETIME或DATEexpr2开始时间DATETIME或DATE两个参数都接受DATETIME含时分秒与DATE仅日期类型。传入DATE时其时分秒部分按00:00:00参与计算。返回值与边界语义返回BIGINT类型的天数差。若传入的日期不存在例如2022-02-29这样的非法日期返回NULL。days_diff会将时、分、秒部分纳入计算若两个时间点的差值不足 1 天则返回0向下取整的结果。当expr1早于expr2时结果为负值。结合源码来看这一不足 1 天即返回 0的行为来自days_diffImpl对微秒差的整除取整逻辑见下文的实现原理小节。与 datediff 的区别秒级精度 vs 日期级精度days_diff与 datediff 是 StarRocks 中极易混淆的一对函数二者的差异在于计算精度函数行为示例days_diff计算精确到秒结果向下取整到最近的整数2020-12-25 23:00:00与2020-12-24 23:00:01之间的 days_diff 为 0datediff计算精确到天仅使用日期部分2020-12-25 23:00:00与2020-12-24 23:00:01之间的 datediff 为 1以文档中的经典例子说明2020-12-25 23:00:00与2020-12-24 23:00:01相差约 23 小时 59 分 59 秒不足一个完整 24 小时周期因此days_diff向下取整返回0而datediff只看日期部分12 月 25 日与 12 月 24 日返回1。此外StarRocks 还提供date_diff函数它支持通过unit参数指定返回单位year/month/quarter/day/hour/minute/second/millisecond详见 date_diff。三者的适用场景可以概括为需要按完整 24 小时精确度量时间跨度 → 使用days_diff只关心日历日之差、忽略时分秒 → 使用datediff需要统一以年月日时分秒等不同单位返回差值 → 使用date_diff。示例在 MySQL 客户端中执行select days_diff(2010-11-30 23:00:00, 2010-11-29 23:00:00) --------------------------------------------------------- | days_diff(2010-11-30 23:00:00, 2010-11-29 23:00:00) | --------------------------------------------------------- | 1 | --------------------------------------------------------- select days_diff(2010-11-30 23:00:00, 2010-11-29 23:10:00) --------------------------------------------------------- | days_diff(2010-11-30 23:00:00, 2010-11-29 23:10:00) | --------------------------------------------------------- | 0 | ---------------------------------------------------------第一个例子中两个时间点相差恰好 24 小时返回1第二个例子中相差 23 小时 50 分钟不足 24 小时向下取整后返回0。源码级实现原理days_diff在 BE 端是一个向量化二元函数其实现位于 time_functions.cpp// days_diff DEFINE_BINARY_FUNCTION_WITH_IMPL(days_diffImpl, l, r) { return l.diff_microsecond(r) / USECS_PER_DAY; } DEFINE_TIME_BINARY_FN(days_diff, TYPE_DATETIME, TYPE_DATETIME, TYPE_BIGINT);实现要点l.diff_microsecond(r)先计算出两个TimestampValue之间精确到微秒的时间差包含时分秒因此days_diff天然具备秒级乃至微秒级精度随后用该微秒差除以USECS_PER_DAY一天的微秒数即 86,400,000,000。由于整型除法本身即等价于向下取整所以差值不足一天时结果为0与文档描述完全一致函数注册为TYPE_DATETIME, TYPE_DATETIME → TYPE_BIGINT即两个 DATETIME 参数返回 BIGINT。声明位置见 time_functions.hDEFINE_VECTORIZED_FN(days_diff)与之紧邻的是date_diff、time_diff、weeks_diff等同族函数它们共用diff_microsecond基础能力。测试用例验证在 time_functions_test.cpp 中days_diff有直接的单测覆盖测试构造了 6 组时间对如2020-06-20 13:48:25与2020-06-20 13:48:30、跨日跨月等组合期望输出为[5, 6, 8, 0, 0, 0]其中后三组时间差不足一天含负数方向的情况均被向下取整为0。该测试与date_diff的测试共用同一组输入数据见 time_functions_test.cpp可以直观对比两种函数在同一批数据下的不同结果date_diff输出[6, 6, 8, -1, 0, 0]而days_diff输出[5, 6, 8, 0, 0, 0]——差值不足一天时date_diff按日期差给出-1days_diff则取整为0。使用建议与注意事项按需选择精度统计打卡间隔是否满 24 小时、订单超时是否跨完整一天等场景优先用days_diff仅按自然日对齐如今天距离注册日多少天用datediff更直观。注意结果的符号days_diff返回expr1 − expr2当expr1 expr2时结果为负若业务只关心绝对间隔可在外层套用abs()。警惕非法日期输入不存在的日期如2022-02-29会返回NULL与datediff一致处理结果时需考虑NULL传播。类型隐式转换DATE类型可作为参数直接传入其时间部分按00:00:00处理跨时区场景建议先统一时区再做差值计算避免边界误差。【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考