apache · CritasWang · Feb 4, 2026 · Feb 2, 2026
diff --git a/src/UserGuide/Master/Table/API/Programming-Java-Native-API_apache.md b/src/UserGuide/Master/Table/API/Programming-Java-Native-API_apache.md
@@ -38,7 +38,7 @@ IoTDB provides a Java native client driver and a session pool management mechani
     <dependency>
       <groupId>org.apache.iotdb</groupId>
       <artifactId>iotdb-session</artifactId>
-        <!-- The version number is the same as the database version number --> 
+        <!-- The version number is the same as the database version number -->
       <version>${project.version}</version>
     </dependency>
 </dependencies>
@@ -63,6 +63,28 @@ The `ITableSession` interface defines basic operations for interacting with IoTD
 | executeQueryStatement(String sql, long timeoutInMs) | Executes a query SQL statement with a specified timeout in milliseconds. | `sql`: The SQL query statement. `timeoutInMs`: Query timeout in milliseconds. | `SessionDataSet` | `StatementExecutionException`                             |
 | close()                                             | Closes the session and releases resources.                   | None                                                         | None             | IoTDBConnectionException                                  |
 
+**Description of Object Data Type:**
+
+Since V2.0.8-beta, the `iTableSession.insert(Tablet tablet)` interface supports splitting a single Object-class file into multiple segments and writing them sequentially in order. When the column data type in the Tablet data structure is **`TSDataType.Object`**, you need to use the following method to populate the Tablet:
+
+```Java
+/*
+rowIndex: row position in the tablet
+columnIndex: column position in the tablet
+isEOF: whether the current write operation contains the last segment of the Object file
+offset: starting offset of the current write content within the Object file
+content: byte array of the current write content
+Note: When writing, ensure the total length of all segmented byte[] arrays equals the original Object size, 
+otherwise it will cause incorrect data size.
+*/
+void addValue(int rowIndex, int columnIndex, boolean isEOF, long offset, byte[] content)
+```
+
+During queries, the following four methods are supported to retrieve values:
+`Field.getStringValue`, `Field.getObjectValue`, `SessionDataSet.DataIterator.getObject`, and `SessionDataSet.DataIterator.getString`.
+All these methods return a String containing metadata in the format:
+`(Object) XX.XX KB` (where XX.XX KB represents the actual object size).
+
 #### 3.1.3 Sample Code
 
 ```Java
@@ -345,6 +367,7 @@ public class TableSessionBuilder {
 }
 ```
 
+
 > Note: When creating tables using the native API, if table or column names contain special characters or Chinese characters, do not add extra double quotes around them. Otherwise, the quotation marks will become part of the name itself.
 
 ## 4. Session Pool

diff --git a/src/UserGuide/Master/Table/API/Programming-Java-Native-API_timecho.md b/src/UserGuide/Master/Table/API/Programming-Java-Native-API_timecho.md
@@ -63,6 +63,28 @@ The `ITableSession` interface defines basic operations for interacting with IoTD
 | executeQueryStatement(String sql, long timeoutInMs) | Executes a query SQL statement with a specified timeout in milliseconds. | `sql`: The SQL query statement. `timeoutInMs`: Query timeout in milliseconds. | `SessionDataSet` | `StatementExecutionException`                             |
 | close()                                             | Closes the session and releases resources.                   | None                                                         | None             | IoTDBConnectionException                                  |
 
+**Description of Object Data Type:**
+
+Since V2.0.8-beta, the `iTableSession.insert(Tablet tablet)` interface supports splitting a single Object-class file into multiple segments and writing them sequentially in order. When the column data type in the Tablet data structure is **`TSDataType.Object`**, you need to use the following method to populate the Tablet:
+
+```Java
+/*
+rowIndex: row position in the tablet
+columnIndex: column position in the tablet
+isEOF: whether the current write operation contains the last segment of the Object file
+offset: starting offset of the current write content within the Object file
+content: byte array of the current write content
+Note: When writing, ensure the total length of all segmented byte[] arrays equals the original Object size, 
+otherwise it will cause incorrect data size.
+*/
+void addValue(int rowIndex, int columnIndex, boolean isEOF, long offset, byte[] content)
+```
+
+During queries, the following four methods are supported to retrieve values:
+`Field.getStringValue`, `Field.getObjectValue`, `SessionDataSet.DataIterator.getObject`, and `SessionDataSet.DataIterator.getString`.
+All these methods return a String containing metadata in the format:
+`(Object) XX.XX KB` (where XX.XX KB represents the actual object size).
+
 #### 3.1.3 Sample Code
 
 ```java

diff --git a/src/UserGuide/Master/Table/Background-knowledge/Data-Type.md b/src/UserGuide/Master/Table/Background-knowledge/Data-Type.md
@@ -33,6 +33,8 @@ IoTDB supports the following ten data types:
 - **TEXT** (Text data, suitable for long strings)
 - **STRING** (String data with additional statistical information for optimized queries)
 - **BLOB** (Large binary object)
+- **OBJECT** (Large Binary Object)
+  > Supported since V2.0.8-beta
 - **TIMESTAMP** (Timestamp, representing precise moments in time)
 - **DATE** (Date, storing only calendar date information)
 
@@ -41,6 +43,14 @@ The difference between **STRING** and **TEXT**:
 - **STRING** stores text data and includes additional statistical information to optimize value-filtering queries.
 - **TEXT** is suitable for storing long text strings without additional query optimization.
 
+The differences between **OBJECT** and **BLOB** types are as follows:
+
+|                      | **OBJECT**                                                                                                              | **BLOB**                             |
+|----------------------|-------------------------------------------------------------------------------------------------------------------------|--------------------------------------|
+| **Write Amplification** (Lower is better)   | Low (Write amplification factor is always 1)                                                                                   | High (Write amplification factor = 2 + number of merges) |
+| **Space Amplification** (Lower is better)  | Low (Merge & release on write)                                                                                               | High (Merge on read and release on compact) |
+| **Query Results** | When querying an OBJECT column by default, returns metadata like: `(Object) XX.XX KB`.  Actual OBJECT data storage path: `${data_dir}/object_data`. Use `READ_OBJECT` function to retrieve raw content | Directly returns raw binary content |
+
 ### 1.1 Floating-Point Precision Configuration
 
 For **FLOAT** and **DOUBLE** series using **RLE** or **TS_2DIFF** encoding, the number of decimal places can be set via the **MAX_POINT_NUMBER** attribute during series creation.
@@ -63,7 +73,7 @@ If the written data type does not match the registered data type of a series:
 The compatibility of data types is shown in the table below:  
 
 | Registered Data Type | Compatible Write Data Types            |
-| :------------------- | :------------------------------------- |
+|:---------------------|:---------------------------------------|
 | BOOLEAN              | BOOLEAN                                |
 | INT32                | INT32                                  |
 | INT64                | INT32, INT64, TIMESTAMP                |
@@ -72,6 +82,7 @@ The compatibility of data types is shown in the table below:
 | TEXT                 | TEXT, STRING                           |
 | STRING               | TEXT, STRING                           |
 | BLOB                 | TEXT, STRING, BLOB                     |
+| OBJECT               | OBJECT                                 |
 | TIMESTAMP            | INT32, INT64, TIMESTAMP                |
 | DATE                 | DATE                                   |
 

diff --git a/src/UserGuide/Master/Table/Basic-Concept/Write-Updata-Data_apache.md b/src/UserGuide/Master/Table/Basic-Concept/Write-Updata-Data_apache.md
@@ -287,7 +287,7 @@ It costs 0.014s
 
 * The source table in the `query` and the target table `table_name` are allowed to be the same table, e.g., `INSERT INTO testtb SELECT * FROM testtb`.
 * The target table **must already exist**; otherwise, the error message `550: Table 'xxx.xxx' does not exist` will be thrown.
-* The number and data types of columns returned by the query **must exactly match** those of the target table. Type conversion between compatible types is not supported currently. A type mismatch will trigger the error message `701: Insert query has mismatched column types`.
+* The number and types of query result columns must exactly match those of the target table. Object type is currently not supported, and no implicit type conversion is supported. If types mismatch, the error `701: Insert query has mismatched column types` will be raised.
 * You can specify a subset of columns in the target table, provided the following rules are met:
   * The timestamp column must be included; otherwise, the error message `701: time column can not be null` will be thrown.
   * At least one **FIELD** column must be included; otherwise, the error message `701: No Field column present` will be thrown.
@@ -302,6 +302,59 @@ It costs 0.014s
   * For more details about user permissions, refer to [Authority Management](../User-Manual/Authority-Management_apache.md).
 
 
+### 1.7 Writing Object Type
+
+To avoid oversized Object write requests, values of **Object** type can be split into segments and written sequentially. In SQL, the `to_object(isEOF, offset, content)` function must be used for value insertion.
+
+> Supported since V2.0.8-beta
+
+**Syntax:**
+
+```SQL
+INSERT INTO tableName(time, columnName) VALUES(timeValue, TO_OBJECT(isEOF, offset, content));
+```  
+
+**Parameters:**
+
+| Name    | Data Type          | Description                                                                 |
+|---------|--------------------|-----------------------------------------------------------------------------|
+| isEOF   | BOOLEAN            | Whether the current write contains the last segment of the Object          |
+| offset  | INT64              | Starting offset of the current segment within the Object                   |
+| content | Hexadecimal (HEX)  | Content of the current segment                                             |
+
+**Examples:**
+
+Add an Object-type column `s1` to table `table1`:
+
+```SQL
+ALTER TABLE table1 ADD COLUMN IF NOT EXISTS s1 OBJECT FIELD COMMENT 'object type';
+```
+
+1. **Non-segmented write**
+
+```SQL
+INSERT INTO table1(time, device_id, s1) VALUES(NOW(), 'tag1', TO_OBJECT(TRUE, 0, X'696F746462'));
+```
+
+2. **Segmented write**
+
+```SQL
+-- First write: TO_OBJECT(FALSE, 0, X'696F')
+INSERT INTO table1(time, device_id, s1) VALUES(1, 'tag1', TO_OBJECT(FALSE, 0, X'696F'));
+
+-- Second write: TO_OBJECT(FALSE, 2, X'7464')
+INSERT INTO table1(time, device_id, s1) VALUES(1, 'tag1', TO_OBJECT(FALSE, 2, X'7464'));
+
+-- Third write: TO_OBJECT(TRUE, 4, X'62')
+INSERT INTO table1(time, device_id, s1) VALUES(1, 'tag1', TO_OBJECT(TRUE, 4, X'62'));
+```
+
+**Notes:**
+
+1. If only partial segments of an Object are written, querying the column will return `NULL`. Data becomes accessible only after all segments are successfully written.
+2. During segmented writes, if the `offset` of the current write does not match the current size of the Object, the write operation will fail.
+3. If `offset=0` is used after partial writes, the existing content will be overwritten with new data.
+
 
 ## 2. Data Updates
 

diff --git a/src/UserGuide/Master/Table/Basic-Concept/Write-Updata-Data_timecho.md b/src/UserGuide/Master/Table/Basic-Concept/Write-Updata-Data_timecho.md
@@ -287,7 +287,7 @@ It costs 0.014s
 
 * The source table in the `query` and the target table `table_name` are allowed to be the same table, e.g., `INSERT INTO testtb SELECT * FROM testtb`.
 * The target table **must already exist**; otherwise, the error message `550: Table 'xxx.xxx' does not exist` will be thrown.
-* The number and data types of columns returned by the query **must exactly match** those of the target table. Type conversion between compatible types is not supported currently. A type mismatch will trigger the error message `701: Insert query has mismatched column types`.
+* The number and types of query result columns must exactly match those of the target table. Object type is currently not supported, and no implicit type conversion is supported. If types mismatch, the error `701: Insert query has mismatched column types` will be raised.
 * You can specify a subset of columns in the target table, provided the following rules are met:
   * The timestamp column must be included; otherwise, the error message `701: time column can not be null` will be thrown.
   * At least one **FIELD** column must be included; otherwise, the error message `701: No Field column present` will be thrown.
@@ -301,7 +301,59 @@ It costs 0.014s
   * The `WRITE` permission on the target table.
   * For more details about user permissions, refer to [Authority Management](../User-Manual/Authority-Management_timecho.md).
 
+
+### 1.7 Writing Object Type
 
+To avoid oversized Object write requests, values of **Object** type can be split into segments and written sequentially. In SQL, the `to_object(isEOF, offset, content)` function must be used for value insertion.
+
+> Supported since V2.0.8-beta
+
+**Syntax:**
+
+```SQL
+INSERT INTO tableName(time, columnName) VALUES(timeValue, TO_OBJECT(isEOF, offset, content));
+```  
+
+**Parameters:**
+
+| Name    | Data Type          | Description                                                                 |
+|---------|--------------------|-----------------------------------------------------------------------------|
+| isEOF   | BOOLEAN            | Whether the current write contains the last segment of the Object          |
+| offset  | INT64              | Starting offset of the current segment within the Object                   |
+| content | Hexadecimal (HEX)  | Content of the current segment                                             |
+
+**Examples:**
+
+Add an Object-type column `s1` to table `table1`:
+
+```SQL
+ALTER TABLE table1 ADD COLUMN IF NOT EXISTS s1 OBJECT FIELD COMMENT 'object type';
+```
+
+1. **Non-segmented write**
+
+```SQL
+INSERT INTO table1(time, device_id, s1) VALUES(NOW(), 'tag1', TO_OBJECT(TRUE, 0, X'696F746462'));
+```
+
+2. **Segmented write**
+
+```SQL
+-- First write: TO_OBJECT(FALSE, 0, X'696F')
+INSERT INTO table1(time, device_id, s1) VALUES(1, 'tag1', TO_OBJECT(FALSE, 0, X'696F'));
+
+-- Second write: TO_OBJECT(FALSE, 2, X'7464')
+INSERT INTO table1(time, device_id, s1) VALUES(1, 'tag1', TO_OBJECT(FALSE, 2, X'7464'));
+
+-- Third write: TO_OBJECT(TRUE, 4, X'62')
+INSERT INTO table1(time, device_id, s1) VALUES(1, 'tag1', TO_OBJECT(TRUE, 4, X'62'));
+```
+
+**Notes:**
+
+1. If only partial segments of an Object are written, querying the column will return `NULL`. Data becomes accessible only after all segments are successfully written.
+2. During segmented writes, if the `offset` of the current write does not match the current size of the Object, the write operation will fail.
+3. If `offset=0` is used after partial writes, the existing content will be overwritten with new data.
 
 ## 2. Data Updates