diff --git a/src/UserGuide/Master/Table/API/RestAPI-V1_apache.md b/src/UserGuide/Master/Table/API/RestAPI-V1_apache.md index 42514d871..d3ed99416 100644 --- a/src/UserGuide/Master/Table/API/RestAPI-V1_apache.md +++ b/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: +``` + +`` 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 diff --git a/src/UserGuide/Master/Tree/API/RestServiceV1_apache.md b/src/UserGuide/Master/Tree/API/RestServiceV1_apache.md index 519f75011..970288d5f 100644 --- a/src/UserGuide/Master/Tree/API/RestServiceV1_apache.md +++ b/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: +``` + +`` 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 diff --git a/src/UserGuide/Master/Tree/API/RestServiceV2_apache.md b/src/UserGuide/Master/Tree/API/RestServiceV2_apache.md index 43e9bb4cf..ecb8cd7ba 100644 --- a/src/UserGuide/Master/Tree/API/RestServiceV2_apache.md +++ b/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: +``` + +`` 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 diff --git a/src/UserGuide/latest-Table/API/RestAPI-V1_apache.md b/src/UserGuide/latest-Table/API/RestAPI-V1_apache.md index 42514d871..d3ed99416 100644 --- a/src/UserGuide/latest-Table/API/RestAPI-V1_apache.md +++ b/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: +``` + +`` 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 diff --git a/src/UserGuide/latest/API/RestServiceV1_apache.md b/src/UserGuide/latest/API/RestServiceV1_apache.md index 519f75011..970288d5f 100644 --- a/src/UserGuide/latest/API/RestServiceV1_apache.md +++ b/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: +``` + +`` 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 diff --git a/src/UserGuide/latest/API/RestServiceV2_apache.md b/src/UserGuide/latest/API/RestServiceV2_apache.md index 43e9bb4cf..ecb8cd7ba 100644 --- a/src/UserGuide/latest/API/RestServiceV2_apache.md +++ b/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: +``` + +`` 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 diff --git a/src/zh/UserGuide/Master/Table/API/RestServiceV1_apache.md b/src/zh/UserGuide/Master/Table/API/RestServiceV1_apache.md index 840a48a0b..3063cca8d 100644 --- a/src/zh/UserGuide/Master/Table/API/RestServiceV1_apache.md +++ b/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 diff --git a/src/zh/UserGuide/Master/Tree/API/RestServiceV1_apache.md b/src/zh/UserGuide/Master/Tree/API/RestServiceV1_apache.md index c1b50601d..94dcbcdb3 100644 --- a/src/zh/UserGuide/Master/Tree/API/RestServiceV1_apache.md +++ b/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 diff --git a/src/zh/UserGuide/Master/Tree/API/RestServiceV2_apache.md b/src/zh/UserGuide/Master/Tree/API/RestServiceV2_apache.md index 74f3a6b54..a1ce47f21 100644 --- a/src/zh/UserGuide/Master/Tree/API/RestServiceV2_apache.md +++ b/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 diff --git a/src/zh/UserGuide/latest-Table/API/RestServiceV1_apache.md b/src/zh/UserGuide/latest-Table/API/RestServiceV1_apache.md index 840a48a0b..3063cca8d 100644 --- a/src/zh/UserGuide/latest-Table/API/RestServiceV1_apache.md +++ b/src/zh/UserGuide/latest-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 diff --git a/src/zh/UserGuide/latest/API/RestServiceV1_apache.md b/src/zh/UserGuide/latest/API/RestServiceV1_apache.md index c1b50601d..94dcbcdb3 100644 --- a/src/zh/UserGuide/latest/API/RestServiceV1_apache.md +++ b/src/zh/UserGuide/latest/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 diff --git a/src/zh/UserGuide/latest/API/RestServiceV2_apache.md b/src/zh/UserGuide/latest/API/RestServiceV2_apache.md index 74f3a6b54..a1ce47f21 100644 --- a/src/zh/UserGuide/latest/API/RestServiceV2_apache.md +++ b/src/zh/UserGuide/latest/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