Skip to content

Add TimeZone header support to REST API (#17344) #17387

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Lexert19 wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Add TimeZone header support to REST API (#17344) #17387

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a678291
Add X-TimeZone header support to REST API (#17344)
Mar 28, 2026
a286e68
Support Time-Zone header and add examples for REST API
Apr 3, 2026
f0c638e
fix test resource leaks
Apr 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions example/rest-java-example/src/main/java/org/apache/iotdb/HttpExample.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ public static void main(String[] args) {
httpExample.ping();
httpExample.insertTablet();
httpExample.query();
httpExample.queryWithTimeZone();
}

public void ping() {
Expand Down Expand Up @@ -138,4 +139,29 @@ public void query() {
}
}
}

public void queryWithTimeZone() {
CloseableHttpClient httpClient = SSLClient.getInstance().getHttpClient();
CloseableHttpResponse response = null;
try {
HttpPost httpPost = getHttpPost("http://127.0.0.1:18080/rest/v1/query");
Copy link

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

queryWithTimeZone() doesn’t actually send the Time-Zone header (unlike the HTTPS and table examples). As written, this method behaves the same as query() and won’t demonstrate the feature. Add the Time-Zone (or intended header name) to this request so the example matches the method name and the PR’s new behavior.

Suggested change
HttpPost httpPost = getHttpPost("http://127.0.0.1:18080/rest/v1/query");
HttpPost httpPost = getHttpPost("http://127.0.0.1:18080/rest/v1/query");
httpPost.setHeader("Time-Zone", "Asia/Shanghai");

Copilot uses AI. Check for mistakes.
String sql = "{\"sql\":\"select * from root.sg25 where time <= 2026-03-28T00:00:00\"}";
httpPost.setEntity(new StringEntity(sql, Charset.defaultCharset()));
response = httpClient.execute(httpPost);
HttpEntity responseEntity = response.getEntity();
String message = EntityUtils.toString(responseEntity, UTF8);
ObjectMapper mapper = new ObjectMapper();
LOGGER.info("message with time zone = {}", mapper.readValue(message, Map.class));
} catch (IOException e) {
LOGGER.error("The query with time zone rest api failed", e);
} finally {
try {
if (response != null) {
response.close();
}
} catch (IOException e) {
LOGGER.error("Response close error", e);
}
}
}
}
27 changes: 27 additions & 0 deletions example/rest-java-example/src/main/java/org/apache/iotdb/HttpsExample.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@ public static void main(String[] args) {
httpsExample.pingHttps();
httpsExample.insertTablet();
httpsExample.query();
httpsExample.queryWithTimeZone();
}

public void pingHttps() {
Expand Down Expand Up @@ -138,4 +139,30 @@ public void query() {
}
}
}

public void queryWithTimeZone() {
CloseableHttpClient httpClient = SSLClient.getInstance().getHttpClient();
CloseableHttpResponse response = null;
try {
HttpPost httpPost = getHttpPost("https://127.0.0.1:18080/rest/v1/query");
httpPost.addHeader("Time-Zone", "+05:00");
String sql = "{\"sql\":\"select * from root.sg25 where time <= 2026-03-28T00:00:00\"}";
httpPost.setEntity(new StringEntity(sql, Charset.defaultCharset()));
response = httpClient.execute(httpPost);
HttpEntity responseEntity = response.getEntity();
String message = EntityUtils.toString(responseEntity, UTF8);
ObjectMapper mapper = new ObjectMapper();
LOGGER.info("message with time zone = {}", mapper.readValue(message, Map.class));
} catch (IOException e) {
LOGGER.error("Https query with time zone rest api failed", e);
} finally {
try {
if (response != null) {
response.close();
}
} catch (IOException e) {
LOGGER.error("Response close error", e);
}
}
}
}
30 changes: 30 additions & 0 deletions example/rest-java-example/src/main/java/org/apache/iotdb/TableHttpExample.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,13 +27,16 @@
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.util.EntityUtils;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.io.IOException;
import java.nio.charset.Charset;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class TableHttpExample {
private static final Logger LOGGER = LoggerFactory.getLogger(TableHttpExample.class);

private static final String UTF8 = "utf-8";

Expand All @@ -50,6 +53,7 @@ public static void main(String[] args) {
httpExample.nonQuery();
httpExample.insertTablet();
httpExample.query();
httpExample.queryWithTimeZone();
}

public void ping() {
Expand Down Expand Up @@ -220,4 +224,30 @@ public void query() {
}
}
}

public void queryWithTimeZone() {
CloseableHttpClient httpClient = SSLClient.getInstance().getHttpClient();
CloseableHttpResponse response = null;
try {
HttpPost httpPost = getHttpPost("http://127.0.0.1:18080/rest/table/v1/query");
httpPost.addHeader("Time-Zone", "+05:00");
String sql =
"{\"database\":\"test\",\"sql\":\"select * from sg211 where time <= 2026-03-28T00:00:00\"}";
httpPost.setEntity(new StringEntity(sql, Charset.defaultCharset()));
response = httpClient.execute(httpPost);
HttpEntity responseEntity = response.getEntity();
String message = EntityUtils.toString(responseEntity, UTF8);
LOGGER.info("message with time zone = {}", JsonParser.parseString(message).getAsJsonObject());
} catch (IOException e) {
LOGGER.error("The query with time zone rest api failed", e);
} finally {
try {
if (response != null) {
response.close();
}
} catch (IOException e) {
LOGGER.error("Response close error", e);
}
}
}
}
30 changes: 30 additions & 0 deletions example/rest-java-example/src/main/java/org/apache/iotdb/TableHttpsExample.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,13 +27,16 @@
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.util.EntityUtils;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.io.IOException;
import java.nio.charset.Charset;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class TableHttpsExample {
private static final Logger LOGGER = LoggerFactory.getLogger(TableHttpsExample.class);

private static final String UTF8 = "utf-8";

Expand All @@ -50,6 +53,7 @@ public static void main(String[] args) {
httpExample.nonQuery();
httpExample.insertTablet();
httpExample.query();
httpExample.queryWithTimeZone();
}

public void ping() {
Expand Down Expand Up @@ -220,4 +224,30 @@ public void query() {
}
}
}

public void queryWithTimeZone() {
CloseableHttpClient httpClient = SSLClient.getInstance().getHttpClient();
CloseableHttpResponse response = null;
try {
HttpPost httpPost = getHttpPost("https://127.0.0.1:18080/rest/table/v1/query");
httpPost.addHeader("Time-Zone", "+05:00");
String sql =
"{\"database\":\"test\",\"sql\":\"select * from sg211 where time <= 2026-03-28T00:00:00\"}";
httpPost.setEntity(new StringEntity(sql, Charset.defaultCharset()));
response = httpClient.execute(httpPost);
HttpEntity responseEntity = response.getEntity();
String message = EntityUtils.toString(responseEntity, UTF8);
LOGGER.info("message with time zone = {}", JsonParser.parseString(message).getAsJsonObject());
} catch (IOException e) {
LOGGER.error("The query with time zone rest api failed", e);
} finally {
try {
if (response != null) {
response.close();
}
} catch (IOException e) {
LOGGER.error("Response close error", e);
}
}
}
}
36 changes: 35 additions & 1 deletion ...ce-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/filter/AuthorizationFilter.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@
import javax.ws.rs.ext.Provider;

import java.io.IOException;
import java.time.DateTimeException;
import java.time.ZoneId;
import java.util.Base64;
import java.util.UUID;
Expand Down Expand Up @@ -88,6 +89,12 @@ public void filter(ContainerRequestContext containerRequestContext) throws IOExc
if (user == null) {
return;
}

ZoneId zoneId = resolveTimeZone(containerRequestContext);
if (zoneId == null) {
return;
}

String sessionid = UUID.randomUUID().toString();
if (SESSION_MANAGER.getCurrSession() == null) {
RestClientSession restClientSession = new RestClientSession(sessionid);
Expand All @@ -97,7 +104,7 @@ public void filter(ContainerRequestContext containerRequestContext) throws IOExc
SESSION_MANAGER.getCurrSession(),
user.getUserId(),
user.getUsername(),
ZoneId.systemDefault(),
zoneId,
IoTDBConstant.ClientVersion.V_1_0);
}
BasicSecurityContext basicSecurityContext =
Expand Down Expand Up @@ -147,6 +154,33 @@ private User checkLogin(
return user;
}

/**
* Resolves the Time-Zone header from the request.
*
* @param requestContext the incoming HTTP request
* @return the resolved ZoneId, or {@code null} if the header is invalid (the request is aborted)
*/
private ZoneId resolveTimeZone(ContainerRequestContext requestContext) {
String timeZoneHeader = requestContext.getHeaderString("Time-Zone");
if (timeZoneHeader == null || timeZoneHeader.isEmpty()) {
return ZoneId.systemDefault();
}
try {
return ZoneId.of(timeZoneHeader);
} catch (DateTimeException e) {
Comment on lines +164 to +170
Copy link

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

timeZoneHeader is used as-is for parsing. If the header is present but contains only whitespace (or has leading/trailing spaces), ZoneId.of(...) will throw and the request will be rejected. Consider trimming the header value before validation/parsing so common client formatting issues don’t cause a 400.

Copilot uses AI. Check for mistakes.
Response resp =
Response.status(Status.BAD_REQUEST)
.type(MediaType.APPLICATION_JSON)
.entity(
new ExecutionStatus()
.code(TSStatusCode.ILLEGAL_PARAMETER.getStatusCode())
.message("Invalid time zone: " + timeZoneHeader))
.build();
requestContext.abortWith(resp);
return null;
}
}

@Override
public void filter(
ContainerRequestContext requestContext, ContainerResponseContext responseContext)
Expand Down
4 changes: 2 additions & 2 deletions ...l/rest/src/main/java/org/apache/iotdb/rest/protocol/table/v1/impl/RestApiServiceImpl.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,6 @@
import javax.ws.rs.core.Response;
import javax.ws.rs.core.SecurityContext;

import java.time.ZoneId;
import java.util.List;
import java.util.Optional;

Expand Down Expand Up @@ -287,7 +286,8 @@ private Statement createStatement(
}

clientSession.setSqlDialect(IClientSession.SqlDialect.TABLE);
return relationSqlParser.createStatement(sql.getSql(), ZoneId.systemDefault(), clientSession);
return relationSqlParser.createStatement(
sql.getSql(), clientSession.getZoneId(), clientSession);
}

private Response validateStatement(Statement statement, boolean userQuery) {
Expand Down
10 changes: 6 additions & 4 deletions ...impl/rest/src/main/java/org/apache/iotdb/rest/protocol/v1/impl/GrafanaApiServiceImpl.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,8 +91,8 @@ public Response variables(SQL sql, SecurityContext securityContext) {
try {
RequestValidationHandler.validateSQL(sql);

Statement statement =
StatementGenerator.createStatement(sql.getSql(), ZoneId.systemDefault());
ZoneId zoneId = SESSION_MANAGER.getCurrSession().getZoneId();
Statement statement = StatementGenerator.createStatement(sql.getSql(), zoneId);
if (!(statement instanceof ShowStatement) && !(statement instanceof QueryStatement)) {
return Response.ok()
.entity(
Expand Down Expand Up @@ -168,7 +168,8 @@ public Response expression(ExpressionRequest expressionRequest, SecurityContext
sql += " " + expressionRequest.getControl();
}

Statement statement = StatementGenerator.createStatement(sql, ZoneId.systemDefault());
ZoneId zoneId = SESSION_MANAGER.getCurrSession().getZoneId();
Statement statement = StatementGenerator.createStatement(sql, zoneId);

Response response = authorizationHandler.checkAuthority(securityContext, statement);
if (response != null) {
Expand Down Expand Up @@ -232,7 +233,8 @@ public Response node(List<String> requestBody, SecurityContext securityContext)
// TODO: necessary to create a partial path?
PartialPath path = new PartialPath(Joiner.on(".").join(requestBody));
String sql = "show child paths " + path;
Statement statement = StatementGenerator.createStatement(sql, ZoneId.systemDefault());
ZoneId zoneId = SESSION_MANAGER.getCurrSession().getZoneId();
Statement statement = StatementGenerator.createStatement(sql, zoneId);

Response response = authorizationHandler.checkAuthority(securityContext, statement);
if (response != null) {
Expand Down
6 changes: 4 additions & 2 deletions ...ce-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/v1/impl/RestApiServiceImpl.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,8 @@ public Response executeNonQueryStatement(SQL sql, SecurityContext securityContex
Statement statement = null;
try {
RequestValidationHandler.validateSQL(sql);
statement = StatementGenerator.createStatement(sql.getSql(), ZoneId.systemDefault());
ZoneId zoneId = SESSION_MANAGER.getCurrSession().getZoneId();
statement = StatementGenerator.createStatement(sql.getSql(), zoneId);
if (statement == null) {
return Response.ok()
.entity(
Expand Down Expand Up @@ -177,7 +178,8 @@ public Response executeQueryStatement(SQL sql, SecurityContext securityContext)
Statement statement = null;
try {
RequestValidationHandler.validateSQL(sql);
statement = StatementGenerator.createStatement(sql.getSql(), ZoneId.systemDefault());
ZoneId zoneId = SESSION_MANAGER.getCurrSession().getZoneId();
statement = StatementGenerator.createStatement(sql.getSql(), zoneId);
if (statement == null) {
return Response.ok()
.entity(
Expand Down
10 changes: 6 additions & 4 deletions ...impl/rest/src/main/java/org/apache/iotdb/rest/protocol/v2/impl/GrafanaApiServiceImpl.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,8 +91,8 @@ public Response variables(SQL sql, SecurityContext securityContext) {
try {
RequestValidationHandler.validateSQL(sql);

Statement statement =
StatementGenerator.createStatement(sql.getSql(), ZoneId.systemDefault());
ZoneId zoneId = SESSION_MANAGER.getCurrSession().getZoneId();
Statement statement = StatementGenerator.createStatement(sql.getSql(), zoneId);
if (!(statement instanceof ShowStatement) && !(statement instanceof QueryStatement)) {
return Response.ok()
.entity(
Expand Down Expand Up @@ -168,7 +168,8 @@ public Response expression(ExpressionRequest expressionRequest, SecurityContext
sql += " " + expressionRequest.getControl();
}

Statement statement = StatementGenerator.createStatement(sql, ZoneId.systemDefault());
ZoneId zoneId = SESSION_MANAGER.getCurrSession().getZoneId();
Statement statement = StatementGenerator.createStatement(sql, zoneId);

Response response = authorizationHandler.checkAuthority(securityContext, statement);
if (response != null) {
Expand Down Expand Up @@ -232,7 +233,8 @@ public Response node(List<String> requestBody, SecurityContext securityContext)
// TODO: necessary to create a PartialPath
PartialPath path = new PartialPath(Joiner.on(".").join(requestBody));
String sql = "show child paths " + path;
Statement statement = StatementGenerator.createStatement(sql, ZoneId.systemDefault());
ZoneId zoneId = SESSION_MANAGER.getCurrSession().getZoneId();
Statement statement = StatementGenerator.createStatement(sql, zoneId);

Response response = authorizationHandler.checkAuthority(securityContext, statement);
if (response != null) {
Expand Down
9 changes: 6 additions & 3 deletions ...ce-impl/rest/src/main/java/org/apache/iotdb/rest/protocol/v2/impl/RestApiServiceImpl.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -270,7 +270,8 @@ public Response executeNonQueryStatement(SQL sql, SecurityContext securityContex
boolean finish = false;
try {
RequestValidationHandler.validateSQL(sql);
statement = StatementGenerator.createStatement(sql.getSql(), ZoneId.systemDefault());
ZoneId zoneId = SESSION_MANAGER.getCurrSession().getZoneId();
statement = StatementGenerator.createStatement(sql.getSql(), zoneId);
if (statement == null) {
return Response.ok()
.entity(
Expand Down Expand Up @@ -310,9 +311,10 @@ public Response executeNonQueryStatement(SQL sql, SecurityContext securityContex
return Response.ok().entity(ExceptionHandler.tryCatchException(e)).build();
} finally {
long costTime = System.nanoTime() - startTime;
if (statement != null)
if (statement != null) {
CommonUtils.addStatementExecutionLatency(
OperationType.EXECUTE_NON_QUERY_PLAN, statement.getType().name(), costTime);
}
if (queryId != null) {
if (finish) {
long executionTime = COORDINATOR.getTotalExecutionTime(queryId);
Expand All @@ -332,7 +334,8 @@ public Response executeQueryStatement(SQL sql, SecurityContext securityContext)
boolean finish = false;
try {
RequestValidationHandler.validateSQL(sql);
statement = StatementGenerator.createStatement(sql.getSql(), ZoneId.systemDefault());
ZoneId zoneId = SESSION_MANAGER.getCurrSession().getZoneId();
statement = StatementGenerator.createStatement(sql.getSql(), zoneId);

if (statement == null) {
return Response.ok()
Expand Down
Loading