This is an automated email from the ASF dual-hosted git repository.
xiangweiwei pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/iotdb.git
The following commit(s) were added to refs/heads/master by this push:
new cd69b8e Add user document of time zone (#3457)
cd69b8e is described below
commit cd69b8e51cf7c6797374d73de9d76922b49df9ac
Author: Xiangwei Wei <[email protected]>
AuthorDate: Tue Jul 6 09:34:38 2021 +0800
Add user document of time zone (#3457)
---
docs/UserGuide/API/Time-zone.md | 84 +++++++++++++++++++++++++++++++++++++
docs/zh/UserGuide/API/Time-zone.md | 85 ++++++++++++++++++++++++++++++++++++++
site/src/main/.vuepress/config.js | 6 ++-
3 files changed, 173 insertions(+), 2 deletions(-)
diff --git a/docs/UserGuide/API/Time-zone.md b/docs/UserGuide/API/Time-zone.md
new file mode 100644
index 0000000..40bf945
--- /dev/null
+++ b/docs/UserGuide/API/Time-zone.md
@@ -0,0 +1,84 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+# Time zone
+
+When a client connects to the IoTDB server, it can specify the time zone to be
used for this connection. If not specified, the default time zone is the one of
the client.
+
+The time zone can be set in both JDBC and session native interface
connections. The usage is as follows:
+
+```java
+JDBC: (IoTDBConnection) connection.setTimeZone("+08:00");
+
+Session: session.setTimeZone("+08:00");
+```
+
+In the CLI command line tool, the way to manually set the time zone through
SQL is as follows:
+
+```java
+SET time_zone=+08:00
+```
+
+The way to view the time zone used by the current connection is as follows:
+
+```java
+JDBC: (IoTDBConnection) connection.getTimeZone();
+
+Session: session.getTimeZone();
+```
+
+## Time zone usage scenarios
+
+The IoTDB server only stores and processes time stamps, and the time zone is
only used to interact with clients. The specific scenarios are as follows:
+
+1. Convert the time format string sent from the client to the corresponding
time stamp.
+
+ For example，execute `insert into root.sg.d1(timestamp, s1)
values(2021-07-01T08:00:00.000, 3.14)`
+
+ Then `2021-07-01T08:00:00.000` will be converted to the corresponding
timestamp value according to the time zone of the client. If it's in GMT+08:00,
the result will be `1625097600000` ，which is equal to the timestamp value of
`2021-07-01T00:00:00.000` in GMT+00:00。
+
+ > Note: At the same time, the dates of different time zones are different,
but the timestamps are the same.
+
+
+
+2. Convert the timestamp in the result returned to the client into a time
format string.
+
+ Take the above situation as an example，execute `select * from
root.sg.d1`，the server will return the time value pair: `(1625097600000,
3.14)`. If CLI tool is used，then `1625097600000` will be converted into time
format string according to time zone, as shown in the figure below：
+
+ ```
+ +-----------------------------+-------------+
+ | Time|root.sg.d1.s1|
+ +-----------------------------+-------------+
+ |2021-07-01T08:00:00.000+08:00| 3.14|
+ +-----------------------------+-------------+
+ ```
+
+ If the query is executed on the client in GMT:+00:00, the result will be as
follows:
+
+ ```
+ +-----------------------------+-------------+
+ | Time|root.sg.d1.s1|
+ +-----------------------------+-------------+
+ |2021-07-01T00:00:00.000+00:00| 3.14|
+ +-----------------------------+-------------+
+ ```
+
+ Note that the timestamps returned are the same, but the dates shown in
different time zones are different.
diff --git a/docs/zh/UserGuide/API/Time-zone.md
b/docs/zh/UserGuide/API/Time-zone.md
new file mode 100644
index 0000000..faf9889
--- /dev/null
+++ b/docs/zh/UserGuide/API/Time-zone.md
@@ -0,0 +1,85 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+# 时区
+
+客户端连接 IoTDB 服务器时，可以指定该连接所要使用的时区。如果未指定，则**默认以客户端所在的时区作为连接的时区。**
+
+在 JDBC 和 Session 原生接口连接中均可以设置时区，使用方法如下：
+
+```java
+JDBC: (IoTDBConnection) connection.setTimeZone("+08:00");
+
+Session: session.setTimeZone("+08:00");
+```
+
+在 CLI 命令行工具中，通过 SQL 手动设置时区的方式为：
+
+```java
+SET time_zone=+08:00
+```
+
+查看当前连接使用的时区的方法如下：
+
+```java
+JDBC: (IoTDBConnection) connection.getTimeZone();
+
+Session: session.getTimeZone();
+```
+
+## 时区使用场景
+
+IoTDB 服务器只针对时间戳进行存储和处理，时区只用来与客户端进行交互，具体场景如下：
+
+1. 将客户端传来的日期格式的字符串转化为相应的时间戳。
+
+ 例如，执行写入 `insert into root.sg.d1(timestamp, s1)
values(2021-07-01T08:00:00.000, 3.14)`
+
+ 则
`2021-07-01T08:00:00.000`将会根据客户端所在的时区转换为相应的时间戳，如果在东八区，则会转化为`1625097600000` ，等价于
0 时区 `2021-07-01T00:00:00.000` 的时间戳值。
+
+ > Note：同一时刻，不同时区的日期不同，但时间戳相同。
+
+
+
+2. 将服务器返回给客户端结果中包含的时间戳转化为日期格式的字符串。
+
+ 以上述情况为例，执行查询 `select * from root.sg.d1`，则服务器会返回 (1625097600000, 3.14)
的时间戳值对，如果使用 CLI 命令行客户端，则 `1625097600000` 又会被根据时区转化为日期格式的字符串，如下图所示：
+
+ ```
+ +-----------------------------+-------------+
+ | Time|root.sg.d1.s1|
+ +-----------------------------+-------------+
+ |2021-07-01T08:00:00.000+08:00| 3.14|
+ +-----------------------------+-------------+
+ ```
+
+ 而如果在 0 时区的客户端执行查询，则显示结果将是：
+
+ ```
+ +-----------------------------+-------------+
+ | Time|root.sg.d1.s1|
+ +-----------------------------+-------------+
+ |2021-07-01T00:00:00.000+00:00| 3.14|
+ +-----------------------------+-------------+
+ ```
+
+ 注意，此时返回的时间戳是相同的，只是不同时区的日期不同。
+
diff --git a/site/src/main/.vuepress/config.js
b/site/src/main/.vuepress/config.js
index 464e3bc..48de93f 100644
--- a/site/src/main/.vuepress/config.js
+++ b/site/src/main/.vuepress/config.js
@@ -694,7 +694,8 @@ var config = {
['API/Programming-Python-Native-API','Python Native API'],
['API/Programming-Cpp-Native-API','C++ Native API'],
['API/Programming-Go-Native-API','Go Native API'],
-
['API/Programming-TsFile-API','TsFile API']
+
['API/Programming-TsFile-API','TsFile API'],
+ ['API/Time-zone','Time
zone']
]
},
{
@@ -1485,7 +1486,8 @@ var config = {
['API/Programming-Python-Native-API','Python 原生接口'],
['API/Programming-Cpp-Native-API','C++ 原生接口'],
['API/Programming-Go-Native-API','Go 原生接口'],
-
['API/Programming-TsFile-API','TsFile API']
+
['API/Programming-TsFile-API','TsFile API'],
+ ['API/Time-zone','时区']
]
},
{
