From a90ba6a991f3115596e304e23750a475b6990fd2 Mon Sep 17 00:00:00 2001 From: Cao Yu <2320485192@qq.com> Date: Tue, 18 Aug 2026 09:35:31 +0800 Subject: [PATCH 1/2] [docs](function) add timezone_hour and timezone_minute function docs --- .../date-time-functions/timezone-hour.md | 61 +++++++++++++++++++ .../date-time-functions/timezone-minute.md | 61 +++++++++++++++++++ .../date-time-functions/timezone-hour.md | 61 +++++++++++++++++++ .../date-time-functions/timezone-minute.md | 61 +++++++++++++++++++ sidebars.ts | 2 + 5 files changed, 246 insertions(+) create mode 100644 docs/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-hour.md create mode 100644 docs/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-minute.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-hour.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-minute.md diff --git a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-hour.md b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-hour.md new file mode 100644 index 0000000000000..58a63198058a9 --- /dev/null +++ b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-hour.md @@ -0,0 +1,61 @@ +--- +{ + "title": "TIMEZONE_HOUR", + "language": "en", + "description": "Returns the hour part of the time zone offset of a TIMESTAMPTZ value, calculated with respect to the session time zone" +} +--- + +## Description + +Returns the hour part of the time zone offset of the given `TIMESTAMPTZ` value. The offset is calculated between the UTC time and the session time zone at the instant represented by the value, and is negative for time zones west of UTC. + +This function is consistent with the [timezone_hour](https://trino.io/docs/current/functions/datetime.html#timezone_hour) function in Trino, except that a `TIMESTAMPTZ` value in Doris does not carry a time zone, so the session time zone is used. For the `TIMESTAMPTZ` data type, please refer to [TIMESTAMPTZ](../../../../sql-manual/basic-element/sql-data-types/date-time/TIMESTAMPTZ). For time zone settings, please refer to [Time Zone Management](../../../../admin-manual/cluster-management/time-zone). + +## Syntax + +```sql +TIMEZONE_HOUR() +``` + +## Parameters + +| Parameter | Description | +| -- | -- | +| `` | The `TIMESTAMPTZ` value whose time zone offset hour is to be returned | + +## Return Value + +Returns the hour part of the time zone offset as a value of type `BIGINT`. The offset is computed in the session time zone at the instant represented by the value. + +- If the parameter is NULL, returns NULL. + +## Example + +```sql +-- The Asia/Shanghai time zone is UTC+8 +mysql> SET time_zone = '+08:00'; +mysql> SELECT timezone_hour(CAST('2024-01-15 12:00:00' AS TIMESTAMPTZ)); ++-------------------------------------------------------------+ +| timezone_hour(CAST('2024-01-15 12:00:00' AS TIMESTAMPTZ)) | ++-------------------------------------------------------------+ +| 8 | ++-------------------------------------------------------------+ + +-- During daylight saving time, the offset of America/New_York is UTC-4 +mysql> SET time_zone = 'America/New_York'; +mysql> SELECT timezone_hour(CAST('2024-07-01 12:00:00' AS TIMESTAMPTZ)); ++-------------------------------------------------------------+ +| timezone_hour(CAST('2024-07-01 12:00:00' AS TIMESTAMPTZ)) | ++-------------------------------------------------------------+ +| -4 | ++-------------------------------------------------------------+ + +-- When the input is NULL, returns NULL +mysql> SELECT timezone_hour(CAST(NULL AS TIMESTAMPTZ)); ++------------------------------------------+ +| timezone_hour(CAST(NULL AS TIMESTAMPTZ)) | ++------------------------------------------+ +| NULL | ++------------------------------------------+ +``` diff --git a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-minute.md b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-minute.md new file mode 100644 index 0000000000000..d8709225cdc45 --- /dev/null +++ b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-minute.md @@ -0,0 +1,61 @@ +--- +{ + "title": "TIMEZONE_MINUTE", + "language": "en", + "description": "Returns the minute part of the time zone offset of a TIMESTAMPTZ value, calculated with respect to the session time zone" +} +--- + +## Description + +Returns the minute part of the time zone offset of the given `TIMESTAMPTZ` value. The offset is calculated between the UTC time and the session time zone at the instant represented by the value, and is negative for time zones west of UTC. + +This function is consistent with the [timezone_minute](https://trino.io/docs/current/functions/datetime.html#timezone_minute) function in Trino, except that a `TIMESTAMPTZ` value in Doris does not carry a time zone, so the session time zone is used. For the `TIMESTAMPTZ` data type, please refer to [TIMESTAMPTZ](../../../../sql-manual/basic-element/sql-data-types/date-time/TIMESTAMPTZ). For time zone settings, please refer to [Time Zone Management](../../../../admin-manual/cluster-management/time-zone). + +## Syntax + +```sql +TIMEZONE_MINUTE() +``` + +## Parameters + +| Parameter | Description | +| -- | -- | +| `` | The `TIMESTAMPTZ` value whose time zone offset minute is to be returned | + +## Return Value + +Returns the minute part of the time zone offset as a value of type `BIGINT`. The offset is computed in the session time zone at the instant represented by the value. For time zones with a whole-hour offset, the returned value is 0. + +- If the parameter is NULL, returns NULL. + +## Example + +```sql +-- The Asia/Shanghai time zone is UTC+8, so the minute part is 0 +mysql> SET time_zone = '+08:00'; +mysql> SELECT timezone_minute(CAST('2024-01-15 12:00:00' AS TIMESTAMPTZ)); ++---------------------------------------------------------------+ +| timezone_minute(CAST('2024-01-15 12:00:00' AS TIMESTAMPTZ)) | ++---------------------------------------------------------------+ +| 0 | ++---------------------------------------------------------------+ + +-- The offset of Asia/Kathmandu is UTC+05:45, so the minute part is 45 +mysql> SET time_zone = 'Asia/Kathmandu'; +mysql> SELECT timezone_minute(CAST('2024-01-15 12:00:00' AS TIMESTAMPTZ)); ++---------------------------------------------------------------+ +| timezone_minute(CAST('2024-01-15 12:00:00' AS TIMESTAMPTZ)) | ++---------------------------------------------------------------+ +| 45 | ++---------------------------------------------------------------+ + +-- When the input is NULL, returns NULL +mysql> SELECT timezone_minute(CAST(NULL AS TIMESTAMPTZ)); ++--------------------------------------------+ +| timezone_minute(CAST(NULL AS TIMESTAMPTZ)) | ++--------------------------------------------+ +| NULL | ++--------------------------------------------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-hour.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-hour.md new file mode 100644 index 0000000000000..0df6cf31fdb75 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-hour.md @@ -0,0 +1,61 @@ +--- +{ + "title": "TIMEZONE_HOUR", + "language": "zh-CN", + "description": "返回 TIMESTAMPTZ 值在会话时区下时区偏移的小时部分" +} +--- + +## 描述 + +返回给定 `TIMESTAMPTZ` 值在会话时区下的时区偏移的小时部分。偏移量以该值所代表的时刻为基准，在 UTC 时间与会话时区之间计算，UTC 以西的时区偏移为负数。 + +该函数与 Trino 中的 [timezone_hour](https://trino.io/docs/current/functions/datetime.html#timezone_hour) 函数保持一致，但 Doris 中的 `TIMESTAMPTZ` 值本身不携带时区信息，因此使用会话时区。关于 `TIMESTAMPTZ` 数据类型，请参考 [TIMESTAMPTZ](../../../../sql-manual/basic-element/sql-data-types/date-time/TIMESTAMPTZ)。关于时区设置，请参考 [时区管理](../../../../admin-manual/cluster-management/time-zone)。 + +## 语法 + +```sql +TIMEZONE_HOUR() +``` + +## 参数 + +| 参数 | 说明 | +| -- | -- | +| `` | 需要返回时区偏移小时的 `TIMESTAMPTZ` 值 | + +## 返回值 + +返回 `BIGINT` 类型的时区偏移的小时部分。偏移量以该值所代表的时刻为基准在会话时区下计算。 + +- 如果参数为 NULL，返回 NULL。 + +## 示例 + +```sql +-- Asia/Shanghai 时区为 UTC+8 +mysql> SET time_zone = '+08:00'; +mysql> SELECT timezone_hour(CAST('2024-01-15 12:00:00' AS TIMESTAMPTZ)); ++-------------------------------------------------------------+ +| timezone_hour(CAST('2024-01-15 12:00:00' AS TIMESTAMPTZ)) | ++-------------------------------------------------------------+ +| 8 | ++-------------------------------------------------------------+ + +-- 夏令时期间，America/New_York 的偏移为 UTC-4 +mysql> SET time_zone = 'America/New_York'; +mysql> SELECT timezone_hour(CAST('2024-07-01 12:00:00' AS TIMESTAMPTZ)); ++-------------------------------------------------------------+ +| timezone_hour(CAST('2024-07-01 12:00:00' AS TIMESTAMPTZ)) | ++-------------------------------------------------------------+ +| -4 | ++-------------------------------------------------------------+ + +-- 当输入为 NULL 时，返回 NULL +mysql> SELECT timezone_hour(CAST(NULL AS TIMESTAMPTZ)); ++------------------------------------------+ +| timezone_hour(CAST(NULL AS TIMESTAMPTZ)) | ++------------------------------------------+ +| NULL | ++------------------------------------------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-minute.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-minute.md new file mode 100644 index 0000000000000..ea4e9e3c6a59a --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-minute.md @@ -0,0 +1,61 @@ +--- +{ + "title": "TIMEZONE_MINUTE", + "language": "zh-CN", + "description": "返回 TIMESTAMPTZ 值在会话时区下时区偏移的分钟部分" +} +--- + +## 描述 + +返回给定 `TIMESTAMPTZ` 值在会话时区下的时区偏移的分钟部分。偏移量以该值所代表的时刻为基准，在 UTC 时间与会话时区之间计算，UTC 以西的时区偏移为负数。 + +该函数与 Trino 中的 [timezone_minute](https://trino.io/docs/current/functions/datetime.html#timezone_minute) 函数保持一致，但 Doris 中的 `TIMESTAMPTZ` 值本身不携带时区信息，因此使用会话时区。关于 `TIMESTAMPTZ` 数据类型，请参考 [TIMESTAMPTZ](../../../../sql-manual/basic-element/sql-data-types/date-time/TIMESTAMPTZ)。关于时区设置，请参考 [时区管理](../../../../admin-manual/cluster-management/time-zone)。 + +## 语法 + +```sql +TIMEZONE_MINUTE() +``` + +## 参数 + +| 参数 | 说明 | +| -- | -- | +| `` | 需要返回时区偏移分钟的 `TIMESTAMPTZ` 值 | + +## 返回值 + +返回 `BIGINT` 类型的时区偏移的分钟部分。偏移量以该值所代表的时刻为基准在会话时区下计算。对于整小时偏移的时区，返回值为 0。 + +- 如果参数为 NULL，返回 NULL。 + +## 示例 + +```sql +-- Asia/Shanghai 时区为 UTC+8，因此分钟部分为 0 +mysql> SET time_zone = '+08:00'; +mysql> SELECT timezone_minute(CAST('2024-01-15 12:00:00' AS TIMESTAMPTZ)); ++---------------------------------------------------------------+ +| timezone_minute(CAST('2024-01-15 12:00:00' AS TIMESTAMPTZ)) | ++---------------------------------------------------------------+ +| 0 | ++---------------------------------------------------------------+ + +-- Asia/Kathmandu 的偏移为 UTC+05:45，因此分钟部分为 45 +mysql> SET time_zone = 'Asia/Kathmandu'; +mysql> SELECT timezone_minute(CAST('2024-01-15 12:00:00' AS TIMESTAMPTZ)); ++---------------------------------------------------------------+ +| timezone_minute(CAST('2024-01-15 12:00:00' AS TIMESTAMPTZ)) | ++---------------------------------------------------------------+ +| 45 | ++---------------------------------------------------------------+ + +-- 当输入为 NULL 时，返回 NULL +mysql> SELECT timezone_minute(CAST(NULL AS TIMESTAMPTZ)); ++--------------------------------------------+ +| timezone_minute(CAST(NULL AS TIMESTAMPTZ)) | ++--------------------------------------------+ +| NULL | ++--------------------------------------------+ +``` diff --git a/sidebars.ts b/sidebars.ts index 0405755dc0107..0b02a1636153b 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -1643,6 +1643,8 @@ const sidebars: SidebarsConfig = { 'sql-manual/sql-functions/scalar-functions/date-time-functions/timediff', "sql-manual/sql-functions/scalar-functions/date-time-functions/time-format", 'sql-manual/sql-functions/scalar-functions/date-time-functions/time-to-sec', + 'sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-hour', + 'sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-minute', 'sql-manual/sql-functions/scalar-functions/date-time-functions/to-date', 'sql-manual/sql-functions/scalar-functions/date-time-functions/to-days', 'sql-manual/sql-functions/scalar-functions/date-time-functions/to-iso8601', From 24bb93798b7a3c72da84bfdb13121229e69f52c3 Mon Sep 17 00:00:00 2001 From: Cao Yu <2320485192@qq.com> Date: Tue, 18 Aug 2026 17:52:35 +0800 Subject: [PATCH 2/2] [docs](function) clarify session-timezone semantics and add divergence examples for timezone_hour/timezone_minute --- .../date-time-functions/timezone-hour.md | 11 +++++++++++ .../date-time-functions/timezone-minute.md | 11 +++++++++++ .../date-time-functions/timezone-hour.md | 10 ++++++++++ .../date-time-functions/timezone-minute.md | 10 ++++++++++ 4 files changed, 42 insertions(+) diff --git a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-hour.md b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-hour.md index 58a63198058a9..e78239fc042de 100644 --- a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-hour.md +++ b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-hour.md @@ -51,6 +51,17 @@ mysql> SELECT timezone_hour(CAST('2024-07-01 12:00:00' AS TIMESTAMPTZ)); | -4 | +-------------------------------------------------------------+ +-- A TIMESTAMPTZ value stores only the UTC instant, not the input zone, so +-- even when the input carries '-04:30', the returned offset is the session +-- time zone's offset. Trino would return -4 for this input. +mysql> SET time_zone = '+08:00'; +mysql> SELECT timezone_hour(CAST('2024-01-15 12:00:00-04:30' AS TIMESTAMPTZ)); ++--------------------------------------------------------------------+ +| timezone_hour(CAST('2024-01-15 12:00:00-04:30' AS TIMESTAMPTZ)) | ++--------------------------------------------------------------------+ +| 8 | ++--------------------------------------------------------------------+ + -- When the input is NULL, returns NULL mysql> SELECT timezone_hour(CAST(NULL AS TIMESTAMPTZ)); +------------------------------------------+ diff --git a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-minute.md b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-minute.md index d8709225cdc45..55830a2266109 100644 --- a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-minute.md +++ b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-minute.md @@ -51,6 +51,17 @@ mysql> SELECT timezone_minute(CAST('2024-01-15 12:00:00' AS TIMESTAMPTZ)); | 45 | +---------------------------------------------------------------+ +-- A TIMESTAMPTZ value stores only the UTC instant, not the input zone, so +-- even when the input carries '-04:30', the returned offset is the session +-- time zone's offset. Trino would return -30 for this input. +mysql> SET time_zone = '+08:00'; +mysql> SELECT timezone_minute(CAST('2024-01-15 12:00:00-04:30' AS TIMESTAMPTZ)); ++----------------------------------------------------------------------+ +| timezone_minute(CAST('2024-01-15 12:00:00-04:30' AS TIMESTAMPTZ)) | ++----------------------------------------------------------------------+ +| 0 | ++----------------------------------------------------------------------+ + -- When the input is NULL, returns NULL mysql> SELECT timezone_minute(CAST(NULL AS TIMESTAMPTZ)); +--------------------------------------------+ diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-hour.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-hour.md index 0df6cf31fdb75..7ccae5c2c2887 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-hour.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-hour.md @@ -51,6 +51,16 @@ mysql> SELECT timezone_hour(CAST('2024-07-01 12:00:00' AS TIMESTAMPTZ)); | -4 | +-------------------------------------------------------------+ +-- TIMESTAMPTZ 值只存储 UTC 时刻，不存储输入时区，因此即使输入携带 +-- '-04:30'，返回的仍是会话时区的偏移。Trino 对该输入会返回 -4。 +mysql> SET time_zone = '+08:00'; +mysql> SELECT timezone_hour(CAST('2024-01-15 12:00:00-04:30' AS TIMESTAMPTZ)); ++--------------------------------------------------------------------+ +| timezone_hour(CAST('2024-01-15 12:00:00-04:30' AS TIMESTAMPTZ)) | ++--------------------------------------------------------------------+ +| 8 | ++--------------------------------------------------------------------+ + -- 当输入为 NULL 时，返回 NULL mysql> SELECT timezone_hour(CAST(NULL AS TIMESTAMPTZ)); +------------------------------------------+ diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-minute.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-minute.md index ea4e9e3c6a59a..6d2a42bb7df06 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-minute.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/timezone-minute.md @@ -51,6 +51,16 @@ mysql> SELECT timezone_minute(CAST('2024-01-15 12:00:00' AS TIMESTAMPTZ)); | 45 | +---------------------------------------------------------------+ +-- TIMESTAMPTZ 值只存储 UTC 时刻，不存储输入时区，因此即使输入携带 +-- '-04:30'，返回的仍是会话时区的偏移。Trino 对该输入会返回 -30。 +mysql> SET time_zone = '+08:00'; +mysql> SELECT timezone_minute(CAST('2024-01-15 12:00:00-04:30' AS TIMESTAMPTZ)); ++----------------------------------------------------------------------+ +| timezone_minute(CAST('2024-01-15 12:00:00-04:30' AS TIMESTAMPTZ)) | ++----------------------------------------------------------------------+ +| 0 | ++----------------------------------------------------------------------+ + -- 当输入为 NULL 时，返回 NULL mysql> SELECT timezone_minute(CAST(NULL AS TIMESTAMPTZ)); +--------------------------------------------+