docs: document REST API session time zone header (V2.0.12)

src/UserGuide/Master/Table/API/RestAPI-V1_apache.md

@@ -30,7 +30,9 @@ The RESTful service is disabled by default. To enable it, locate the `conf/iotdb
 enable_rest_service=true
 ```
 
-## 2. Authentication
+## 2. General Request Headers
+
+### 2.1 Authentication
 
 All RESTful APIs adopt **Basic Authentication**, except the health check interface `/ping`.
 All requests must carry the `Authorization` information in the request header.
@@ -83,6 +85,32 @@ Authorization: Basic cm9vdDpyb290
 ```
 
 
+### 2.2 Session Time Zone
+
+Starting from V2.0.12, the optional `Time-Zone` request header can specify the session time zone for the current request. This setting affects how date-time values without an explicit time-zone offset in SQL are parsed.
+
+The header format is:
+```http
+Time-Zone: <time-zone ID>
+```
+
+`<time-zone ID>` can be any valid value compatible with Java `java.time.ZoneId`, for example:
+
+- `Europe/Warsaw`
+- `Asia/Shanghai`
+- `UTC`
+
+If the request does not include the `Time-Zone` header, the session uses the server's default time zone. If the specified time-zone ID is invalid, the server returns HTTP status `400 Bad Request`.
+
+For example, to query data before local time `2026-04-10 12:00:00` in the `Europe/Warsaw` time zone, send:
+```shell
+curl -X POST http://127.0.0.1:18080/rest/table/v1/query \
+  -H "Authorization: Basic cm9vdDpyb290" \
+  -H "Content-Type: application/json" \
+  -H "Time-Zone: Europe/Warsaw" \
+  -d '{"database":"factory","sql":"SELECT temperature FROM sensor1 WHERE time <= 2026-04-10T12:00:00"}'
+```
+
 ## 3. Interface Definitions
 
 ### 3.1 Ping

src/UserGuide/Master/Tree/API/RestServiceV1_apache.md

@@ -32,7 +32,9 @@ RESTful services are disabled by default.
   enable_rest_service=true
   ```
 
-## 2. Authentication
+## 2. General Request Headers
+
+### 2.1 Authentication
 
 All RESTful services require **Basic authentication** except the health check interface `/ping`. An `Authorization` header must be carried in all requests.
 
@@ -84,6 +86,32 @@ Authorization: Basic cm9vdDpyb290
 
 
 
+### 2.2 Session Time Zone
+
+Starting from V2.0.12, the optional `Time-Zone` request header can specify the session time zone for the current request. This setting affects how date-time values without an explicit time-zone offset in SQL are parsed.
+
+The header format is:
+```http
+Time-Zone: <time-zone ID>
+```
+
+`<time-zone ID>` can be any valid value compatible with Java `java.time.ZoneId`, for example:
+
+- `Europe/Warsaw`
+- `Asia/Shanghai`
+- `UTC`
+
+If the request does not include the `Time-Zone` header, the session uses the server's default time zone. If the specified time-zone ID is invalid, the server returns HTTP status `400 Bad Request`.
+
+For example, to query data before local time `2026-04-10 12:00:00` in the `Europe/Warsaw` time zone, send:
+```shell
+curl -X POST http://127.0.0.1:18080/rest/v1/query \
+  -H "Authorization: Basic cm9vdDpyb290" \
+  -H "Content-Type: application/json" \
+  -H "Time-Zone: Europe/Warsaw" \
+  -d '{"sql":"SELECT temperature FROM root.factory.sensor1 WHERE time <= 2026-04-10T12:00:00"}'
+```
+
 ## 3. Interface
 
 ### 3.1 ping

src/UserGuide/Master/Tree/API/RestServiceV2_apache.md

@@ -32,7 +32,9 @@ RESTful services are disabled by default.
   enable_rest_service=true
   ```
 
-## 2. Authentication
+## 2. General Request Headers
+
+### 2.1 Authentication
 
 All RESTful services require **Basic authentication** except the health check interface `/ping`. An `Authorization` header must be carried in all requests.
 
@@ -83,6 +85,32 @@ Authorization: Basic cm9vdDpyb290
 ```
 
 
+### 2.2 Session Time Zone
+
+Starting from V2.0.12, the optional `Time-Zone` request header can specify the session time zone for the current request. This setting affects how date-time values without an explicit time-zone offset in SQL are parsed.
+
+The header format is:
+```http
+Time-Zone: <time-zone ID>
+```
+
+`<time-zone ID>` can be any valid value compatible with Java `java.time.ZoneId`, for example:
+
+- `Europe/Warsaw`
+- `Asia/Shanghai`
+- `UTC`
+
+If the request does not include the `Time-Zone` header, the session uses the server's default time zone. If the specified time-zone ID is invalid, the server returns HTTP status `400 Bad Request`.
+
+For example, to query data before local time `2026-04-10 12:00:00` in the `Europe/Warsaw` time zone, send:
+```shell
+curl -X POST http://127.0.0.1:18080/rest/v2/query \
+  -H "Authorization: Basic cm9vdDpyb290" \
+  -H "Content-Type: application/json" \
+  -H "Time-Zone: Europe/Warsaw" \
+  -d '{"sql":"SELECT temperature FROM root.factory.sensor1 WHERE time <= 2026-04-10T12:00:00"}'
+```
+
 ## 3. Interface
 
 ### 3.1 ping

src/UserGuide/latest-Table/API/RestAPI-V1_apache.md

@@ -30,7 +30,9 @@ The RESTful service is disabled by default. To enable it, locate the `conf/iotdb
 enable_rest_service=true
 ```
 
-## 2. Authentication
+## 2. General Request Headers
+
+### 2.1 Authentication
 
 All RESTful APIs adopt **Basic Authentication**, except the health check interface `/ping`.
 All requests must carry the `Authorization` information in the request header.
@@ -83,6 +85,32 @@ Authorization: Basic cm9vdDpyb290
 ```
 
 
+### 2.2 Session Time Zone
+
+Starting from V2.0.12, the optional `Time-Zone` request header can specify the session time zone for the current request. This setting affects how date-time values without an explicit time-zone offset in SQL are parsed.
+
+The header format is:
+```http
+Time-Zone: <time-zone ID>
+```
+
+`<time-zone ID>` can be any valid value compatible with Java `java.time.ZoneId`, for example:
+
+- `Europe/Warsaw`
+- `Asia/Shanghai`
+- `UTC`
+
+If the request does not include the `Time-Zone` header, the session uses the server's default time zone. If the specified time-zone ID is invalid, the server returns HTTP status `400 Bad Request`.
+
+For example, to query data before local time `2026-04-10 12:00:00` in the `Europe/Warsaw` time zone, send:
+```shell
+curl -X POST http://127.0.0.1:18080/rest/table/v1/query \
+  -H "Authorization: Basic cm9vdDpyb290" \
+  -H "Content-Type: application/json" \
+  -H "Time-Zone: Europe/Warsaw" \
+  -d '{"database":"factory","sql":"SELECT temperature FROM sensor1 WHERE time <= 2026-04-10T12:00:00"}'
+```
+
 ## 3. Interface Definitions
 
 ### 3.1 Ping

src/UserGuide/latest/API/RestServiceV1_apache.md

@@ -32,7 +32,9 @@ RESTful services are disabled by default.
   enable_rest_service=true
   ```
 
-## 2. Authentication
+## 2. General Request Headers
+
+### 2.1 Authentication
 
 All RESTful services require **Basic authentication** except the health check interface `/ping`. An `Authorization` header must be carried in all requests.
 
@@ -84,6 +86,32 @@ Authorization: Basic cm9vdDpyb290
 
 
 
+### 2.2 Session Time Zone
+
+Starting from V2.0.12, the optional `Time-Zone` request header can specify the session time zone for the current request. This setting affects how date-time values without an explicit time-zone offset in SQL are parsed.
+
+The header format is:
+```http
+Time-Zone: <time-zone ID>
+```
+
+`<time-zone ID>` can be any valid value compatible with Java `java.time.ZoneId`, for example:
+
+- `Europe/Warsaw`
+- `Asia/Shanghai`
+- `UTC`
+
+If the request does not include the `Time-Zone` header, the session uses the server's default time zone. If the specified time-zone ID is invalid, the server returns HTTP status `400 Bad Request`.
+
+For example, to query data before local time `2026-04-10 12:00:00` in the `Europe/Warsaw` time zone, send:
+```shell
+curl -X POST http://127.0.0.1:18080/rest/v1/query \
+  -H "Authorization: Basic cm9vdDpyb290" \
+  -H "Content-Type: application/json" \
+  -H "Time-Zone: Europe/Warsaw" \
+  -d '{"sql":"SELECT temperature FROM root.factory.sensor1 WHERE time <= 2026-04-10T12:00:00"}'
+```
+
 ## 3. Interface
 
 ### 3.1 ping

src/UserGuide/latest/API/RestServiceV2_apache.md

@@ -32,7 +32,9 @@ RESTful services are disabled by default.
   enable_rest_service=true
   ```
 
-## 2. Authentication
+## 2. General Request Headers
+
+### 2.1 Authentication
 
 All RESTful services require **Basic authentication** except the health check interface `/ping`. An `Authorization` header must be carried in all requests.
 
@@ -83,6 +85,32 @@ Authorization: Basic cm9vdDpyb290
 ```
 
 
+### 2.2 Session Time Zone
+
+Starting from V2.0.12, the optional `Time-Zone` request header can specify the session time zone for the current request. This setting affects how date-time values without an explicit time-zone offset in SQL are parsed.
+
+The header format is:
+```http
+Time-Zone: <time-zone ID>
+```
+
+`<time-zone ID>` can be any valid value compatible with Java `java.time.ZoneId`, for example:
+
+- `Europe/Warsaw`
+- `Asia/Shanghai`
+- `UTC`
+
+If the request does not include the `Time-Zone` header, the session uses the server's default time zone. If the specified time-zone ID is invalid, the server returns HTTP status `400 Bad Request`.
+
+For example, to query data before local time `2026-04-10 12:00:00` in the `Europe/Warsaw` time zone, send:
+```shell
+curl -X POST http://127.0.0.1:18080/rest/v2/query \
+  -H "Authorization: Basic cm9vdDpyb290" \
+  -H "Content-Type: application/json" \
+  -H "Time-Zone: Europe/Warsaw" \
+  -d '{"sql":"SELECT temperature FROM root.factory.sensor1 WHERE time <= 2026-04-10T12:00:00"}'
+```
+
 ## 3. Interface
 
 ### 3.1 ping

src/zh/UserGuide/Master/Table/API/RestServiceV1_apache.md

@@ -31,7 +31,9 @@ Restful 服务默认情况是关闭的，开启 restful 功能需要找到 IoTDB
  enable_rest_service=true
 ```
 
-## 2. 鉴权
+## 2. 通用请求头
+
+### 2.1 鉴权
 
 除了检活接口 `/ping`，RESTful 服务均使用基础（Basic）鉴权，所有请求都需要在 Header 中携带 `Authorization` 信息。
 
@@ -87,6 +89,32 @@ Authorization: Basic cm9vdDpyb290
 {"code":800,"message":"INIT_AUTH_ERROR"}
 ```
 
+### 2.2 会话时区
+
+自 V2.0.12 起支持通过可选的 `Time-Zone` 请求头指定当前请求所使用的会话时区。该设置会影响 SQL 中不包含时区偏移量的日期时间值的解析。
+
+请求头格式如下：
+```HTTP
+Time-Zone: <时区 ID>
+```
+
+`<时区 ID>` 可以是任意兼容 Java `java.time.ZoneId` 的有效值，例如：
+
+- `Europe/Warsaw`
+- `Asia/Shanghai`
+- `UTC`
+
+如果请求中未携带 `Time-Zone` 请求头，会话将使用服务端的默认时区。如果指定的时区 ID 无效，服务端将返回 HTTP 状态码 `400 Bad Request`。
+
+例如，客户端希望按照 `Europe/Warsaw` 时区查询当地时间 `2026-04-10 12:00:00` 之前的数据，可以发送以下请求：
+```Shell
+curl -X POST http://127.0.0.1:18080/rest/table/v1/query \
+  -H "Authorization: Basic cm9vdDpyb290" \
+  -H "Content-Type: application/json" \
+  -H "Time-Zone: Europe/Warsaw" \
+  -d '{"database":"factory","sql":"SELECT temperature FROM sensor1 WHERE time <= 2026-04-10T12:00:00"}'
+```
+
 ## 3. 接口定义
 
 ### 3.1 ping

src/zh/UserGuide/Master/Tree/API/RestServiceV1_apache.md

@@ -31,7 +31,9 @@ RESTful 服务默认情况是关闭的
     enable_rest_service=true
    ```
 
-## 2. 鉴权
+## 2. 通用请求头
+
+### 2.1 鉴权
 除了检活接口 `/ping`，RESTful 服务均使用基础（Basic）鉴权，所有请求都需要在 Header 中携带 `Authorization` 信息。
 
 1. 鉴权格式
@@ -87,6 +89,32 @@ Authorization: Basic cm9vdDpyb290
 ```
 
 
+### 2.2 会话时区
+
+自 V2.0.12 起支持通过可选的 `Time-Zone` 请求头指定当前请求所使用的会话时区。该设置会影响 SQL 中不包含时区偏移量的日期时间值的解析。
+
+请求头格式如下：
+```HTTP
+Time-Zone: <时区 ID>
+```
+
+`<时区 ID>` 可以是任意兼容 Java `java.time.ZoneId` 的有效值，例如：
+
+- `Europe/Warsaw`
+- `Asia/Shanghai`
+- `UTC`
+
+如果请求中未携带 `Time-Zone` 请求头，会话将使用服务端的默认时区。如果指定的时区 ID 无效，服务端将返回 HTTP 状态码 `400 Bad Request`。
+
+例如，客户端希望按照 `Europe/Warsaw` 时区查询当地时间 `2026-04-10 12:00:00` 之前的数据，可以发送以下请求：
+```Shell
+curl -X POST http://127.0.0.1:18080/rest/v1/query \
+  -H "Authorization: Basic cm9vdDpyb290" \
+  -H "Content-Type: application/json" \
+  -H "Time-Zone: Europe/Warsaw" \
+  -d '{"sql":"SELECT temperature FROM root.factory.sensor1 WHERE time <= 2026-04-10T12:00:00"}'
+```
+
 ## 3. 接口
 
 ### 3.1 ping

src/zh/UserGuide/Master/Tree/API/RestServiceV2_apache.md

@@ -31,7 +31,9 @@ RESTful 服务默认情况是关闭的
     enable_rest_service=true
    ```
 
-## 2. 鉴权
+## 2. 通用请求头
+
+### 2.1 鉴权
 除了检活接口 `/ping`，RESTful 服务均使用基础（Basic）鉴权，所有请求都需要在 Header 中携带 `Authorization` 信息。
 
 1. 鉴权格式
@@ -86,6 +88,32 @@ Authorization: Basic cm9vdDpyb290
 {"code":603,"message":"UNINITIALIZED_AUTH_ERROR"}
 ```
 
+### 2.2 会话时区
+
+自 V2.0.12 起支持通过可选的 `Time-Zone` 请求头指定当前请求所使用的会话时区。该设置会影响 SQL 中不包含时区偏移量的日期时间值的解析。
+
+请求头格式如下：
+```HTTP
+Time-Zone: <时区 ID>
+```
+
+`<时区 ID>` 可以是任意兼容 Java `java.time.ZoneId` 的有效值，例如：
+
+- `Europe/Warsaw`
+- `Asia/Shanghai`
+- `UTC`
+
+如果请求中未携带 `Time-Zone` 请求头，会话将使用服务端的默认时区。如果指定的时区 ID 无效，服务端将返回 HTTP 状态码 `400 Bad Request`。
+
+例如，客户端希望按照 `Europe/Warsaw` 时区查询当地时间 `2026-04-10 12:00:00` 之前的数据，可以发送以下请求：
+```Shell
+curl -X POST http://127.0.0.1:18080/rest/v2/query \
+  -H "Authorization: Basic cm9vdDpyb290" \
+  -H "Content-Type: application/json" \
+  -H "Time-Zone: Europe/Warsaw" \
+  -d '{"sql":"SELECT temperature FROM root.factory.sensor1 WHERE time <= 2026-04-10T12:00:00"}'
+```
+
 ## 3. 接口
 
 ### 3.1 ping