diff --git a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/utc-date.md b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/utc-date.md new file mode 100644 index 0000000000000..9093fde59e2ed --- /dev/null +++ b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/utc-date.md @@ -0,0 +1,36 @@ +--- +{ + "title": "UTC_DATE", + "language": "en" +} +--- + +## Description +The UTC_DATE function returns the current date in the UTC timezone. This function is not affected by the local timezone and always returns the current date based on the UTC timezone, ensuring date consistency across different timezone scenarios. + +This function behaves consistently with the [utc_date function](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_utc-date) in MySQL. + +## Syntax + +```sql +UTC_DATE() +``` + +## Return Value +Returns the current UTC date, with the type DATE. + +Return Date type (format: YYYY-MM-DD). When performing numerical operations on the returned results, a type conversion will be performed, returning an [integer format](https://doris.apache.org/docs/dev/sql-manual/basic-element/sql-data-types/conversion/int-conversion#from-date) (format: YYYYMMDD). + +## Examples + +```sql +-- Assume the current local time is UTC+8 2025-10-27 10:55:35 +SELECT UTC_DATE(), UTC_DATE() + 0; +``` +```text ++------------+----------------+ +| UTC_DATE() | UTC_DATE() + 0 | ++------------+----------------+ +| 2025-10-27 | 20251027 | ++------------+----------------+ +``` diff --git a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/utc-time.md b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/utc-time.md new file mode 100644 index 0000000000000..8e4588a109f66 --- /dev/null +++ b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/utc-time.md @@ -0,0 +1,52 @@ +--- +{ + "title": "UTC_TIME", + "language": "en" +} +--- + +## Description +The UTC_TIME function returns the current time in the UTC timezone. This function is not affected by the local timezone and always returns the current time based on the UTC timezone, ensuring time consistency across different timezone scenarios. + +This function behaves consistently with the [utc_time function](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_utc-time) in MySQL. + +## Syntax + +```sql +UTC_TIME([<`precision`>]) +``` + +## Parameters + +| Parameter | Description | +|-----------|-------------| +| `` | The precision of the returned time value supports integer types within the range [0, 6]. Only integer type constants are accepted.。 | + +## Return Value +Returns the current UTC time. + +Return Time type (format: HH:mm:ss). When using the returned result for numerical operations, it will be converted to [integer format](https://doris.apache.org/docs/dev/sql-manual/basic-element/sql-data-types/conversion/int-conversion#from--time) (the time value elapsed since 00:00:00, unit in microseconds). + +When the input is NULL or the precision is out of range, an error will be thrown. + +## Examples + +```sql +-- Assume the current local time is UTC+8 2025-10-27 14:39:01 +SELECT UTC_TIME(), UTC_TIME() + 1, UTC_TIME(6), UTC_TIME(6) + 1; +``` +```text +------------+----------------+-----------------+-----------------+ +| UTC_TIME() | UTC_TIME() + 1 | UTC_TIME(6) | UTC_TIME(6) + 1 | ++------------+----------------+-----------------+-----------------+ +| 06:39:01 | 23941000001 | 06:39:01.934119 | 23941934120 | ++------------+----------------+-----------------+-----------------+ +``` + +```sql +SELECT UTC_TIME(7); +-- ERROR 1105 (HY000): errCode = 2, detailMessage = scale must be between 0 and 6 + +SELECT UTC_TIME(NULL); +-- ERROR 1105 (HY000): errCode = 2, detailMessage = UTC_TIME argument cannot be NULL. +``` diff --git a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/utc-timestamp.md b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/utc-timestamp.md index 9aed31f689434..3348d01677048 100644 --- a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/utc-timestamp.md +++ b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/utc-timestamp.md @@ -13,20 +13,40 @@ This function behaves consistently with the [utc_timestamp function](https://dev ## Syntax ```sql -UTC_TIMESTAMP() +UTC_TIMESTAMP([``]) ``` +## Parameters + +| Parameter | Description | +|-----------|-------------| +| `` | The precision of the returned date-time value supports integer types within the range [0, 6]. Only integer type constants are accepted.。 | + ## Return Value -Returns the current UTC date and time, type DATETIME. +Returns the current UTC date and time. + +Returns DATETIME type (format: YYYY-MM-DD HH:mm:ss[.ssssss]). When using the returned result for numeric operations, it will be converted to the [integer format](https://doris.apache.org/docs/dev/sql-manual/basic-element/sql-data-types/conversion/int-conversion#from-datetime) (format YYYYMMDDHHmmss). + +When the input is NULL or the precision is out of range, an error will be thrown. ## Examples ```sql --- Current local time is UTC+8 2025-08-14 11:45:42 -SELECT UTC_TIMESTAMP() AS utc_str; -+---------------------+ -| utc_str | -+---------------------+ -| 2025-08-14 03:45:42 | -+---------------------+ +-- Current local time is UTC+8 2025-10-27 14:43:21 +SELECT UTC_TIMESTAMP(), UTC_TIMESTAMP() + 0, UTC_TIMESTAMP(5), UTC_TIMESTAMP(5) + 0; +``` +```text ++---------------------+---------------------+---------------------------+----------------------+ +| UTC_TIMESTAMP() | UTC_TIMESTAMP() + 0 | UTC_TIMESTAMP(5) | UTC_TIMESTAMP(5) + 0 | ++---------------------+---------------------+---------------------------+----------------------+ +| 2025-10-27 06:43:21 | 20251027064321 | 2025-10-27 06:43:21.88177 | 20251027064321 | ++---------------------+---------------------+---------------------------+----------------------+ +``` + +```sql +SELECT UTC_TIMESTAMP(7); +-- ERROR 1105 (HY000): errCode = 2, detailMessage = scale must be between 0 and 6 + +SELECT UTC_TIMESTAMP(NULL); +-- ERROR 1105 (HY000): errCode = 2, detailMessage = UTC_TIMESTAMP argument cannot be NULL. ``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/utc-date.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/utc-date.md new file mode 100644 index 0000000000000..2090e7e915e42 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/utc-date.md @@ -0,0 +1,37 @@ +--- +{ + "title": "UTC_DATE", + "language": "zh-CN" +} +--- + +## 描述 +UTC_DATE 函数用于返回当前 UTC 时区的日期。该函数不受本地时区影响，始终返回基于 UTC 时区的当前日期，确保跨时区场景下的日期一致性。 + +该函数与 mysql 中的 [utc_date 函数](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_utc-date) 行为一致。 + +## 语法 + +```sql +UTC_DATE() +``` + +## 返回值 +返回当前 UTC 日期。 + +返回 Date 类型（格式：YYYY-MM-DD）。当使用返回结果进行数值运算时，会进行类型转换，返回[整数格式](https://doris.apache.org/zh-CN/docs/dev/sql-manual/basic-element/sql-data-types/conversion/int-conversion#from-date)（格式: YYYYMMDD）。 + +## 举例 + +```sql +--- 假设当前地区时间为东八区 2025-10-27 10:55:35 +SELECT UTC_DATE(), UTC_DATE() + 0; +``` +```text ++------------+----------------+ +| UTC_DATE() | UTC_DATE() + 0 | ++------------+----------------+ +| 2025-10-27 | 20251027 | ++------------+----------------+ +``` + diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/utc-time.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/utc-time.md new file mode 100644 index 0000000000000..cd61f0dca525b --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/utc-time.md @@ -0,0 +1,53 @@ +--- +{ + "title": "UTC_TIME", + "language": "zh-CN" +} +--- + +## 描述 +UTC_TIME 函数用于返回当前 UTC 时区的时间。该函数不受本地时区影响，始终返回基于 UTC 时区的当前时间，确保跨时区场景下的时间一致性。 + +该函数与 mysql 中的 [utc_time 函数](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_utc-time) 行为一致。 + +## 语法 + +```sql +UTC_TIME([<`precision`>]) +``` + +## 参数 + +| 参数 | 描述 | +|----------------------------|-----------------------------| +| `` | 返回的时间值的精度，支持[0, 6]范围内的整数类型。仅接受整数类型常量。 | + +## 返回值 + +返回当前 UTC 时间。 + +返回 TIME 类型（格式：HH:mm:ss）。当使用返回结果进行数值运算时，会进行类型转换，返回[整数格式](https://doris.apache.org/zh-CN/docs/dev/sql-manual/basic-element/sql-data-types/conversion/int-conversion#from--time)（从 00:00:00 开始经过的时间值，单位为微秒）。 + +当输入为 NULL 或精度超出范围会报错。 + +## 举例 + +```sql +--- 假设当前地区时间为东八区 2025-10-27 14:39:01 +SELECT UTC_TIME(), UTC_TIME() + 1, UTC_TIME(6), UTC_TIME(6) + 1; +``` +```text +------------+----------------+-----------------+-----------------+ +| UTC_TIME() | UTC_TIME() + 1 | UTC_TIME(6) | UTC_TIME(6) + 1 | ++------------+----------------+-----------------+-----------------+ +| 06:39:01 | 23941000001 | 06:39:01.934119 | 23941934120 | ++------------+----------------+-----------------+-----------------+ +``` + +```sql +SELECT UTC_TIME(7); +-- ERROR 1105 (HY000): errCode = 2, detailMessage = scale must be between 0 and 6 + +SELECT UTC_TIME(NULL); +-- ERROR 1105 (HY000): errCode = 2, detailMessage = UTC_TIME argument cannot be NULL. +``` \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/utc-timestamp.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/utc-timestamp.md index 947aef5efbab4..89f9c5b5f07af 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/utc-timestamp.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/utc-timestamp.md @@ -13,22 +13,41 @@ UTC_TIMESTAMP 函数用于返回当前 UTC 时区在所的日期时间。该函 ## 语法 ```sql -UTC_TIMESTAMP() +UTC_TIMESTAMP([``]) ``` +## 参数 + +| 参数 | 描述 | +|----------------------------|-----------------------------| +| `` | 返回的时间值的精度，支持[0, 6]范围内的整数类型。仅接受整数类型常量。 | + ## 返回值 -返回当前 UTC 日期时间，类型为 DATETIME. +返回当前 UTC 日期时间. + +返回 DATETIME 类型（格式：YYYY-MM-DD HH:mm:ss[.ssssss]）。当使用返回结果进行数值运算时，会进行类型转换，返回[整数格式](https://doris.apache.org/zh-CN/docs/dev/sql-manual/basic-element/sql-data-types/conversion/int-conversion#from-datetime)（格式YYYYMMDDHHmmss）。 + +当输入为 NULL 或精度超出范围会报错。 ## 举例 ```sql +---当前地区时间为东八区 2025-10-27 14:43:21 +SELECT UTC_TIMESTAMP(), UTC_TIMESTAMP() + 0, UTC_TIMESTAMP(5), UTC_TIMESTAMP(5) + 0; +``` +```text ++---------------------+---------------------+---------------------------+----------------------+ +| UTC_TIMESTAMP() | UTC_TIMESTAMP() + 0 | UTC_TIMESTAMP(5) | UTC_TIMESTAMP(5) + 0 | ++---------------------+---------------------+---------------------------+----------------------+ +| 2025-10-27 06:43:21 | 20251027064321 | 2025-10-27 06:43:21.88177 | 20251027064321 | ++---------------------+---------------------+---------------------------+----------------------+ +``` + +```sql +SELECT UTC_TIMESTAMP(7); +-- ERROR 1105 (HY000): errCode = 2, detailMessage = scale must be between 0 and 6 ----当前地区时间为东八区 2025-08-14 11：45：42 -SELECT UTC_TIMESTAMP() AS utc_str; -+---------------------+ -| utc_str | -+---------------------+ -| 2025-08-14 03:45:42 | -+---------------------+ +SELECT UTC_TIMESTAMP(NULL); +-- ERROR 1105 (HY000): errCode = 2, detailMessage = UTC_TIMESTAMP argument cannot be NULL. ``` diff --git a/sidebars.json b/sidebars.json index 940fdcb441527..d0907342f2329 100644 --- a/sidebars.json +++ b/sidebars.json @@ -1419,6 +1419,8 @@ "sql-manual/sql-functions/scalar-functions/date-time-functions/to-days", "sql-manual/sql-functions/scalar-functions/date-time-functions/to-iso8601", "sql-manual/sql-functions/scalar-functions/date-time-functions/to-monday", + "sql-manual/sql-functions/scalar-functions/date-time-functions/utc-date", + "sql-manual/sql-functions/scalar-functions/date-time-functions/utc-time", "sql-manual/sql-functions/scalar-functions/date-time-functions/utc-timestamp", "sql-manual/sql-functions/scalar-functions/date-time-functions/unix-timestamp", "sql-manual/sql-functions/scalar-functions/date-time-functions/week",