小 T 导读：很多新用户在配置TDengine的时候，偶尔会因为配置了错误的时区（timezone），而导致写入和查询的时间出现错位。今天希望这篇文章，能将日期时间、时间戳以及TDengine在写入和查询时处理时区的行为等描述清楚。
TDengine是涛思数据专为物联网、车联网、工业互联网、IT运维等设计和优化的大数据平台，核心的时序数据库在处理时序数据上有着十分优异的性能。
一般来说，时序数据就是带有时间序列属性的数据。在处理时序数据时，TDengine有着自己独特的方式。但是如果你没有正确理解TDengine在写入和查询上的行为，极可能会因为配置了错误的时区（timezone），而导致写入和查询的时间出现错位。
下面是一个真实用户的例子：
从上图中可以看到，用户执行的一条SQL写入了“2021-07-23 07:04:00.000″这个时刻的数据，可是在不同的客户端中，查询出的结果却相差了13个小时。
今天希望通过这篇文章，将日期时间、时间戳以及TDengine在写入和查询时处理时区的行为等描述清楚，并给出如何设置timezone参数的意见，供大家参考。
在开始之前，你需要先了解以下这三点
1. TDengine中用时间戳表示日期时间，以标准的Unix元年时间（UTC时区1970年1月1日0点0分0秒）为原点，支持毫秒、微秒、纳秒三种精度；
2. 在写入时，如果SQL中是本地日期时间格式，TDengine的客户端使用当前生效的timezone配置，将SQL中的日期时间转换为timestamp；同时，也支持使用RFC-3339格式的日期时间进行写入；
3. 在shell中查询时，客户端使用当前生效的timezone配置，将TDengine中存储的timestamp转换为日期时间格式进行显示。
本文所用相关概念
- 本地日期时间：表示当地的日期时间。12:00是中午吃饭的时间，8:00是早上上班的时间，这是人类习惯的一种表示时间的方式，是不带时区信息的日期和时间，可以当成一个String。例如：2021-07-21 12:00:00.000，表示2021年7月21日正午，时间精度以毫秒记，这个日期时间的表示方法，不带任何时区信息。
- 时区：地理概念，按照UTC/格林威治时区，把地球划分成向东和向西各12个时区，其中东12区和西12区是一个区。时区可以通过’Asia/shanghai’这样的’地区/城市’的方式表示，也可以用UTC偏移的方式表示。例如：UTC+8，代表东八区，当协调世界时（UTC）时间为凌晨2点的时候，当地的时间为2+8点，即早上10点。
- RFC 3339：一种表示日期时间的标准格式。RFC 3339是带时区信息的格式，即包含日期时间信息，也有时区信息。例如，以下两个时间在地球上是同一时刻：2019-10-12T07:20:50+00:00，这个表示2019年10月12日，上午7点20分50秒(UTC+0时区)，2019-10-12T15:20:50+08:00，这个表示2019年10月12日，下午3点20分50秒(UTC+8时区)。
- 时间戳：是机器存储和计算时间的方式。以Unix元年（UTC时区1970年1月1日0点0分0秒）开始经过的秒数计算，不同精度的计时方式，可以有不同的时间戳。例如：0，表示UTC时区1970年1月1日凌晨的时间。
本地日期时间、时区信息、时间戳的关系可以参考下面这张图：
TDengine如何处理日期时间？
写入
如果在insert语句中，用一个String表示日期时间，插入到TDengine，存在着将这个String解析成timestamp的过程。这个String存在不同的格式，合法的格式包括：
（1）RFC 3339标准的表示方式
（2）yyyy-MM-dd hh:mm:ss
第1种情况——采用RFC 3339标准，那么这个String是带时区信息的，可以明确地将其转换成timestamp。例如：
这里，介绍一个小技巧：使用-r参数启动taos shell时，timestamp类型的数据，将会以时间戳（long值）的形式显示。# taos -rtaos> drop table test.weather;Query OK, 0 of 0 row(s) in database (0.004202s)taos> create table test.weather(ts timestamp, f1 float) ;Query OK, 0 of 0 row(s) in database (0.012690s)taos> insert into test.weather values('1970-01-01T08:00:00.000+08:00',22.00) ;Query OK, 1 of 1 row(s) in database (0.002363s)taos> select * from test.weather;ts | f1 |========================================0 | 22.00000 |Query OK, 1 row(s) in set (0.001476s)
可以看到，1970-01-01T08:00:00.000+08:00，代表UTC+8时区1970年1月1日上午8:00，这正好对应UTC时区的凌晨，所以在timestamp是0。
第2种情况——在insert语句中使用yyyy-MM-dd hh:mm:ss格式的时间字符串，不含时区信息。这时，taos客户端会采用当前timezone信息，将字符串转化成timestamp。例如：
可以看到，1970-01-01T08:00:00.000+08:00，代表UTC+8时区1970年1月1日上午8:00，这正好对应UTC时区的凌晨，所以在timestamp是0。
第2种情况——在insert语句中使用yyyy-MM-dd hh:mm:ss格式的时间字符串，不含时区信息。这时，taos客户端会采用当前timezone信息，将字符串转化成timestamp。例如：
taos> show variables;name | value |============================================================timezone | (CST, +0800) |taos> insert into test.weather(ts, f1) values('1970-01-01 00:00:00.000', 22.00);Query OK, 1 of 1 row(s) in database (0.001290s)taos> select * from test.weather;ts | f1 |========================================-28800000 | 22.00000 |Query OK, 1 row(s) in set (0.002220s)
可以看到，insert语句使用了配置文件中的时区信息，和insert语句中的日期时间信息，即“1970-01-01 00:00:00+08:00”，这个值在时间戳中正好代表-28800000。
由此可见，在TDengine中，时间原点是国际通用的Unix元年（UTC时区1970年1月1日凌晨）。
查询
# 在taos.cfg内配置timezone# cat /etc/taos/taos.cfg | grep timezonetimezone UTC+0# 在shell中查询timezonetaos> show variables;name | value |============================================================timezone | (CST, +0800) |# taos -s "select * from test.weather" -rWelcome to the TDengine shell from Linux, Client Version:2.0.20.11Copyright (c) 2020 by TAOS Data, Inc. All rights reserved.taos> select * from test.weatherts | f1 |========================================-28800000 | 22.00000 |Query OK, 1 row(s) in set (0.002564s)# taos -s "select * from test.weather"Welcome to the TDengine shell from Linux, Client Version:2.0.20.11Copyright (c) 2020 by TAOS Data, Inc. All rights reserved.taos> select * from test.weather;ts | f1 |=================================================1969-12-31 16:00:00.000 | 22.00000 |Query OK, 1 row(s) in set (0.002306s)
可以看到，select语句在查询时，依然存在着从ts转换为一个string串的情况，Tdengine会将ts转换成当前taos client中的时区。
Timezone配置为UTC-8
有些用户不理解，为什么在TDengine中timezone会被配置为UTC-8？原因是，在POSIX标准中，表示时区偏移量的方式和地理的表示方式不一致。参考Wikipedia中的定义，在ISO 8601中，UTC+8为东八区，该时区是以中文为主的时区。那在Unix中，东八区又应该如何表示？请参考下面这个例子：
# date --help用法：date [选项]... [+格式]或：date [-u|--utc|--universal] [MMDDhhmm[[CC]YY][.ss]]Display the current time in the given FORMAT, or set the system date.%z +hhmm数字时区(例如，-0400)%:z +hh:mm数字时区(例如，-04:00)%Z按字母表排序的时区缩写 (例如，EDT)Examples:Show the time on the west coast of the US (use tzselect(1) to find TZ)$ TZ='America/Los_Angeles' date# 使用TZ='UTC-8'查看当前时间# TZ='UTC-8' date +'%Y-%m-%d %H:%M:%S %Z %z'2021-08-01 22:31:29 UTC +0800# 使用TZ='UTC'查看当前时间# TZ='UTC' date +'%Y-%m-%d %H:%M:%S %Z %z'2021-08-01 14:31:51 UTC +0000# 使用TZ='UTC+8'查看当前时间# TZ='UTC+8' date +'%Y-%m-%d %H:%M:%S %Z %z'2021-08-01 06:32:06 UTC -0800
可见，在POSIX标准中，UTC-8代表东八区，UTC+8代表西八区。这里与地理上表示时区的习惯是不一致的。在taos.cfg中，TDengine使用的是POSIX Timezone标准。
在JDBC中设置Timezone
在使用JDBC Connector连接TDengine时，可以通过3个途径设置timezone参数，分别为：url、properties和taos.cfg配置文件。
// urlConnection conn = DriverManager.getConnection("jdbc:TAOS://taosdemo.com:6030/test?timezone=UTC-8", "root", "taosdata");// propertiesProperties connProps = new Properties();connProps.setProperty(TSDBDriver.PROPERTY_KEY_USER, "root");connProps.setProperty(TSDBDriver.PROPERTY_KEY_PASSWORD, "taosdata");connProps.setProperty(TSDBDriver.PROPERTY_KEY_TIME_ZONE, "UTC-8");// 当url和properties中都没有制定timezone的情况下，会使用本地配置文件taos.cfg中timezone的配置参数Connection conn = DriverManager.getConnection("jdbc:TAOS://taosdemo.com:6030/test", connProps);
参考文档： https://tdengine.com/docs/cn/v2.0/connector/java
总结
最后，我们再回顾一下前文中描述的用户问题：“为什么在不同的客户端中，日期时间会相差13个小时？”执行的insert语句SQL为：
INSERT INTO n802344030600001_w21003 USING mnt_factor_item_data TAGS ("N802344030600001", 'w21003') VALUES ('2021-7-23 07:04:00:000',3, 999,'N802344030600002','w21003',19,'COD','mg/L',4,2,'大空港片区',1,'龙翔北路监测控制站',1,'龙翔北路水监测设备',3,'龙翔北路监测终端');SQL中是以本地日期时间的格式表示时间戳的，客户端使用了本地的timezone，将这个“2021-7-23 07:04:00:000”转换为timestamp；在查询时，Windows上的shell和Linux的shell都会将timestamp，根据当前生效的timezone，转换成日期时间格式。
参考文献：
2. 理解RFC 3339标准
3. RFC 3339标准
4. UTC+8时区的定义
