Wei-hao-Li · Nov 12, 2026 · Nov 12, 2026 · Nov 13, 2026 · Nov 13, 2026
diff --git a/...rest/src/test/java/org/apache/iotdb/rest/protocol/v1/handler/QueryDataSetHandlerTest.java b/...rest/src/test/java/org/apache/iotdb/rest/protocol/v1/handler/QueryDataSetHandlerTest.java
@@ -26,6 +26,7 @@
 import org.apache.iotdb.db.queryengine.plan.analyze.QueryType;
 import org.apache.iotdb.db.queryengine.plan.execution.ExecutionResult;
 import org.apache.iotdb.db.queryengine.plan.execution.IQueryExecution;
+import org.apache.iotdb.db.queryengine.plan.execution.PendingResultFragment;
 import org.apache.iotdb.rest.protocol.model.ExecutionStatus;
 import org.apache.iotdb.rest.protocol.v1.model.QueryDataSet;
 import org.apache.iotdb.rpc.TSStatusCode;
@@ -88,6 +89,7 @@ private static final class TestQueryExecution implements IQueryExecution {
 
     private final Queue<Optional<TsBlock>> batches = new ArrayDeque<>();
     private final DatasetHeader datasetHeader;
+    private final PendingResultFragment pendingResultFragment = new PendingResultFragment(() -> {});
 
     private TestQueryExecution(TsBlock... tsBlocks) {
       for (TsBlock tsBlock : tsBlocks) {
@@ -124,10 +126,15 @@ public Optional<TsBlock> getBatchResult() throws IoTDBException {
     }
 
     @Override
-    public Optional<ByteBuffer> getByteBufferBatchResult() {
+    public Optional<ByteBuffer> getByteBufferBatchResult(boolean retainMemory) {
       return Optional.empty();
     }
 
+    @Override
+    public PendingResultFragment getPendingResultFragment() {
+      return pendingResultFragment;
+    }
+
     @Override
     public boolean hasNextResult() {
       return !batches.isEmpty();

diff --git a/iotdb-client/isession/src/main/java/org/apache/iotdb/isession/SessionDataSet.java b/iotdb-client/isession/src/main/java/org/apache/iotdb/isession/SessionDataSet.java
@@ -61,7 +61,10 @@ public SessionDataSet(
       ZoneId zoneId,
       int timeFactor,
       boolean tableModel,
-      List<Integer> columnIndex2TsBlockColumnIndexList) {
+      List<Integer> columnIndex2TsBlockColumnIndexList,
+      boolean offsetSet,
+      int offset,
+      int totalLength) {
     this.ioTDBRpcDataSet =
         new IoTDBRpcDataSet(
             sql,
@@ -81,7 +84,48 @@ public SessionDataSet(
             RpcUtils.DEFAULT_TIME_FORMAT,
             timeFactor,
             tableModel,
-            columnIndex2TsBlockColumnIndexList);
+            columnIndex2TsBlockColumnIndexList,
+            offsetSet,
+            offset,
+            totalLength);
+  }
+
+  @SuppressWarnings("squid:S107") // ignore Methods should not have too many parameters
+  public SessionDataSet(
+      String sql,
+      List<String> columnNameList,
+      List<String> columnTypeList,
+      Map<String, Integer> columnNameIndex,
+      long queryId,
+      long statementId,
+      IClientRPCService.Iface client,
+      long sessionId,
+      List<ByteBuffer> queryResult,
+      boolean ignoreTimeStamp,
+      boolean moreData,
+      ZoneId zoneId,
+      int timeFactor,
+      boolean tableModel,
+      List<Integer> columnIndex2TsBlockColumnIndexList) {
+    this(
+        sql,
+        columnNameList,
+        columnTypeList,
+        columnNameIndex,
+        queryId,
+        statementId,
+        client,
+        sessionId,
+        queryResult,
+        ignoreTimeStamp,
+        moreData,
+        zoneId,
+        timeFactor,
+        tableModel,
+        columnIndex2TsBlockColumnIndexList,
+        false,
+        0,
+        0);
   }
 
   @SuppressWarnings("squid:S107") // ignore Methods should not have too many parameters
@@ -102,7 +146,10 @@ public SessionDataSet(
       ZoneId zoneId,
       int timeFactor,
       boolean tableModel,
-      List<Integer> columnIndex2TsBlockColumnIndexList) {
+      List<Integer> columnIndex2TsBlockColumnIndexList,
+      boolean offsetSet,
+      int offset,
+      int totalLength) {
     this.ioTDBRpcDataSet =
         new IoTDBRpcDataSet(
             sql,
@@ -122,7 +169,52 @@ public SessionDataSet(
             RpcUtils.DEFAULT_TIME_FORMAT,
             timeFactor,
             tableModel,
-            columnIndex2TsBlockColumnIndexList);
+            columnIndex2TsBlockColumnIndexList,
+            offsetSet,
+            offset,
+            totalLength);
+  }
+
+  @SuppressWarnings("squid:S107") // ignore Methods should not have too many parameters
+  public SessionDataSet(
+      String sql,
+      List<String> columnNameList,
+      List<String> columnTypeList,
+      Map<String, Integer> columnNameIndex,
+      long queryId,
+      long statementId,
+      IClientRPCService.Iface client,
+      long sessionId,
+      List<ByteBuffer> queryResult,
+      boolean ignoreTimeStamp,
+      long timeout,
+      boolean moreData,
+      int fetchSize,
+      ZoneId zoneId,
+      int timeFactor,
+      boolean tableModel,
+      List<Integer> columnIndex2TsBlockColumnIndexList) {
+    this(
+        sql,
+        columnNameList,
+        columnTypeList,
+        columnNameIndex,
+        queryId,
+        statementId,
+        client,
+        sessionId,
+        queryResult,
+        ignoreTimeStamp,
+        timeout,
+        moreData,
+        fetchSize,
+        zoneId,
+        timeFactor,
+        tableModel,
+        columnIndex2TsBlockColumnIndexList,
+        false,
+        0,
+        0);
   }
 
   public int getFetchSize() {

diff --git a/iotdb-client/jdbc/src/main/java/org/apache/iotdb/jdbc/Config.java b/iotdb-client/jdbc/src/main/java/org/apache/iotdb/jdbc/Config.java
@@ -93,4 +93,6 @@ private Config() {
   public static final String SQL_DIALECT = "sql_dialect";
 
   public static final String DATABASE = "db";
+
+  public static final String ENABLE_RESULT_CHUNKING = "enable_result_chunking";
 }
diff --git a/iotdb-client/jdbc/src/main/java/org/apache/iotdb/jdbc/IoTDBConnection.java b/iotdb-client/jdbc/src/main/java/org/apache/iotdb/jdbc/IoTDBConnection.java
@@ -601,6 +601,8 @@ private void openSession() throws SQLException {
     openReq.setZoneId(getTimeZone());
     openReq.putToConfiguration(Config.VERSION, params.getVersion().toString());
     openReq.putToConfiguration(Config.SQL_DIALECT, params.getSqlDialect());
+    // this client can assemble fragmented query results, see TSFetchResultsReq#offset
+    openReq.putToConfiguration(Config.ENABLE_RESULT_CHUNKING, Boolean.TRUE.toString());
     params.getDb().ifPresent(db -> openReq.putToConfiguration(Config.DATABASE, db));
 
     TSOpenSessionResp openResp = null;

diff --git a/iotdb-client/jdbc/src/main/java/org/apache/iotdb/jdbc/IoTDBJDBCResultSet.java b/iotdb-client/jdbc/src/main/java/org/apache/iotdb/jdbc/IoTDBJDBCResultSet.java
@@ -104,7 +104,10 @@ public IoTDBJDBCResultSet(
       ZoneId zoneId,
       Charset charset,
       boolean tableModel,
-      List<Integer> columnIndex2TsBlockColumnIndexList)
+      List<Integer> columnIndex2TsBlockColumnIndexList,
+      boolean offsetSet,
+      int offset,
+      int totalLength)
       throws SQLException {
     this.ioTDBRpcDataSet =
         new IoTDBRpcDataSet(
@@ -125,7 +128,10 @@ public IoTDBJDBCResultSet(
             timeFormat,
             statement.getTimeFactor(),
             tableModel,
-            columnIndex2TsBlockColumnIndexList);
+            columnIndex2TsBlockColumnIndexList,
+            offsetSet,
+            offset,
+            totalLength);
     this.statement = statement;
     this.columnTypeList = columnTypeList;
     if (tracingInfo != null) {
@@ -135,6 +141,49 @@ public IoTDBJDBCResultSet(
     this.charset = charset;
   }
 
+  @SuppressWarnings("squid:S107") // ignore Methods should not have too many parameters
+  public IoTDBJDBCResultSet(
+      IoTDBStatement statement,
+      List<String> columnNameList,
+      List<String> columnTypeList,
+      Map<String, Integer> columnNameIndex,
+      boolean ignoreTimeStamp,
+      IClientRPCService.Iface client,
+      String sql,
+      long queryId,
+      long sessionId,
+      List<ByteBuffer> dataSet,
+      TSTracingInfo tracingInfo,
+      long timeout,
+      boolean moreData,
+      ZoneId zoneId,
+      Charset charset,
+      boolean tableModel,
+      List<Integer> columnIndex2TsBlockColumnIndexList)
+      throws SQLException {
+    this(
+        statement,
+        columnNameList,
+        columnTypeList,
+        columnNameIndex,
+        ignoreTimeStamp,
+        client,
+        sql,
+        queryId,
+        sessionId,
+        dataSet,
+        tracingInfo,
+        timeout,
+        moreData,
+        zoneId,
+        charset,
+        tableModel,
+        columnIndex2TsBlockColumnIndexList,
+        false,
+        0,
+        0);
+  }
+
   @SuppressWarnings("squid:S107") // ignore Methods should not have too many parameters
   public IoTDBJDBCResultSet(
       Statement statement,
@@ -150,7 +199,10 @@ public IoTDBJDBCResultSet(
       TSTracingInfo tracingInfo,
       long timeout,
       boolean moreData,
-      ZoneId zoneId)
+      ZoneId zoneId,
+      boolean offsetSet,
+      int offset,
+      int totalLength)
       throws SQLException {
     this.ioTDBRpcDataSet =
         new IoTDBRpcDataSet(
@@ -171,7 +223,10 @@ public IoTDBJDBCResultSet(
             timeFormat,
             ((IoTDBStatement) statement).getTimeFactor(),
             false,
-            IntStream.range(0, columnNameList.size()).boxed().collect(Collectors.toList()));
+            IntStream.range(0, columnNameList.size()).boxed().collect(Collectors.toList()),
+            offsetSet,
+            offset,
+            totalLength);
     this.statement = (IoTDBStatement) statement;
     this.columnTypeList = columnTypeList;
     if (tracingInfo != null) {
@@ -180,6 +235,43 @@ public IoTDBJDBCResultSet(
     }
   }
 
+  @SuppressWarnings("squid:S107") // ignore Methods should not have too many parameters
+  public IoTDBJDBCResultSet(
+      Statement statement,
+      List<String> columnNameList,
+      List<String> columnTypeList,
+      Map<String, Integer> columnNameIndex,
+      boolean ignoreTimeStamp,
+      IClientRPCService.Iface client,
+      String sql,
+      long queryId,
+      long sessionId,
+      List<ByteBuffer> dataSet,
+      TSTracingInfo tracingInfo,
+      long timeout,
+      boolean moreData,
+      ZoneId zoneId)
+      throws SQLException {
+    this(
+        statement,
+        columnNameList,
+        columnTypeList,
+        columnNameIndex,
+        ignoreTimeStamp,
+        client,
+        sql,
+        queryId,
+        sessionId,
+        dataSet,
+        tracingInfo,
+        timeout,
+        moreData,
+        zoneId,
+        false,
+        0,
+        0);
+  }
+
   @Override
   public boolean isWrapperFor(Class<?> iface) throws SQLException {
     throw new SQLException(Constant.METHOD_NOT_SUPPORTED);

diff --git a/iotdb-client/jdbc/src/main/java/org/apache/iotdb/jdbc/IoTDBStatement.java b/iotdb-client/jdbc/src/main/java/org/apache/iotdb/jdbc/IoTDBStatement.java
@@ -412,7 +412,10 @@ private boolean executeSQL(String sql) throws TException, SQLException {
                 zoneId,
                 charset,
                 execResp.isSetTableModel() && execResp.isTableModel(),
-                execResp.getColumnIndex2TsBlockColumnIndexList());
+                execResp.getColumnIndex2TsBlockColumnIndexList(),
+                execResp.isSetOffset(),
+                execResp.offset,
+                execResp.totalLength);
       }
       return true;
     }
@@ -549,7 +552,10 @@ private ResultSet executeQuerySQL(String sql, long timeoutInMS) throws TExceptio
               zoneId,
               charset,
               execResp.isSetTableModel() && execResp.isTableModel(),
-              execResp.getColumnIndex2TsBlockColumnIndexList());
+              execResp.getColumnIndex2TsBlockColumnIndexList(),
+              execResp.isSetOffset(),
+              execResp.offset,
+              execResp.totalLength);
     }
     return resultSet;
   }

diff --git a/iotdb-client/jdbc/src/main/java/org/apache/iotdb/jdbc/IoTDBTablePreparedStatement.java b/iotdb-client/jdbc/src/main/java/org/apache/iotdb/jdbc/IoTDBTablePreparedStatement.java
@@ -238,7 +238,10 @@ private ResultSet processQueryResult(TSExecuteStatementResp resp) throws SQLExce
               resp.isSetTableModel() && resp.isTableModel(),
               resp.getColumnIndex2TsBlockColumnIndexList() == null
                   ? null
-                  : new ArrayList<>(resp.getColumnIndex2TsBlockColumnIndexList()));
+                  : new ArrayList<>(resp.getColumnIndex2TsBlockColumnIndexList()),
+              resp.isSetOffset(),
+              resp.offset,
+              resp.totalLength);
       return resultSet;
     }
     return null;

diff --git a/iotdb-client/service-rpc/pom.xml b/iotdb-client/service-rpc/pom.xml
@@ -75,6 +75,11 @@
             <artifactId>junit</artifactId>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+            <scope>test</scope>
+        </dependency>
         <dependency>
             <groupId>org.slf4j</groupId>
             <artifactId>slf4j-api</artifactId>

diff --git a/iotdb-client/service-rpc/src/main/i18n/en/org/apache/iotdb/rpc/i18n/RpcMessages.java b/iotdb-client/service-rpc/src/main/i18n/en/org/apache/iotdb/rpc/i18n/RpcMessages.java
@@ -127,4 +127,15 @@ private RpcMessages() {}
 
   public static final String EXCEPTION_DATA_TYPE_ARG_IS_NOT_SUPPORTED_31213160 =
       "Data type %s is not supported.";
+
+  public static final String EXCEPTION_CHUNKED_RESULT_EMPTY_FRAGMENT_03A0EF39 =
+      "Empty fragment received when assembling a chunked query result";
+  public static final String
+      EXCEPTION_CHUNKED_RESULT_FRAGMENT_OFFSET_ARG_NOT_GREATER_THAN_ACCUMULATED_LENGTH_ARG_A0F032E3 =
+          "Fragment offset %d is not greater than the accumulated length %d";
+  public static final String EXCEPTION_CHUNKED_RESULT_MISSING_TOTAL_LENGTH_FOR_FIRST_FRAGMENT_1D11374F =
+      "Missing totalLength for the first fragment of a chunked TsBlock";
+  public static final String
+      EXCEPTION_CHUNKED_RESULT_ASSEMBLED_LENGTH_ARG_DOES_NOT_MATCH_TOTAL_LENGTH_ARG_925DCB15 =
+          "Assembled fragment length %d does not match the total length %d";
 }
diff --git a/iotdb-client/service-rpc/src/main/i18n/zh/org/apache/iotdb/rpc/i18n/RpcMessages.java b/iotdb-client/service-rpc/src/main/i18n/zh/org/apache/iotdb/rpc/i18n/RpcMessages.java
@@ -108,4 +108,15 @@ private RpcMessages() {}
       "通过列名 %s 获取的值为 NULL。";
 
   public static final String EXCEPTION_DATA_TYPE_ARG_IS_NOT_SUPPORTED_31213160 = "不支持数据类型 %s。";
+
+  public static final String EXCEPTION_CHUNKED_RESULT_EMPTY_FRAGMENT_03A0EF39 =
+      "拼装分片查询结果时收到空分片";
+  public static final String
+      EXCEPTION_CHUNKED_RESULT_FRAGMENT_OFFSET_ARG_NOT_GREATER_THAN_ACCUMULATED_LENGTH_ARG_A0F032E3 =
+          "分片 offset %d 不大于已累计的长度 %d";
+  public static final String EXCEPTION_CHUNKED_RESULT_MISSING_TOTAL_LENGTH_FOR_FIRST_FRAGMENT_1D11374F =
+      "分片 TsBlock 的首个分片缺少 totalLength";
+  public static final String
+      EXCEPTION_CHUNKED_RESULT_ASSEMBLED_LENGTH_ARG_DOES_NOT_MATCH_TOTAL_LENGTH_ARG_925DCB15 =
+          "拼装后的分片长度 %d 与 totalLength %d 不一致";
 }