StarRocks microseconds_add 微秒级时间加法函数详解语法、参数、示例与底层实现【免费下载链接】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/starrocksmicroseconds_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)参数类型说明expr1DATETIME基准时间表达式必须为 DATETIME 类型expr2INT要添加的时间间隔单位为微秒必须为 INT 类型参数要点expr1不仅接受完整的 DATETIME 字面量如2010-11-30 23:50:50也接受 DATE 类型的字面量如2010-11-30expr2为有符号整数传入负值等同于执行减法与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.addUNIT(count); }即microseconds_add(expr1, expr2)最终等价于TimestampValue::addTimeUnit::MICROSECOND(expr1, expr2)由时间值类型内部的add模板负责完成微秒累加与跨单位进位。同一文件中还定义了MICROSECONDS_PER_SECOND 1000000LL等常量及normalize_microseconds辅助逻辑用于处理微秒部分溢出≥1,000,000 时进位为秒或为负向秒借位的规范化运算。这也解释了为何传入超过 1,000,000 的偏移量仍能得到正确结果。相关函数该函数族在 date-time-functions 目录下成对出现常用搭配如下microseconds_sub与microseconds_add语义相反从时间值中减去微秒间隔语法与返回类型完全一致详见 microseconds_sub.mdmillis_add / millis_sub毫秒级加减函数精度为10⁻³秒seconds_add / seconds_sub秒级加减函数date_add / date_sub按天为单位进行日期加减。选择哪个函数取决于业务所需的精度普通日志与报表使用秒或毫秒即可而涉及亚毫秒时间差、高频采样对齐、微秒级时间戳校验的场景则应使用microseconds_add/microseconds_sub。注意事项expr2必须为 INT 类型超大偏移量需拆分为多次计算或改用其他时间单位函数避免超出 INT 表示范围函数对传入的 DATE 字面量会隐式补齐00:00:00如需保留原日期语义建议显式使用 DATETIME 字面量返回结果始终为 DATETIME比较运算时注意与其他时间函数的精度对齐微秒位占 6 位小数避免在毫秒级数据上误用微秒偏移该函数在 BE 端由统一的时间计算框架生成性能与同族函数一致可直接在 WHERE 条件、投影列与 JOIN 关联键中使用。【免费下载链接】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），仅供参考
StarRocks microseconds_add 微秒级时间加法函数详解：语法、参数、示例与底层实现
StarRocks microseconds_add 微秒级时间加法函数详解语法、参数、示例与底层实现【免费下载链接】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/starrocksmicroseconds_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)参数类型说明expr1DATETIME基准时间表达式必须为 DATETIME 类型expr2INT要添加的时间间隔单位为微秒必须为 INT 类型参数要点expr1不仅接受完整的 DATETIME 字面量如2010-11-30 23:50:50也接受 DATE 类型的字面量如2010-11-30expr2为有符号整数传入负值等同于执行减法与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.addUNIT(count); }即microseconds_add(expr1, expr2)最终等价于TimestampValue::addTimeUnit::MICROSECOND(expr1, expr2)由时间值类型内部的add模板负责完成微秒累加与跨单位进位。同一文件中还定义了MICROSECONDS_PER_SECOND 1000000LL等常量及normalize_microseconds辅助逻辑用于处理微秒部分溢出≥1,000,000 时进位为秒或为负向秒借位的规范化运算。这也解释了为何传入超过 1,000,000 的偏移量仍能得到正确结果。相关函数该函数族在 date-time-functions 目录下成对出现常用搭配如下microseconds_sub与microseconds_add语义相反从时间值中减去微秒间隔语法与返回类型完全一致详见 microseconds_sub.mdmillis_add / millis_sub毫秒级加减函数精度为10⁻³秒seconds_add / seconds_sub秒级加减函数date_add / date_sub按天为单位进行日期加减。选择哪个函数取决于业务所需的精度普通日志与报表使用秒或毫秒即可而涉及亚毫秒时间差、高频采样对齐、微秒级时间戳校验的场景则应使用microseconds_add/microseconds_sub。注意事项expr2必须为 INT 类型超大偏移量需拆分为多次计算或改用其他时间单位函数避免超出 INT 表示范围函数对传入的 DATE 字面量会隐式补齐00:00:00如需保留原日期语义建议显式使用 DATETIME 字面量返回结果始终为 DATETIME比较运算时注意与其他时间函数的精度对齐微秒位占 6 位小数避免在毫秒级数据上误用微秒偏移该函数在 BE 端由统一的时间计算框架生成性能与同族函数一致可直接在 WHERE 条件、投影列与 JOIN 关联键中使用。【免费下载链接】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），仅供参考
