StarRocks DAYOFYEAR 函数详解获取日期在一年中的第几天【免费下载链接】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/starrocksDAYOFYEAR是 StarRocks 提供的日期时间函数之一用于返回给定日期在所属年份中的天数序号1 到 366。本文以官方 SQL 函数参考文档 dayofyear.md 为骨架结合 StarRocks 前后端源码与单元测试系统讲解该函数的语法、取值范围、实现原理与典型使用场景。读完本文你将掌握DAYOFYEAR的正确用法、闰年边界行为并理解它在查询引擎中的底层计算路径。函数定义与语法DAYOFYEAR(date)接收一个日期参数返回该日期是当年中的第几天。函数签名如下INT DAYOFYEAR(DATETIME|DATE date)参数类型date必须为DATE或DATETIME类型。DATE仅包含年月日DATETIME额外包含时分秒但DAYOFYEAR只关心日期部分时分秒不影响结果。返回类型INT类型整数取值范围为11 月 1 日到366闰年的 12 月 31 日。在 SQL 中传入日期字符串字面量时StarRocks 会自动将其转换为DATE/DATETIME类型参与计算因此可以直接写SELECT DAYOFYEAR(2007-02-03 00:00:00);返回值与取值范围返回值表示“该日期距离当年 1 月 1 日的天数差 1”平年全年 365 天返回值区间为[1, 365]闰年全年 366 天返回值区间为[1, 366]。这一取值范围在 FE 的优化器统计信息中得到了印证ExpressionStatisticCalculator.java 为FunctionSet.DAYOFYEAR注册了minValue 1、maxValue 366、distinctValue 366即优化器在估算含dayofyear(...)的谓词或投影表达式的行数/基数时会采用这一数值范围。使用示例官方文档给出的基准示例如下MySQL select dayofyear(2007-02-03 00:00:00); ---------------------------------- | dayofyear(2007-02-03 00:00:00) | ---------------------------------- | 34 | ----------------------------------结合返回值定义可以验证2007 年为平年2 月 3 日 311 月 3 第 34 天结果正确。围绕边界与典型场景可进一步验证-- 当年第 1 天 SELECT DAYOFYEAR(2024-01-01); -- 1 -- 平年年末 SELECT DAYOFYEAR(2023-12-31); -- 365 -- 闰年年末2024 年是闰年 SELECT DAYOFYEAR(2024-12-31); -- 366 -- DATE 类型参数 SELECT DAYOFYEAR(DATE 2024-03-01); -- 611 月 31 天 2 月 29 天 1 -- 在 WHERE 条件中过滤“一年中的第 100 天之后”的数据 SELECT * FROM events WHERE DAYOFYEAR(event_date) 100;DAYOFYEAR是严格单目函数输入非法日期如2023-02-29时SQL 层在日期解析阶段即会报错不会进入函数计算。源码级实现原理1. 存储层儒略日差值计算DAYOFYEAR的数学定义位于 BE 的时间值类型 datetime_value.hint day_of_year() const { return daynr() - calc_daynr(_year, 1, 1) 1; }其中daynr()返回当前日期对应的“从某基准日算起的累计天数”儒略日编号calc_daynr(_year, 1, 1)返回当年 1 月 1 日的编号两者相减再加 1即得到当年的第几天。这种基于儒略日编号的差减法不依赖月份天数表天然正确处理平年/闰年。2. 表达式层向量化单目函数BE 中dayofyear对应的内部函数名为day_of_year声明在 time_functions.h实现在 time_functions.cpp// day_of_year DEFINE_UNARY_FN_WITH_IMPL(day_of_yearImpl, v) { auto day (DateValue)v; int year, month, day1; day.to_date(year, month, day1); DateValue first_day_year; first_day_year.from_date(year, 1, 1); return day.julian() - first_day_year.julian() 1; } DEFINE_TIME_UNARY_FN(day_of_year, TYPE_DATETIME, TYPE_INT);实现要点先将输入值转换为DateValue拆出年份用同一年的 1 月 1 日构造first_day_year再做儒略日差值加 1DEFINE_TIME_UNARY_FN(day_of_year, TYPE_DATETIME, TYPE_INT)声明输入类型为TYPE_DATETIMEDATE会自动提升参与计算、输出类型为TYPE_INT该宏见 time_functions.cpp最终通过VectorizedStrictUnaryFunction以批处理向量化方式对整列求值配合day、month、quarter、week_of_year等函数共用同一套向量化框架因此在大表上执行全列计算时吞吐较高。3. 前端函数注册与解析FE 侧在 FunctionSet.java 中注册函数名常量public static final String DAYOFYEAR dayofyear;此外dayofyear还通过两种语法入口被解析为同一函数date_part/extract的单位别名在 ExpressionAnalyzer.java 中date_part(doy, date)或extract(doy from date)会将单位doy归一化映射到dayofyear与 PostgreSQL 的DOYday of year语义对齐ODBC 标量函数语法在 OdbcScalarFunctionCall.java 中{fn dayofyear(date)}这类 ODBC 转义语法也会被转换为内置函数dayofyear方便从支持 ODBC 标准标量函数的 BI 工具迁移。测试用例验证仓库内置的单元测试直接锁定了DAYOFYEAR的正确性类型层测试 datetime_value_test.cpp20070101→120070203→34与官方文档示例完全一致表达式层测试 time_functions_test.cpp对2020年的 6 个日期批量求值期望结果分别为1、33、66、99、130、308覆盖了年初、跨月与年末附近的不同位置该测试同时断言结果列是数值类型且不可为 NULL印证了DAYOFYEAR属于严格strict非空函数。与其他日期时间函数的对比DAYOFYEAR属于 StarRocks 日期时间函数族中的“年度周期定位”类函数与其相邻的同类函数包括函数返回值含义取值范围DAYOFYEAR(date)一年中的第几天1 ~ 366DAYOFWEEK(date)一周中的第几天1 ~ 7WEEKOFYEAR(date)一年中的第几周1 ~ 53QUARTER(date)所属季度1 ~ 4其中day_of_week、week_of_year等函数与day_of_year一样均在 time_functions.cpp 中通过同一套向量化宏实现输入输出约定一致可以组合使用完成“按年内的日/周/季度维度聚合”的分析需求例如SELECT DAYOFYEAR(dt) AS doy, COUNT(*) FROM events GROUP BY doy ORDER BY doy;注意事项DAYOFYEAR只取日期部分传入DATETIME时的时分秒不影响结果结果最大值取决于当年是否为闰年366/365跨年比较时需注意年份上下文参数必须是可转换为DATE/DATETIME的值对 NULL 输入函数返回 NULL若需要“一年中的第几周”或“一周中的第几天”语义请改用WEEKOFYEAR或DAYOFWEEK三者不可混用。如需查看完整函数定义可继续阅读官方参考文档 dayofyear.md以及上述 BE/FE 源码与测试文件。【免费下载链接】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），仅供参考