大网数据广告活动
数据库部署与 SQL 参考

Apache Doris 中文参考:TIMESTAMPTZ

· 52CE 我爱测

在不同数据库系统中,带时区的时间戳类型有多种命名方式: - PostgreSQL 和 Oracle 使用 TIMESTAMP WITH TIME ZONE - SQL Server 使用 DATETIMEOFFSET - 其他一些数据库使用 TIMESTAMP WITH LOCAL TIME ZONE

描述

TIMESTAMPTZ 是 Doris 中用于存储带时区信息的日期时间数据类型,对应于标准 SQL 中的 TIMESTAMP WITH TIME ZONE。

在不同数据库系统中,带时区的时间戳类型有多种命名方式:

  • PostgreSQL 和 Oracle 使用 TIMESTAMP WITH TIME ZONE
  • SQL Server 使用 DATETIMEOFFSET
  • 其他一些数据库使用 TIMESTAMP WITH LOCAL TIME ZONE

根据 SQL 标准,单独的 TIMESTAMP 类型不应携带时区信息(等同于 TIMESTAMP WITHOUT TIME ZONE)。考虑到用户习惯和使用便捷性,Doris 选择使用 TIMESTAMPTZ 这个更加简洁的命名来表示带时区的时间戳类型。Doris 没有单独的 TIMESTAMP 类型:不带时区且需要较大日期范围时使用 DATETIME,需要固定纳秒精度时使用 TIMESTAMP_NS。

TIMESTAMPTZ 的取值范围与 DATETIME 相同,为 [0000-01-01 00:00:00.000000, 9999-12-31 23:59:59.999999]。 TIMESTAMPTZ 支持指定精度,格式为 TIMESTAMPTZ(p),其中 p 表示精度,取值范围为 [0, 6],默认值为 0。换句话说,TIMESTAMPTZ 等同于 TIMESTAMPTZ(0)。 默认输出格式为 'yyyy-MM-dd HH:mm:ss.SSSSSS+XX:XX',其中 +XX:XX 表示时区偏移量(注意,SSSSSS 的位数由精度 p 决定)。

TIMESTAMPTZ 类型可以作为主键、分区列、分桶列。

工作原理

TIMESTAMPTZ 的实现并非在每行数据中单独存储时区信息,而是采用以下机制:

  1. 存储时:将输入的时间值统一转换为 UTC(世界协调时间)存储。
  2. 查询时:根据会话的时区设置(通过 time_zone 变量指定),将 UTC 时间自动转换为相应时区的时间进行展示。

因此,TIMESTAMPTZ 可以理解为一个带有时区转换功能的 DATETIME 类型,Doris 在内部自动完成时区的转换处理。

时区处理规则

  • 当输入字符串包含时区信息(如 "2020-01-01 00:00:00+03:00")时,Doris 会使用该时区信息进行转换。
  • 当输入字符串不包含时区信息(如 "2020-01-01 00:00:00")时,Doris 会使用当前会话的时区设置进行转换。

自 4.1.5 版本起,历史 IANA 时区若含秒级偏移,输出会保留为 +HH:MM:SS,而不丢弃偏移秒数。输入时间戳中的数字偏移与会话固定偏移是不同约束:输入偏移的小时小于 24、分和秒小于 60;会话固定偏移仍限制在 -12:00 至 +14:00。转换到会话时区后,若本地年份超出 0 至 9999 会报错。

自 4.1.5 版本起,Catalog 的外部带时区时间类型固定映射为 TIMESTAMPTZ,兼容标记 enable.mapping.timestamp_tz=false 不能恢复旧的 DATETIME 映射。Arrow Flight SQL 使用带时区注解的 Arrow Timestamp 传输时间点,查询 Schema 采用会话时区(Z 规范化为 UTC),DATETIME 则使用无时区 Timestamp。

存储与使用

在 Doris 中,一个 TIMESTAMPTZ 类型字段占用 8 字节存储空间。

TIMESTAMPTZ 支持与 DATETIME 和 TIMESTAMP_NS 相互转换,转换过程中会根据时区进行适当调整。TIMESTAMP_NS 转换为 TIMESTAMPTZ 时,会从纳秒精度四舍五入到目标 TIMESTAMPTZ 精度。

举例

-- 使用当前时区(假设为 +08:00)转换没有时区信息的时间字符串
select cast("2020-01-01 00:00:00" as timestamptz);
+--------------------------------------------+
| cast("2020-01-01 00:00:00" as timestamptz) |
+--------------------------------------------+
| 2020-01-01 00:00:00+08:00                  |
+--------------------------------------------+
-- TIMESTAMPTZ 可以支持微秒
select cast("2020-01-01 00:00:00.123456" as timestamptz(5));
+------------------------------------------------------+
| cast("2020-01-01 00:00:00.123456" as timestamptz(5)) |
+------------------------------------------------------+
| 2020-01-01 00:00:00.12345+08:00                      |
+------------------------------------------------------+
-- 使用带有时区信息的时间字符串
select cast("2020-01-01 00:00:00 +03:00" as timestamptz);
+---------------------------------------------------+
| cast("2020-01-01 00:00:00 +03:00" as timestamptz) |
+---------------------------------------------------+
| 2020-01-01 05:00:00 +08:00                        |
+---------------------------------------------------+
-- TIMESTAMPTZ 转换为 DATETIME(会根据当前时区进行转换)
select cast(cast("2020-01-01 00:00:00 +03:00" as timestamptz) as datetime);
+---------------------------------------------------------------------+
| cast(cast("2020-01-01 00:00:00 +03:00" as timestamptz) as datetime) |
+---------------------------------------------------------------------+
| 2020-01-01 05:00:00                                                 |
+---------------------------------------------------------------------+
-- 将 DATETIME 转换为 TIMESTAMPTZ
select cast(cast('2023-01-02 01:00:00' as datetime) as timestamptz);
+--------------------------------------------------------------+
| cast(cast('2023-01-02 01:00:00' as datetime) as timestamptz) |
+--------------------------------------------------------------+
| 2023-01-02 01:00:00 +08:00                                   |
+--------------------------------------------------------------+
-- 在函数中使用 TIMESTAMPTZ
select HOUR(cast("2020-01-01 00:00:00 +03:00" as timestamptz));
+---------------------------------------------------------+
| HOUR(cast("2020-01-01 00:00:00 +03:00" as timestamptz)) |
+---------------------------------------------------------+
|                                                       5 |
+---------------------------------------------------------+

本文来自 Apache Doris 文档贡献者,按 Apache 2.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
Apache Doris 文档贡献者
适用范围
master 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
Apache 2.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。