[UPDATE] 2021-07-06

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.

docs/UserGuide/IoTDB-SQL-Language/DML-Data-Manipulation-Language.md

@@ -1562,11 +1562,10 @@ or
 ```
 delete from root.ln.wf02.wt02.* where time <= 2017-11-01T16:26:00;
 ```
-It should be noted that when the deleted path does not exist, IoTDB will give the corresponding error prompt as shown below:
-
+It should be noted that when the deleted path does not exist, IoTDB will not prompt that the path does not exist, but that the execution is successful, because SQL is a declarative programming method. Unless it is a syntax error, insufficient permissions and so on, it is not considered an error, as shown below:
 ```
 IoTDB> delete from root.ln.wf03.wt02.status where time < now()
-Msg: TimeSeries does not exist and its data cannot be deleted
+Msg: The statement is executed successfully.
 ```
 
 ### Delete Time Partition (experimental)

docs/UserGuide/IoTDB-SQL-Language/Maintenance-Command.md

@@ -59,10 +59,15 @@ IoTDB> CREATE SNAPSHOT FOR SCHEMA
 ```
 
 
-## Kill Query
+## Timeout
 
-When using IoTDB, you may encounter the following situations: you have entered a query statement, but can not get the result for a long time, as this query contains too much data or some other reasons, and have to wait until the query ends.
-Since version 0.12, IoTDB has provided two solutions for queries with long execution time: query timeout and query abort.
+IoTDB supports session and query level timeout.
+
+### Session timeout
+
+Session timeout controls when idle sessions are closed. An idle session is one that had not initiated any query or non-query operations for a period of time.
+
+Session timeout is disabled by default and can be set using the `session_timeout_threshold` parameter in IoTDB configuration file.
 
 ### Query timeout
 
@@ -73,7 +78,7 @@ IoTDB> select * from root;
 Msg: 701 Current query is time out, please check your statement or modify timeout parameter.
 ```
 
-The default timeout of the system is 60000 ms，which can be customized in the configuration file through the `query_timeout_threshold` parameter.
+The default timeout of a query is 60000 ms，which can be customized in the configuration file through the `query_timeout_threshold` parameter.
 
 If you use JDBC or Session, we also support setting a timeout for a single query（Unit: ms）：
 

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|
+   +-----------------------------+-------------+
+   ```
+
+   注意，此时返回的时间戳是相同的，只是不同时区的日期不同。
+

docs/zh/UserGuide/IoTDB-SQL-Language/DML-Data-Manipulation-Language.md

@@ -1551,11 +1551,11 @@ delete from root.ln.wf02.wt02 where time <= 2017-11-01T16:26:00;
 delete from root.ln.wf02.wt02.* where time <= 2017-11-01T16:26:00;
 ```
 
-需要注意的是，当删除的路径不存在时，IoTDB会提示路径不存在，无法删除数据，如下所示。
+需要注意的是，当删除的路径不存在时，IoTDB不会提示路径不存在，而是显示执行成功，因为SQL是一种声明式的编程方式，除非是语法错误、权限不足等，否则都不认为是错误，如下所示。
 
 ```
 IoTDB> delete from root.ln.wf03.wt02.status where time < now()
-Msg: TimeSeries does not exist and its data cannot be deleted
+Msg: The statement is executed successfully.
 ```
 
 ### 删除时间分区 (实验性功能)

docs/zh/UserGuide/IoTDB-SQL-Language/Maintenance-Command.md

@@ -56,11 +56,15 @@ IoTDB> CLEAR CACHE
 IoTDB> CREATE SNAPSHOT FOR SCHEMA
 ```
 
-## 中止查询
+## 超时
 
-当使用 IoTDB 时，您可能会遇到以下情形：输入了一个查询，但是由于其包含的数据量过大或是其他原因，导致长时间无法返回结果，但是迫于生产环境无法中止该命令，只能被迫等待。
+IoTDB 支持 Session 超时和查询超时。
 
-从 0.12 版本开始，IoTDB 对执行时间过长的查询给出了两种解决方案：查询超时和查询中止。
+### Session 超时
+
+Session 超时控制何时关闭空闲 Session。空闲 Session 指在一段时间内没有发起任何操作的 Session。
+
+Session 超时默认未开启。可以在配置文件中通过 `session_timeout_threshold` 参数进行配置。
 
 ### 查询超时
 

server/src/assembly/resources/conf/iotdb-engine.properties

@@ -462,6 +462,12 @@ timestamp_precision=ms
 # Datatype: int
 # merge_write_throughput_mb_per_sec=8
 
+# The maximum session idle time. unit: ms
+# Idle sessions are the ones that performs neither query or non-query operations for a period of time
+# Set to 0 to disable session timeout
+# Datatype: int
+# session_timeout_threshold=0
+
 # The max executing time of query. unit: ms
 # Datatype: int
 # query_timeout_threshold=60000

server/src/main/java/org/apache/iotdb/db/conf/IoTDBConfig.java

@@ -407,6 +407,9 @@ public class IoTDBConfig {
   /** the max executing time of query in ms. Unit: millisecond */
   private int queryTimeoutThreshold = 60000;
 
+  /** the max time to live of a session in ms. Unit: millisecond */
+  private int sessionTimeoutThreshold = 0;
+
   /** Replace implementation class of JDBC service */
   private String rpcImplClassName = TSServiceImpl.class.getName();
 
@@ -1217,6 +1220,14 @@ public void setQueryTimeoutThreshold(int queryTimeoutThreshold) {
     this.queryTimeoutThreshold = queryTimeoutThreshold;
   }
 
+  public int getSessionTimeoutThreshold() {
+    return sessionTimeoutThreshold;
+  }
+
+  public void setSessionTimeoutThreshold(int sessionTimeoutThreshold) {
+    this.sessionTimeoutThreshold = sessionTimeoutThreshold;
+  }
+
   public boolean isReadOnly() {
     return readOnly;
   }

server/src/main/java/org/apache/iotdb/db/conf/IoTDBDescriptor.java

@@ -360,6 +360,12 @@ private void loadProps() {
               properties.getProperty(
                   "query_timeout_threshold", Integer.toString(conf.getQueryTimeoutThreshold()))));
 
+      conf.setSessionTimeoutThreshold(
+          Integer.parseInt(
+              properties.getProperty(
+                  "session_timeout_threshold",
+                  Integer.toString(conf.getSessionTimeoutThreshold()))));
+
       conf.setSyncEnable(
           Boolean.parseBoolean(
               properties.getProperty("is_sync_enable", Boolean.toString(conf.isSyncEnable()))));

server/src/main/java/org/apache/iotdb/db/query/control/QueryTimeManager.java

@@ -94,6 +94,8 @@ public AtomicBoolean unRegisterQuery(long queryId) {
           if (scheduledFuture != null) {
             scheduledFuture.cancel(false);
           }
+          SessionTimeoutManager.getInstance()
+              .refresh(SessionManager.getInstance().getSessionIdByQueryId(queryId));
           return null;
         });
     return successRemoved;

server/src/main/java/org/apache/iotdb/db/query/control/SessionManager.java

@@ -77,6 +77,20 @@ public boolean releaseSessionResource(long sessionId) {
     return sessionIdToUsername.remove(sessionId) != null;
   }
 
+  public long getSessionIdByQueryId(long queryId) {
+    // TODO: make this more efficient with a queryId -> sessionId map
+    for (Map.Entry<Long, Set<Long>> statementToQueries : statementIdToQueryId.entrySet()) {
+      if (statementToQueries.getValue().contains(queryId)) {
+        for (Map.Entry<Long, Set<Long>> sessionToStatements : sessionIdToStatementId.entrySet()) {
+          if (sessionToStatements.getValue().contains(statementToQueries.getKey())) {
+            return sessionToStatements.getKey();
+          }
+        }
+      }
+    }
+    return -1;
+  }
+
   public long requestStatementId(long sessionId) {
     long statementId = statementIdGenerator.incrementAndGet();
     sessionIdToStatementId