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 5 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
5 commits
Select commit Hold shift + click to select a range
a70e434
Add X-TimeZone header support to REST API (#17344)
Mar 28, 2026
76801e8
Support Time-Zone header and add examples for REST API
Apr 3, 2026
cb9cd5c
fix test resource leaks
Apr 3, 2026
1c7b835
copilot review
Apr 9, 2026
ff9d1b5
null checks, table v1 integration tests
Apr 14, 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
27 changes: 27 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,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/v1/query");
Comment thread
Lexert19 marked this conversation as resolved.
httpPost.setHeader("Time-Zone", "Asia/Shanghai");
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);
}
}
}
}
40 changes: 39 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,37 @@ 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) {
return ZoneId.systemDefault();
}
timeZoneHeader = timeZoneHeader.trim();
if (timeZoneHeader.isEmpty()) {
return ZoneId.systemDefault();
}
Comment thread
HTHou marked this conversation as resolved.
try {
return ZoneId.of(timeZoneHeader);
} catch (DateTimeException e) {
Comment thread
Lexert19 marked this conversation as resolved.
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(
Copy link
Copy Markdown
Collaborator

@CritasWang CritasWang Apr 13, 2026

Choose a reason for hiding this comment

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

The table REST API (RestApiServiceImpl in table/v1) was also updated to use session ZoneId, but there are no integration tests for the table model endpoints with the Time-Zone header.

Copy link
Copy Markdown
Author

@Lexert19 Lexert19 Apr 14, 2026

Choose a reason for hiding this comment

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

Added integration tests for Table API.

sql.getSql(), clientSession.getZoneId(), clientSession);
}

private Response validateStatement(Statement statement, boolean userQuery) {
Expand Down
14 changes: 10 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 @@ -21,6 +21,7 @@
import org.apache.iotdb.commons.path.PartialPath;
import org.apache.iotdb.db.conf.IoTDBConfig;
import org.apache.iotdb.db.conf.IoTDBDescriptor;
import org.apache.iotdb.db.protocol.session.IClientSession;
import org.apache.iotdb.db.protocol.session.SessionManager;
import org.apache.iotdb.db.queryengine.plan.Coordinator;
import org.apache.iotdb.db.queryengine.plan.analyze.ClusterPartitionFetcher;
Expand Down Expand Up @@ -91,8 +92,9 @@ public Response variables(SQL sql, SecurityContext securityContext) {
try {
RequestValidationHandler.validateSQL(sql);

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

Statement statement = StatementGenerator.createStatement(sql, ZoneId.systemDefault());
IClientSession session = SESSION_MANAGER.getCurrSession();
ZoneId zoneId = (session != null) ? session.getZoneId() : ZoneId.systemDefault();
Statement statement = StatementGenerator.createStatement(sql, zoneId);

Response response = authorizationHandler.checkAuthority(securityContext, statement);
if (response != null) {
Expand Down Expand Up @@ -232,7 +236,9 @@ 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());
IClientSession session = SESSION_MANAGER.getCurrSession();
ZoneId zoneId = (session != null) ? session.getZoneId() : ZoneId.systemDefault();
Statement statement = StatementGenerator.createStatement(sql, zoneId);

Response response = authorizationHandler.checkAuthority(securityContext, statement);
if (response != null) {
Expand Down
9 changes: 7 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 @@ -20,6 +20,7 @@
import org.apache.iotdb.db.conf.IoTDBConfig;
import org.apache.iotdb.db.conf.IoTDBDescriptor;
import org.apache.iotdb.db.conf.rest.IoTDBRestServiceDescriptor;
import org.apache.iotdb.db.protocol.session.IClientSession;
import org.apache.iotdb.db.protocol.session.SessionManager;
import org.apache.iotdb.db.protocol.thrift.OperationType;
import org.apache.iotdb.db.queryengine.plan.Coordinator;
Expand Down Expand Up @@ -87,7 +88,9 @@ public Response executeNonQueryStatement(SQL sql, SecurityContext securityContex
Statement statement = null;
try {
RequestValidationHandler.validateSQL(sql);
statement = StatementGenerator.createStatement(sql.getSql(), ZoneId.systemDefault());
IClientSession session = SESSION_MANAGER.getCurrSession();
ZoneId zoneId = (session != null) ? session.getZoneId() : ZoneId.systemDefault();
statement = StatementGenerator.createStatement(sql.getSql(), zoneId);
if (statement == null) {
return Response.ok()
.entity(
Expand Down Expand Up @@ -177,7 +180,9 @@ public Response executeQueryStatement(SQL sql, SecurityContext securityContext)
Statement statement = null;
try {
RequestValidationHandler.validateSQL(sql);
statement = StatementGenerator.createStatement(sql.getSql(), ZoneId.systemDefault());
IClientSession session = SESSION_MANAGER.getCurrSession();
ZoneId zoneId = (session != null) ? session.getZoneId() : ZoneId.systemDefault();
statement = StatementGenerator.createStatement(sql.getSql(), zoneId);
if (statement == null) {
return Response.ok()
.entity(
Expand Down
14 changes: 10 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 @@ -21,6 +21,7 @@
import org.apache.iotdb.commons.path.PartialPath;
import org.apache.iotdb.db.conf.IoTDBConfig;
import org.apache.iotdb.db.conf.IoTDBDescriptor;
import org.apache.iotdb.db.protocol.session.IClientSession;
import org.apache.iotdb.db.protocol.session.SessionManager;
import org.apache.iotdb.db.queryengine.plan.Coordinator;
import org.apache.iotdb.db.queryengine.plan.analyze.ClusterPartitionFetcher;
Expand Down Expand Up @@ -91,8 +92,9 @@ public Response variables(SQL sql, SecurityContext securityContext) {
try {
RequestValidationHandler.validateSQL(sql);

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

Statement statement = StatementGenerator.createStatement(sql, ZoneId.systemDefault());
IClientSession session = SESSION_MANAGER.getCurrSession();
ZoneId zoneId = (session != null) ? session.getZoneId() : ZoneId.systemDefault();
Statement statement = StatementGenerator.createStatement(sql, zoneId);

Response response = authorizationHandler.checkAuthority(securityContext, statement);
if (response != null) {
Expand Down Expand Up @@ -232,7 +236,9 @@ 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());
IClientSession session = SESSION_MANAGER.getCurrSession();
ZoneId zoneId = (session != null) ? session.getZoneId() : ZoneId.systemDefault();
Statement statement = StatementGenerator.createStatement(sql, zoneId);

Response response = authorizationHandler.checkAuthority(securityContext, statement);
if (response != null) {
Expand Down
Loading
Loading