时区处理

场景信息概述

• 存储纽约某一交易所地交易数据，其中一列是交易时间，例如2022.02.20 09:35:03。
• 数据库服务部署在北京（东八区）。
• 业务相关的端上服务（web、APP 等）一部分部署在北京（东八区），另一部分部署在旧金山（西八区）。

业务需求概述

• 要求无论是在北京（东八区）还是旧金山（西八区）的用户，访问端上服务时，查询时显示的数据时间显示和纽约交易所本地交易时间（西五区）一致，本例中以即显示2022.02.20 09:35:03为例进行说明。

在需要存储时区信息的场景下，DolphinDB 也可以通过一些内置函数实现存储时区信息。

场景信息概述

• 某中国买家通过电商平台，与日本卖家达成了一笔线上交易。交易时间为北京时间2022.05.20 11:30:05（东八区），东京时间2022.05.20 12:30:05（东九区）。
• 该电商公司在中国和日本都部署了数据中心，分别用于存储当前国家的交易数据。

业务需求概述

用户浏览订单时，平台显示的交易时间必须与用户所在时区一致，即中国买家看到北京时间，日本卖家看到东京时间。

时间数据在导入 DolphinDB 后，可能会出现其在 DolphinDB 中打印的值与原数据库中的值“不一致”的情况。这和 Java Date 类的存储逻辑有关，下面进行解释。

• 实例化 Date 类

Date date = new Date();
System.out.println(date);
// Mon May 23 22:22:10 CST 2022

这里要注意的是，尽管直接打印 date 对象显示的是当前服务器时间，但其底层存储的是 Unix 时间戳（长整型）。

• 存储入库

执行如下代码，在 DolphinDB Server 端创建一个两列的共享内存表：

conn.run("t = table(100:0,`ts`value,[TIMESTAMP,INT]);share t as timeJava;");

通过 Java API 写入一条数据，示例代码如下：

public static void write() throws IOException {
    DBConnection conn = new DBConnection();
    conn.connect("localhost", 8848, "admin", "123456");
    LinkedList<Long> dtList = new LinkedList<>();// ts
    LinkedList<Integer> valueList = new LinkedList<>();// value
    Date date = new Date();
    System.out.println(date);
    dtList.add(date.getTime());
    valueList.add(1);
    List<Entity> data = Arrays.asList(
    new BasicTimestampVector(dtList),
    new BasicIntVector(valueList)
    );
    conn.run("tableInsert{\"testJava\"}", data);
}

Java API 通过 System.out.println(date)将写入的时间打印到了前台，同时通过 DolphinDB GUI 查看共享内存表中写入的数据，对比结果如下图所示：

观察发现，Java 控制台打印的时间和数据入库时间不符，出现了时间错乱的现象，原因有以下两点：

1. Date 对象实例化是通过 System.currentTimeMillis() 返回的 Unix 时间戳实现的。关于 Date 的构造函数的更多信息，见 Java官方文档。

/**
* Allocates a <code>Date</code> object and initializes it so that
* it represents the time at which it was allocated, measured to the
* nearest millisecond.
*
* @see     java.lang.System#currentTimeMillis()
*/
public Date() {
	this(System.currentTimeMillis());
}

1. 在 Java 中，Date 类的打印输出值是通过重写其 toString 方法来定制的，该方法涉及时区转换（见下面的源代码）。因此，尽管 Date 被存储为 Unix 的时间戳，但它是根据服务器的时区来打印的。

public String toString() {
        // "EEE MMM dd HH:mm:ss zzz yyyy";
        BaseCalendar.Date date = normalize();
        StringBuilder sb = new StringBuilder(28);
        int index = date.getDayOfWeek();
        if (index == BaseCalendar.SUNDAY) {
            index = 8;
        }
        convertToAbbr(sb, wtb[index]).append(' ');                        // EEE
        convertToAbbr(sb, wtb[date.getMonth() - 1 + 2 + 7]).append(' ');  // MMM
        CalendarUtils.sprintf0d(sb, date.getDayOfMonth(), 2).append(' '); // dd
        CalendarUtils.sprintf0d(sb, date.getHours(), 2).append(':');   // HH
        CalendarUtils.sprintf0d(sb, date.getMinutes(), 2).append(':'); // mm
        CalendarUtils.sprintf0d(sb, date.getSeconds(), 2).append(' '); // ss
        TimeZone zi = date.getZone();
        if (zi != null) {
            sb.append(zi.getDisplayName(date.isDaylightTime(), TimeZone.SHORT, Locale.US)); // zzz
        } else {
            sb.append("GMT");
        }
        sb.append(' ').append(date.getYear());  // yyyy
        return sb.toString();
}

另一方面，DolphinDB 把导入的时间的 Unix 时间戳存储在 LONG 类型中，并以 UTC 时区显示。

因此，虽然时间值在导入 DolphinDB 前后显得 "不一致"，但事实上在这个过程中没有任何修改。

本节基于 MySQL 5.7 版本进行说明，本节讨论的日期时间类型有：DATETIME, TIMESTAMP, DATE, TIME。

• DATE, TIME, DATETIME：和时区无关，存进去的值不会根据时区的调整而改变。
• TIMESTAMP：和时区相关，TIMESTAMP 存储的是 Unix 时间戳，显示时会将时间戳转换为设置的时区进行显示。

使用下面的命令来检查 MySQL 中时区变量的值。输出显示系统时区是 "CST"（中国标准时间，即 UTC+8），服务器时区与系统时区相同。

mysql> show variables like '%time_zone%';
+------------------+--------+
| Variable_name    | Value  |
+------------------+--------+
| system_time_zone | CST    |
| time_zone        | SYSTEM |
+------------------+--------+

执行如下命令，创建数据库和表：

mysql> USE testdb;
mysql> CREATE TABLE testTable(
    -> date DATE NOT NULL,
    -> time TIME NOT NULL,
    -> ts TIMESTAMP NOT NULL
    -> );
Query OK, 0 rows affected (0.11 sec)

插入测试数据后，查看数据：

mysql> select * from testTable;
+------------+----------+---------------------+
| date       | time     | ts                  |
+------------+----------+---------------------+
| 2022-06-14 | 23:13:15 | 2022-06-14 23:13:15 |
+------------+----------+---------------------+
1 row in set (0.00 sec)

此时，设置数据库时区为东九区，再次查看数据：

mysql> set time_zone='+09:00';
Query OK, 0 rows affected (0.01 sec)

mysql> show variables like '%time_zone%';
+------------------+--------+
| Variable_name    | Value  |
+------------------+--------+
| system_time_zone | CST    |
| time_zone        | +09:00 |
+------------------+--------+
2 rows in set (0.00 sec)

mysql> select * from testTable;
+------------+----------+---------------------+
| date       | time     | ts                  |
+------------+----------+---------------------+
| 2022-06-14 | 23:13:15 | 2022-06-15 00:13:15 |
+------------+----------+---------------------+
1 row in set (0.00 sec)

比较时区变化前后的查询结果："date" 和 "time" 列包含固定的 DATE 和 TIME 值，因此没有变化；"ts" 列中的 TIMESTAMP 值随着时区从 UTC+8 变为 UTC+9 而向前推进了1小时。

本节通过 DolphinDB 的 MySQL 插件，将 MySQL 中的数据快速导入 DolphinDB。MySQL 插件会自动完成数据类型转换。MySQL时间类型与DolphinDB时间类型转换关系如下表。关于插件更多使用介绍，请参考：MySQL插件使用说明。

DolphinDB 还支持如下时间相关的类型：MONTH, MINUTE, SECOND, NANOTIME, NANOTIMESTAMP。

首先导入一批纽约交易所的 csv 数据至 MySQL 中，本次测试 MySQL 全局 time_zone 设置为 UTC，csv 示例数据和 MySQL 导入代码见附录。

为了对比 DATE, TIME 和 TIMESTAMP 类型的值分别导入到 DolphinDB 中的效果，笔者新增一列 ts（TIMESTAMP 类型），插入了交易时间（西五区）对应的 UTC 时间数据，相比 time 列的数据晚了5个小时。

完成导入后查看数据：

mysql> select * from taqTs limit 5;
+--------+------------+----------+-------+-------+--------+--------+------+-----+------+---------------------+
| symbol | date       | time     | bid   | ofr   | bidsiz | ofrsiz | mode | ex  | mmid | ts                  |
+--------+------------+----------+-------+-------+--------+--------+------+-----+------+---------------------+
| A      | 2022-02-20 | 06:24:34 |  1.00 |  0.00 |      1 |      0 |   12 | 'P' | null | 2022-02-20 11:24:34 |
| A      | 2022-02-20 | 06:24:56 |  0.00 |  0.00 |      0 |      0 |   12 | 'P' | null | 2022-02-20 11:24:56 |
| A      | 2022-02-20 | 07:02:00 |  0.00 | 54.84 |      0 |      1 |   12 | 'T' | null | 2022-02-20 12:02:00 |
| A      | 2022-02-20 | 07:02:00 | 22.17 | 54.84 |      1 |      1 |   12 | 'T' | null | 2022-02-20 12:02:00 |
| A      | 2022-02-20 | 07:08:22 | 37.00 | 54.84 |      1 |      1 |   12 | 'T' | null | 2022-02-20 12:08:22 |
+--------+------------+----------+-------+-------+--------+--------+------+-----+------+---------------------+

然后在 DolphinDB 中加载 MySQL 插件，将 MySQL 数据导入到 DolphinDB 内存表，具体代码如下：

// 加载插件
loadPlugin("/DolphinDB/server/plugins/mysql/PluginMySQL.txt");

// 连接 MySQL Server
conn = mysql::connect(`127.0.0.1, 3306, `root, "root", `testdb)

// 执行导入
taqDdb = mysql::load(conn, "SELECT * FROM taqTs");

// 查看数据
select * from taqDdb;

由此可见，如果用户想同步 MySQL 数据库中的 UTC 表示的 TIMESTAMP 类型的列到 DolphinDB，需要先设置 MySQL 的全局 time_zone 为 UTC。对于 DATE, TIME 和 TIMESTAMP 类型的数据，导入前后对比可见，DolphinDB 和 MySQL 是完全一致的。

需要注意的是，MySQL 的 time_zone 时区设置分为全局和会话两种级别，如果用户发现在 MySQL 的客户端查询和导入到 DolphinDB 中的时间不一致，首先需要检查全局 time_zone 和会话 time_zone 是否一致，DolphinDB 处理 MySQL 的 TIMESTAMP 列时，会按照全局 time_zone 下的时间戳进行存储。

比如此时在 MySQL 查询客户端中设置会话 time_zone = '+08:00'，并查看数据，可以观察到本次查询会话中 ts 列的数据从 UTC 转换成了东八区时间进行显示：

mysql> set time_zone='+08:00';
Query OK, 0 rows affected (0.00 sec)

mysql> select * from taqTs limit 5;
+--------+------------+----------+-------+-------+--------+--------+------+-----+------+---------------------+
| symbol | date       | time     | bid   | ofr   | bidsiz | ofrsiz | mode | ex  | mmid | ts                  |
+--------+------------+----------+-------+-------+--------+--------+------+-----+------+---------------------+
| A      | 2022-02-20 | 06:24:34 |  1.00 |  0.00 |      1 |      0 |   12 | 'P' | null | 2022-02-20 19:24:34 |
| A      | 2022-02-20 | 06:24:56 |  0.00 |  0.00 |      0 |      0 |   12 | 'P' | null | 2022-02-20 19:24:56 |
| A      | 2022-02-20 | 07:02:00 |  0.00 | 54.84 |      0 |      1 |   12 | 'T' | null | 2022-02-20 20:02:00 |
| A      | 2022-02-20 | 07:02:00 | 22.17 | 54.84 |      1 |      1 |   12 | 'T' | null | 2022-02-20 20:02:00 |
| A      | 2022-02-20 | 07:08:22 | 37.00 | 54.84 |      1 |      1 |   12 | 'T' | null | 2022-02-20 20:08:22 |
+--------+------------+----------+-------+-------+--------+--------+------+-----+------+---------------------+
5 rows in set (0.00 sec)

在 DolphinDB 中重新连接 MySQL，执行上述的数据导入代码，此时全局 time_zone 还是 UTC，且没有临时设置会话 time_zone，所以 ts 列的数据还是和 MySQL 中保持一致，查询同步到 DolphinDB 的结果表如下：

此时若通过 set global time_zone='+08:00'，设置 MySQL 的全局 time_zone 为东八区，然后在 DolphinDB 中重新连接 MySQL，执行上述的数据导入代码。此时，MySQL 的全局 time_zone 为东八区，ts 是 TIMESTAMP 类型，存储的是 Unix 时间戳，根据设置的时区转换，从 MySQL 查询获得的 ts 列时间自动转换成了东八区的时间，所以比原始的 UTC 会晚8个小时，查询同步到 DolphinDB 的结果表如下：