TDengine 时区配置问题全解

TDengine 时区配置问题全解

本文旨在彻底解决用户在使用 TDengine 时，遇到数据时间戳与预期不符的问题。

典型问题

为什么查询出来的数据时间戳差了 X 小时？
为什么查询 A 时间范围的数据，但结果中有些时间戳超出了 A 范围？
这是不是 TDengine 查询的 bug？

答案：不是 bug，而是时区配置问题。

在同一时刻，不同用户因时区配置不同，得到的时间戳可能不同。正确配置时区参数，是使用时序数据库必须掌握的知识。

TDengine TSDB 的连接方式

TDengine 支持三类连接方式：

原生连接
Websocket 连接
REST 连接

推荐：优先使用 Websocket 连接。

Websocket 兼具高性能和便捷性（升级数据库时无需升级客户端）。

新版本 Websocket 连接的时区配置

近期各语言连接器已统一 Websocket 时区配置方式，支持在连接层面设置时区，影响 SQL 时间字符串、查询结果集和订阅数据中的时间类型数据。

连接器类型	版本号
Python(taos-ws-py)	0.6.1
C/C++	3.3.7.1
Java	3.7.1
Go	3.7.4
NodeJs	3.1.9
Rust	0.13.0
C#	3.1.8

具体写法参考官方连接器文档。
再次提示：官方建议使用 Websocket 方式。

旧版本时区处理逻辑

SQL 输入时区：由数据库客户端（taosc）根据 taos.cfg 的 timezone 参数进行转换，转为 UTC/Unix 时间戳后交给服务端。如果未指定，则默认用应用服务器时区。
- 例如：insert into t1 values ("2025-01-13 08:06:34.630",3);
  若 taos.cfg 配置为东八区，实际写入服务端时间为 UTC 的 "2025-01-13 00:06:34.630"。
查询结果时区：服务端返回 UTC 时间戳，客户端连接器根据自身配置将数据转换为目标时区。

这种输入和输出分别处理时区的机制，方便跨时区业务场景的灵活应用。

SQL 时区配置方式

在 taos.cfg 文件中设置 timezone 参数。-
也可直接在 SQL 语句中使用 Unix 时间戳或 RFC 3339/ISO-8601 格式（如 2013-04-12T15:52:01.123+08:00），显式声明时区。

各连接器/工具的时区处理逻辑

连接方式	原生连接	Websocket	REST
Java	可在 URL 指定 timezone，默认等于 JVM 时区	可在 URL 指定 timezone，默认等于 JVM 时区	固定等于 JVM 时区
Go	默认等于服务器时区	默认等于服务器时区	固定返回 UTC 时区
C/C++	可在 taos_options/taos_options_connections 指定时区，默认服务器时区	同左	不支持 REST
Python	可在 connect 指定 timezone，默认服务器时区	同左	可在 RestClient 指定 timezone，默认服务器时区
Rust	默认服务器时区（需自行处理）	同左	不支持 REST
Node.js	不支持原生连接	固定返回 UTC 时区	不支持 REST
C#	通过 ConnectionStringBuilder 设置 timezone，默认服务器时区	同左	不支持 REST
REST API	-	-	URL 中指定 tz 参数
ODBC	固定返回 UTC 时区	固定返回 UTC 时区	不支持 REST
第三方应用	参考对应语言/连接方式	参考对应语言/连接方式	参考对应语言/连接方式

具体写法请参考官方文档。

结论与建议

强烈推荐使用 Websocket 连接方式。
新版连接器支持在连接层面统一配置时区，使用更简单。
旧版需关注 taos.cfg 和连接器配置的时区处理逻辑。
如需精确控制时间戳，建议直接使用 Unix 时间戳或带时区的时间字符串。

正确配置时区参数，可彻底解决 TDengine 查询结果时间戳与预期不符的问题。

关于 TDengine

TDengine 专为物联网IoT平台、工业大数据平台设计。其中，TDengine TSDB 是一款高性能、分布式的时序数据库（Time Series Database），同时它还带有内建的缓存、流式计算、数据订阅等系统功能；TDengine IDMP 是一款AI原生工业数据管理平台，它通过树状层次结构建立数据目录，对数据进行标准化、情景化，并通过 AI 提供实时分析、可视化、事件管理与报警等功能。