StarRocks TIME_FORMAT 函数详解TIME 类型时间格式化实战指南【免费下载链接】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导读本文以 StarRocks 官方文档 time_format 为主体结合前端函数注册与后端列式计算实现源码系统讲解TIME_FORMAT函数的语法、全部格式说明符、真实执行行为与边界情况。读完本文你将掌握如何将 TIME 类型值按任意自定义模板输出为 VARCHAR 字符串并能理解其在 StarRocks 向量化执行引擎中的底层工作原理。一、函数定位TIME 类型专属的格式化函数StarRocks 的日期时间函数家族中date_format、datetime_format面向 DATETIME/DATE 类型而TIME_FORMAT是专门为TIME 类型设计的格式化函数它接受一个 TIME 值和一个格式模板返回按模板渲染后的 VARCHAR 字符串适用于需要将时分秒可含微秒按自定义样式展示的场景例如报表中的07:30:10 PM、14:30等输出需求。从实现层面看该函数在 FE 端通过 FunctionSet.java 中的TIME_FORMAT time_format注册为内置标量函数在 BE 端由 time_functions.cpp 的TimeFunctions::time_format执行函数签名与文档声明完全对应VARCHAR TIME_FORMAT(TIME time, VARCHAR format)二、语法与参数说明VARCHAR TIME_FORMAT(TIME time, VARCHAR format)参数类型是否必填说明timeTIME必填待格式化的时间值仅支持 TIME 类型formatVARCHAR必填格式化模板由格式说明符与普通字符混合组成三、格式说明符全解TIME_FORMAT支持的格式说明符共 7 个覆盖了时、分、秒、微秒与上下午标识%f Microseconds (000000 to 999999) %H Hour (00 to 23) %h Hour (00 to 12) %i Minutes (00 to 59) %p AM or PM %S Seconds (00 to 59) %s Seconds (00 to 59)对照 time_functions.cpp 的 switch 分支可确认每个说明符的精确行为说明符含义输出范围源码行为%f微秒000000–999999以 6 位宽度、左补零输出微秒部分std::setw(6)%H小时24 小时制00–23以 2 位宽度、左补零输出小时%h小时12 小时制01–12(hours % 12) 0 ? 12 : (hours % 12)即 0 点与 12 点均显示为 12%i分钟00–59以 2 位宽度、左补零输出分钟%S/%s秒00–59两个说明符等价均以 2 位宽度输出秒%p上下午标识AM / PM小时 12输出AM否则输出PM注意官方文档中对%h的描述写为 Hour (00 to 12)而当前仓库源码的实际实现为 12 小时制显示01–12其中 0 点被显示为 12这一点以源码实现为准。普通字符非%开头会被原样复制到结果中%与空格、冒号等字符组合时空格与冒号照常输出。另外%后跟随的字符若不在上述 7 个说明符之内则会按%加该字符的形式原样保留见default分支例如%Y会输出字面量%Y——这与date_format等函数的行为不同使用时应特别注意。四、使用示例4.1 官方文档示例文档给出的经典示例mysql SELECT TIME_FORMAT(19:30:10, %h %i %s %p); ---------------------------------------- | time_format(19:30:10, %h %i %s %p) | ---------------------------------------- | 12 00 00 AM | ---------------------------------------- 1 row in set (0.01 sec)需要说明的是该示例输出为历史文档记录。对照当前仓库实现输入19:30:10经to_timestamp拆分为hours19, minutes30, seconds10后%h应输出0719 % 12%p因19 12应输出PM即当前实现下该查询实际返回07 30 10 PM。若想验证可直接在 mysql 客户端中执行查询并与输出比对。4.2 更多实战示例基于源码中 time_functions_test.cpp 的测试用例可以确认以下行为-- 24 小时制完整时间输出 14:30:40 SELECT TIME_FORMAT(14:30:40, %H:%i:%S); -- 仅取时分输出 14:30 SELECT TIME_FORMAT(14:30:40, %H:%i); -- 模板中混入普通文本输出 Time: 14:30 SELECT TIME_FORMAT(14:30:40, Time: %H:%i); -- 仅取小时输出 14 SELECT TIME_FORMAT(14:30:40, %H); -- 12 小时制加 AM/PM输出 02:30:40 PM SELECT TIME_FORMAT(14:30:40, %h:%i:%s %p);上述行为均有 BE 端单元测试覆盖测试构造TimestampValue::create(0, 0, 0, 14, 30, 40)表示14:30:40分别以%H:%i:%S、%H:%i、Time: %H:%i、%H四种模板验证输出并断言了14:30:40、14:30、Time: 14:30、14四个正确结果。五、源码级实现解析TimeFunctions::time_format是典型的向量化执行路径实现time_functions.cpp 的完整处理流程如下参数校验要求恰好传入 2 个参数否则返回Status::InvalidArgument空值短路若整列全为 NULL直接返回空列逐行处理时任一参数为 NULL 则该行结果为 NULLbuilder.append_null()类型视图通过ColumnViewerTYPE_TIME与ColumnViewerTYPE_VARCHAR分别读取 TIME 列与格式串列字段拆分将 TIME 值转换为TimestampValue后调用to_timestamp一次性拆出年、月、日、时、分、秒、微秒共 7 个字段模板解析逐字符扫描格式串遇到%后读取下一个字符进入 switch 分支按前文表格渲染对应字段普通字符直接写入结果结果构建使用ColumnBuilderTYPE_VARCHAR构建输出列并通过ColumnHelper::is_all_const(columns)保留常量列优化能力。TIME 值的内部表示值得注意从 time_functions.cpp 中MAX_TIME 3023999L与sec_to_time的限幅逻辑可以推断TIME 类型在内部以自00:00:00起经过的秒数双精度可带小数微秒存储并允许超过 24 小时乃至负值范围约为 ±838:59:59。因此TIME_FORMAT对超过 24 小时的时间值%H会按实际小时数输出如30:15:00的%H为30%p则仍按 24 小时制整点判定 AM/PM。六、边界行为与注意事项NULL 传播time或format任一为 NULL结果为 NULL未知说明符原样保留%后跟不支持字符如%Y、%m时不会报错而是输出字面量%Y。因为 TIME 类型不含年月日信息模板中不应使用日期类说明符结尾孤立%格式串以%结尾时函数会输出单个%字符源码中if (in_format) result %;分支12 小时制特例%h在 0 点与 12 点时均输出12区分大小写%H24 小时制与%h12 小时制、%S与%s均大小写敏感但语义分列%i与%I不同——%I不在支持列表内会原样输出返回值类型始终返回 VARCHAR可与CONCAT、CASE WHEN等表达式组合使用。七、与同类函数的区别TIME_FORMAT与datetime_format声明于 time_functions.cpp容易混淆区别如下函数输入类型输出语义TIME_FORMATTIME仅格式化时分秒/微秒部分支持%f %H %h %i %p %S %sdatetime_formatDATETIME格式化完整日期时间支持%Y %m %d等日期说明符若你的数据列是 DATETIME 类型但只需展示时间部分可先用CAST或相应时间截取函数将其转为 TIME 后再调用TIME_FORMAT。八、参考与验证函数文档docs/en/sql-reference/sql-functions/date-time-functions/time_format.mdBE 端实现be/src/exprs/time_functions.cpp单元测试be/test/exprs/time_functions_test.cppFE 端函数注册fe/fe-core/src/main/java/com/starrocks/catalog/FunctionSet.java在本地开发环境运行./run-be-ut.sh或执行TimeFunctionsTest中time_format相关用例即可复现本文引用的全部格式化行为作为线上 SQL 编写时的可靠参照。【免费下载链接】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），仅供参考