StarRocks microseconds_add 微秒级时间加法函数详解：语法、参数、示例与底层实现-酒店常州论坛

StarRocks microseconds_add 微秒级时间加法函数详解：语法、参数、示例与底层实现

【免费下载链接】starrocksThe world's 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

microseconds_add是 StarRocks 提供的日期时间函数之一，用于在给定的日期时间值上增加一个以微秒（microsecond）为单位的时间间隔。在需要处理高精度时间戳、日志时间对齐、性能监控时间窗口计算等亚毫秒级场景中，它比基于秒或毫秒的函数更精准。阅读本篇后，你将掌握该函数的完整语法、参数约束、返回类型与边界行为，并能结合源码理解其底层实现原理与配套的microseconds_sub等姊妹函数。

函数概述

microseconds_add对日期时间值执行微秒级的加法运算，其时间单位精度为10⁻⁶秒（即 1/1,000,000 秒）。它适用于需要对 DATETIME 类型的值进行高精度偏移计算的场景，例如：

将监控采样点的时间戳向前平移数个微秒以对齐事件序列；
在毫秒级时间戳基础上追加微秒偏移量；
构造精确到微秒的边界时间用于区间查询。

从 StarRocks 的函数族来看，它属于一套以统一宏生成的时间加减函数（seconds_add/sub、millis_add/sub、micros_add/sub等）中的微秒档位，与毫秒级函数millis_add形成精度上的递进关系。

语法与参数说明

函数声明如下：

DATETIME microseconds_add(DATETIME expr1, INT expr2)

参数	类型	说明
`expr1`	DATETIME	基准时间表达式，必须为 DATETIME 类型
`expr2`	INT	要添加的时间间隔，单位为微秒，必须为 INT 类型

参数要点：

expr1不仅接受完整的 DATETIME 字面量（如'2010-11-30 23:50:50'），也接受 DATE 类型的字面量（如'2010-11-30'）；
expr2为有符号整数，传入负值等同于执行减法（与microseconds_sub效果等价）；
当expr2的绝对值超过 1,000,000（即 1 秒）时，函数会自动完成秒、分钟、小时等更高单位的进位或借位，无需预先拆分单位。

返回值与边界行为

该函数始终返回DATETIME 类型的值，精度可呈现到微秒（秒的小数部分占 6 位）。

DATE 输入的处理：当expr1为 DATE 类型时，其小时、分钟、秒部分会被视为00:00:00，即从当日零点开始计算偏移；
结果范围：返回结果仍为 DATETIME 类型，若相加后跨越午夜，日期部分会自动进位到次日（见下方microseconds_sub的借位示例）；
类型一致性：无论传入的是 DATE 还是 DATETIME，返回值统一为 DATETIME，便于后续参与时间比较与排序。

使用示例

以下示例完整复现自官方参考文档：

select microseconds_add('2010-11-30 23:50:50', 2); +--------------------------------------------+ | microseconds_add('2010-11-30 23:50:50', 2) | +--------------------------------------------+ | 2010-11-30 23:50:50.000002 | +--------------------------------------------+ 1 row in set (0.00 sec) select microseconds_add('2010-11-30', 2); +-----------------------------------+ | microseconds_add('2010-11-30', 2) | +-----------------------------------+ | 2010-11-30 00:00:00.000002 | +-----------------------------------+

扩展示例：

向时间值增加超过 1 秒的微秒偏移，观察自动进位：

select microseconds_add('2010-11-30 23:50:50', 1000001); +--------------------------------------------------+ | microseconds_add('2010-11-30 23:50:50', 1000001) | +--------------------------------------------------+ | 2010-11-30 23:50:51.000001 | +--------------------------------------------------+

传入负值实现等价减法：

select microseconds_add('2010-11-30 00:00:00.000002', -2); +-----------------------------------------------------+ | microseconds_add('2010-11-30 00:00:00.000002', -2) | +-----------------------------------------------------+ | 2010-11-30 00:00:00.000000 | +-----------------------------------------------------+

在真实表上结合列使用：

SELECT event_time, microseconds_add(event_time, 500000) AS shifted_time FROM events WHERE event_time >= '2024-01-01 00:00:00';

底层实现原理

microseconds_add并非独立手写的特殊函数，而是与microseconds_sub、millis_add/sub等同族函数由同一套宏模板在编译期生成。

前端（FE）注册：在 FunctionSet.java 中声明了常量MICROSECONDS_ADD = "microseconds_add"，用于函数名的统一管理与注册。

后端（BE）实现：在 time_functions.cpp 中，通过宏DEFINE_TIME_ADD_AND_SUB_FN(micros, TimeUnit::MICROSECOND)一次生成micros_add与micros_sub两个函数。其核心调用链为：

template <TimeUnit UNIT> TimestampValue timestamp_add(TimestampValue tsv, int count) { return tsv.add<UNIT>(count); }

即microseconds_add(expr1, expr2)最终等价于TimestampValue::add<TimeUnit::MICROSECOND>(expr1, expr2)，由时间值类型内部的add模板负责完成微秒累加与跨单位进位。同一文件中还定义了MICROSECONDS_PER_SECOND = 1000000LL等常量及normalize_microseconds辅助逻辑，用于处理微秒部分溢出（≥1,000,000 时进位为秒）或为负（向秒借位）的规范化运算。这也解释了为何传入超过 1,000,000 的偏移量仍能得到正确结果。

注意事项

expr2必须为 INT 类型，超大偏移量需拆分为多次计算或改用其他时间单位函数，避免超出 INT 表示范围；
函数对传入的 DATE 字面量会隐式补齐00:00:00，如需保留原日期语义，建议显式使用 DATETIME 字面量；
返回结果始终为 DATETIME，比较运算时注意与其他时间函数的精度对齐（微秒位占 6 位小数），避免在毫秒级数据上误用微秒偏移；
该函数在 BE 端由统一的时间计算框架生成，性能与同族函数一致，可直接在 WHERE 条件、投影列与 JOIN 关联键中使用。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析