You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iotdb.apache.org by cr...@apache.org on 2026/07/20 06:14:32 UTC
(iotdb-docs) branch docs/rust-client-sdk created (now 11550eb1)
This is an automated email from the ASF dual-hosted git repository.
CritasWang pushed a change to branch docs/rust-client-sdk
in repository https://gitbox.apache.org/repos/asf/iotdb-docs.git
at 11550eb1 docs: refresh Rust client docs for the official apache/iotdb-client-rust SDK
This branch includes the following new commits:
new 11550eb1 docs: refresh Rust client docs for the official apache/iotdb-client-rust SDK
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
(iotdb-docs) 01/01: docs: refresh Rust client docs for the official apache/iotdb-client-rust SDK
Posted by cr...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
CritasWang pushed a commit to branch docs/rust-client-sdk
in repository https://gitbox.apache.org/repos/asf/iotdb-docs.git
commit 11550eb162059c4098041431147ccf2bd6507370
Author: CritasWang <cr...@outlook.com>
AuthorDate: Mon Jul 20 14:14:21 2026 +0800
docs: refresh Rust client docs for the official apache/iotdb-client-rust SDK
- Rewrite the tree-model Rust API page (latest + Master/Tree, en + zh):
the old page documented hand-generating Thrift stubs; it now covers the
official SDK (installation, quick start, session pool, TLS/compression).
- Add the table-model Rust API page (latest-Table + Master/Table, en + zh).
- Add the Rust entry to the V2.0.x Table sidebars (en + zh); the Tree
sidebars already had it.
---
src/.vuepress/sidebar/V2.0.x/en-Table.ts | 1 +
src/.vuepress/sidebar/V2.0.x/zh-Table.ts | 1 +
.../API/Programming-Rust-Native-API_apache.md | 134 ++++++++++
.../Master/Tree/API/Programming-Rust-Native-API.md | 267 +++++++++-----------
.../API/Programming-Rust-Native-API_apache.md | 134 ++++++++++
.../latest/API/Programming-Rust-Native-API.md | 267 +++++++++-----------
.../API/Programming-Rust-Native-API_apache.md | 133 ++++++++++
.../Master/Tree/API/Programming-Rust-Native-API.md | 277 +++++++++------------
.../API/Programming-Rust-Native-API_apache.md | 133 ++++++++++
.../latest/API/Programming-Rust-Native-API.md | 277 +++++++++------------
10 files changed, 1026 insertions(+), 598 deletions(-)
diff --git a/src/.vuepress/sidebar/V2.0.x/en-Table.ts b/src/.vuepress/sidebar/V2.0.x/en-Table.ts
index bf72d970..4312ed68 100644
--- a/src/.vuepress/sidebar/V2.0.x/en-Table.ts
+++ b/src/.vuepress/sidebar/V2.0.x/en-Table.ts
@@ -184,6 +184,7 @@ export const enSidebar = {
{ text: 'C++ Native API', link: 'Programming-Cpp-Native-API_apache' },
{ text: 'GO Native API', link: 'Programming-Go-Native-API_apache' },
{ text: 'C# Native API', link: 'Programming-CSharp-Native-API_apache' },
+ { text: 'Rust Native API', link: 'Programming-Rust-Native-API_apache' },
{ text: 'JDBC', link: 'Programming-JDBC_apache' },
{ text: 'MQTT Protocol', link: 'Programming-MQTT_apache' },
{ text: 'RESTAPI V1 ', link: 'RestAPI-V1_apache' },
diff --git a/src/.vuepress/sidebar/V2.0.x/zh-Table.ts b/src/.vuepress/sidebar/V2.0.x/zh-Table.ts
index 3a0364a2..41897721 100644
--- a/src/.vuepress/sidebar/V2.0.x/zh-Table.ts
+++ b/src/.vuepress/sidebar/V2.0.x/zh-Table.ts
@@ -183,6 +183,7 @@ export const zhSidebar = {
{ text: 'C++原生接口', link: 'Programming-Cpp-Native-API_apache' },
{ text: 'GO原生接口', link: 'Programming-Go-Native-API_apache' },
{ text: 'C#原生接口', link: 'Programming-CSharp-Native-API_apache' },
+ { text: 'Rust原生接口', link: 'Programming-Rust-Native-API_apache' },
{ text: 'JDBC', link: 'Programming-JDBC_apache' },
{ text: 'MQTT协议', link: 'Programming-MQTT_apache' },
{ text: 'RESTAPI V1 ', link: 'RestServiceV1_apache' },
diff --git a/src/UserGuide/Master/Table/API/Programming-Rust-Native-API_apache.md b/src/UserGuide/Master/Table/API/Programming-Rust-Native-API_apache.md
new file mode 100644
index 00000000..fa8252ff
--- /dev/null
+++ b/src/UserGuide/Master/Table/API/Programming-Rust-Native-API_apache.md
@@ -0,0 +1,134 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+# Rust Native API
+
+Apache IoTDB provides an official Rust client SDK: [apache/iotdb-client-rust](https://github.com/apache/iotdb-client-rust). It speaks the Thrift RPC protocol (default port 6667). This document covers the **table model** (`TableSession` / `TableSessionPool`, relational SQL dialect); the tree model is documented separately.
+
+## 1. Requirements
+
+- Rust 1.75+
+- Apache IoTDB 2.x — see [COMPATIBILITY.md](https://github.com/apache/iotdb-client-rust/blob/main/COMPATIBILITY.md) for the full server version matrix
+
+## 2. Installation
+
+Once published to crates.io:
+
+```toml
+[dependencies]
+iotdb-client-rust = "0.1"
+```
+
+Until then, use a git dependency:
+
+```toml
+[dependencies]
+iotdb-client = { git = "https://github.com/apache/iotdb-client-rust" }
+```
+
+The import name is `iotdb_client` in both cases.
+
+## 3. Quick start
+
+```rust
+use iotdb_client::{ColumnCategory, Result, TSDataType, TableSession, Tablet, Value};
+
+fn main() -> Result<()> {
+ let mut session = TableSession::builder()
+ .node_urls(&["127.0.0.1:6667"])?
+ .username("root")
+ .password("root")
+ .build()?;
+
+ session.execute_non_query("CREATE DATABASE IF NOT EXISTS demo")?;
+ session.execute_non_query("USE demo")?;
+ session.execute_non_query(
+ "CREATE TABLE IF NOT EXISTS sensors (device_id STRING TAG, temperature DOUBLE FIELD)",
+ )?;
+
+ // Column-major tablet write. columnCategories must NOT include TIME —
+ // the time column is implicit.
+ let mut tablet = Tablet::new_table(
+ "sensors",
+ vec!["device_id".into(), "temperature".into()],
+ vec![TSDataType::String, TSDataType::Double],
+ vec![ColumnCategory::Tag, ColumnCategory::Field],
+ )?;
+ tablet.add_row(
+ 1_720_000_000_000,
+ vec![
+ Some(Value::String("dev-1".into())),
+ Some(Value::Double(21.5)),
+ ],
+ )?;
+ session.insert(&tablet)?;
+
+ // Query with row iteration; the dataset borrows the session until dropped.
+ {
+ let mut dataset =
+ session.execute_query("SELECT time, device_id, temperature FROM sensors")?;
+ while let Some(row) = dataset.next_row()? {
+ println!("{:?}", row.values);
+ }
+ }
+
+ session.execute_non_query("DROP DATABASE demo")?;
+ session.close()
+}
+```
+
+## 4. Session pool
+
+`TableSessionPool` is the thread-safe pool variant for concurrent workloads; `acquire()` returns an RAII guard that releases the session back to the pool on drop. See the runnable [`session_pool` example](https://github.com/apache/iotdb-client-rust/blob/main/examples/session_pool.rs).
+
+## 5. TLS & RPC compression
+
+**RPC compression** (the Thrift compact protocol) must match the server setting `dn_rpc_thrift_compression_enable` (default `false`):
+
+```rust
+let mut session = TableSession::builder()
+ .node_urls(&["127.0.0.1:6667"])?
+ .enable_rpc_compression(true)
+ .build()?;
+```
+
+**TLS** is behind the `tls` cargo feature:
+
+```toml
+iotdb-client-rust = { version = "0.1", features = ["tls"] }
+```
+
+```rust
+let mut session = TableSession::builder()
+ .node_urls(&["127.0.0.1:6667"])?
+ .use_ssl(true)
+ .ca_cert_path("ca.pem")
+ .build()?;
+```
+
+## 6. Examples
+
+Full runnable examples live in the repository's [`examples/`](https://github.com/apache/iotdb-client-rust/tree/main/examples) directory:
+
+```sh
+cargo run --example table_session
+cargo run --example session_pool
+```
diff --git a/src/UserGuide/Master/Tree/API/Programming-Rust-Native-API.md b/src/UserGuide/Master/Tree/API/Programming-Rust-Native-API.md
index f3fcacf4..e4a8b0a0 100644
--- a/src/UserGuide/Master/Tree/API/Programming-Rust-Native-API.md
+++ b/src/UserGuide/Master/Tree/API/Programming-Rust-Native-API.md
@@ -21,168 +21,147 @@
# Rust Native API
-IoTDB uses Thrift as a cross language RPC framework, so access to IoTDB can be achieved through the interface provided by Thrift.
-This document will introduce how to generate a native Rust interface that can access IoTDB.
+Apache IoTDB provides an official Rust client SDK: [apache/iotdb-client-rust](https://github.com/apache/iotdb-client-rust). It speaks the Thrift RPC protocol (default port 6667) and supports both IoTDB data models:
-## 1. Dependents
+- **Tree model** — `Session` / `SessionPool`: device/timeseries paths (`root.sg.d1.s1`), covered in this document
+- **Table model** — `TableSession` / `TableSessionPool`: relational SQL dialect
- * JDK >= 1.8
- * Rust >= 1.0.0
- * thrift 0.14.1
- * Linux、Macos or like unix
- * Windows+bash
+## 1. Requirements
-Thrift (0.14.1 or higher) must be installed to compile Thrift files into Rust code. The following is the official installation tutorial, and in the end, you should receive a Thrift executable file.
+- Rust 1.75+
+- Apache IoTDB 2.x — see [COMPATIBILITY.md](https://github.com/apache/iotdb-client-rust/blob/main/COMPATIBILITY.md) for the full server version matrix
-```
-http://thrift.apache.org/docs/install/
-```
+## 2. Installation
-## 2. Compile the Thrift library and generate the Rust native interface
-
-1. Find the `pom.xml` file in the root directory of the IoTDB source code folder.
-2. Open the `pom.xml` file and find the following content:
- ```xml
- <execution>
- <id>generate-thrift-sources-python</id>
- <phase>generate-sources</phase>
- <goals>
- <goal>compile</goal>
- </goals>
- <configuration>
- <generator>py</generator>
- <outputDirectory>${project.build.directory}/generated-sources-python/</outputDirectory>
- </configuration>
- </execution>
- ```
-3. Duplicate this block and change the `id`, `generator` and `outputDirectory` to this:
- ```xml
- <execution>
- <id>generate-thrift-sources-rust</id>
- <phase>generate-sources</phase>
- <goals>
- <goal>compile</goal>
- </goals>
- <configuration>
- <generator>rs</generator>
- <outputDirectory>${project.build.directory}/generated-sources-rust/</outputDirectory>
- </configuration>
- </execution>
- ```
-4. In the root directory of the IoTDB source code folder，run `mvn clean generate-sources`.
-
-This command will automatically delete the files in `iotdb/iotdb-protocol/thrift/target` and `iotdb/iotdb-protocol/thrift-commons/target`, and repopulate the folder with the newly generated files.
-The newly generated Rust sources will be located in `iotdb/iotdb-protocol/thrift/target/generated-sources-rust` in the various modules of the `iotdb-protocol` module.
-
-## 3. Using the Rust native interface
-
-Copy `iotdb/iotdb-protocol/thrift/target/generated-sources-rust/` and `iotdb/iotdb-protocol/thrift-commons/target/generated-sources-rust/` into your project。
-
-## 4. RPC interface
+Once published to crates.io:
+```toml
+[dependencies]
+iotdb-client-rust = "0.1"
```
-// open a session
-TSOpenSessionResp openSession(1:TSOpenSessionReq req);
-
-// close a session
-TSStatus closeSession(1:TSCloseSessionReq req);
-
-// run an SQL statement in batch
-TSExecuteStatementResp executeStatement(1:TSExecuteStatementReq req);
-
-// execute SQL statement in batch
-TSStatus executeBatchStatement(1:TSExecuteBatchStatementReq req);
-
-// execute query SQL statement
-TSExecuteStatementResp executeQueryStatement(1:TSExecuteStatementReq req);
-
-// execute insert, delete and update SQL statement
-TSExecuteStatementResp executeUpdateStatement(1:TSExecuteStatementReq req);
-
-// fetch next query result
-TSFetchResultsResp fetchResults(1:TSFetchResultsReq req)
-
-// fetch meta data
-TSFetchMetadataResp fetchMetadata(1:TSFetchMetadataReq req)
-
-// cancel a query
-TSStatus cancelOperation(1:TSCancelOperationReq req);
-
-// close a query dataset
-TSStatus closeOperation(1:TSCloseOperationReq req);
-
-// get time zone
-TSGetTimeZoneResp getTimeZone(1:i64 sessionId);
-
-// set time zone
-TSStatus setTimeZone(1:TSSetTimeZoneReq req);
-
-// get server's properties
-ServerProperties getProperties();
-
-// CREATE DATABASE
-TSStatus setStorageGroup(1:i64 sessionId, 2:string storageGroup);
-// create timeseries
-TSStatus createTimeseries(1:TSCreateTimeseriesReq req);
+Until then, use a git dependency:
-// create multi timeseries
-TSStatus createMultiTimeseries(1:TSCreateMultiTimeseriesReq req);
-
-// delete timeseries
-TSStatus deleteTimeseries(1:i64 sessionId, 2:list<string> path)
-
-// delete sttorage groups
-TSStatus deleteStorageGroups(1:i64 sessionId, 2:list<string> storageGroup);
-
-// insert record
-TSStatus insertRecord(1:TSInsertRecordReq req);
-
-// insert record in string format
-TSStatus insertStringRecord(1:TSInsertStringRecordReq req);
-
-// insert tablet
-TSStatus insertTablet(1:TSInsertTabletReq req);
-
-// insert tablets in batch
-TSStatus insertTablets(1:TSInsertTabletsReq req);
-
-// insert records in batch
-TSStatus insertRecords(1:TSInsertRecordsReq req);
-
-// insert records of one device
-TSStatus insertRecordsOfOneDevice(1:TSInsertRecordsOfOneDeviceReq req);
+```toml
+[dependencies]
+iotdb-client = { git = "https://github.com/apache/iotdb-client-rust" }
+```
-// insert records in batch as string format
-TSStatus insertStringRecords(1:TSInsertStringRecordsReq req);
+The import name is `iotdb_client` in both cases.
+
+## 3. Quick start
+
+```rust
+use iotdb_client::{Result, Session, SessionConfig, TSDataType, Tablet, Value};
+
+fn main() -> Result<()> {
+ let config = SessionConfig::default().with_node_urls(&["127.0.0.1:6667"])?;
+ let mut session = Session::new(config);
+ session.open()?;
+
+ session.execute_non_query("CREATE DATABASE root.demo")?;
+ session.execute_non_query(
+ "CREATE TIMESERIES root.demo.d1.temperature WITH DATATYPE=DOUBLE, ENCODING=PLAIN",
+ )?;
+
+ // Batch write via a column-major tablet (nulls allowed).
+ let mut tablet = Tablet::new(
+ "root.demo.d1",
+ vec!["temperature".into()],
+ vec![TSDataType::Double],
+ )?;
+ tablet.add_row(1_720_000_000_000, vec![Some(Value::Double(21.5))])?;
+ tablet.add_row(1_720_000_001_000, vec![None])?; // null cell
+ session.insert_tablet(&tablet)?;
+
+ // Or write a single row via insertRecord (aligned variants and
+ // multi-row insert_records / insert_records_of_one_device also exist).
+ session.insert_record(
+ "root.demo.d1",
+ 1_720_000_002_000,
+ vec!["temperature".into()],
+ &[Value::Double(22.0)],
+ false, // is_aligned
+ )?;
+
+ // Query with row iteration; the dataset borrows the session until dropped.
+ {
+ let mut dataset = session.execute_query("SELECT temperature FROM root.demo.d1")?;
+ while let Some(row) = dataset.next_row()? {
+ println!("ts={:?} values={:?}", row.timestamp, row.values);
+ }
+ }
+
+ session.execute_non_query("DELETE DATABASE root.demo")?;
+ session.close()
+}
+```
-// test the latency of innsert tablet，caution：no data will be inserted, only for test latency
-TSStatus testInsertTablet(1:TSInsertTabletReq req);
+## 4. Session pool
+
+`SessionPool` is a thread-safe pool for concurrent workloads. `acquire()` returns an RAII guard that releases the session back to the pool on drop:
+
+```rust
+use std::sync::Arc;
+use iotdb_client::{Result, SessionPool, SessionPoolConfig};
+
+fn main() -> Result<()> {
+ let config = SessionPoolConfig {
+ max_size: 4,
+ ..SessionPoolConfig::default()
+ }
+ .with_node_urls(&["127.0.0.1:6667"])?;
+ let pool = Arc::new(SessionPool::new(config)?);
+
+ let handles: Vec<_> = (0..4)
+ .map(|_| {
+ let pool = Arc::clone(&pool);
+ std::thread::spawn(move || -> Result<()> {
+ let mut session = pool.acquire()?;
+ session.execute_non_query("SHOW DATABASES")?;
+ Ok(())
+ })
+ })
+ .collect();
+ for handle in handles {
+ handle.join().expect("thread panicked")?;
+ }
+
+ pool.close();
+ Ok(())
+}
+```
-// test the latency of innsert tablets，caution：no data will be inserted, only for test latency
-TSStatus testInsertTablets(1:TSInsertTabletsReq req);
+## 5. TLS & RPC compression
-// test the latency of innsert record，caution：no data will be inserted, only for test latency
-TSStatus testInsertRecord(1:TSInsertRecordReq req);
+**RPC compression** (the Thrift compact protocol) must match the server setting `dn_rpc_thrift_compression_enable` (default `false`):
-// test the latency of innsert record in string format，caution：no data will be inserted, only for test latency
-TSStatus testInsertStringRecord(1:TSInsertStringRecordReq req);
+```rust
+let config = SessionConfig { enable_rpc_compression: true, ..Default::default() };
+```
-// test the latency of innsert records，caution：no data will be inserted, only for test latency
-TSStatus testInsertRecords(1:TSInsertRecordsReq req);
+**TLS** is behind the `tls` cargo feature:
-// test the latency of innsert records of one device，caution：no data will be inserted, only for test latency
-TSStatus testInsertRecordsOfOneDevice(1:TSInsertRecordsOfOneDeviceReq req);
+```toml
+iotdb-client-rust = { version = "0.1", features = ["tls"] }
+```
-// test the latency of innsert records in string formate，caution：no data will be inserted, only for test latency
-TSStatus testInsertStringRecords(1:TSInsertStringRecordsReq req);
+```rust
+let config = SessionConfig {
+ use_ssl: true,
+ ca_cert_path: Some("ca.pem".into()), // trust a private CA / self-signed cert
+ accept_invalid_certs: false, // true skips verification (tests only!)
+ domain_override: None, // SNI/validation hostname when connecting by IP
+ ..Default::default()
+};
+```
-// delete data
-TSStatus deleteData(1:TSDeleteDataReq req);
+## 6. Examples
-// execute raw data query
-TSExecuteStatementResp executeRawDataQuery(1:TSRawDataQueryReq req);
+Full runnable examples live in the repository's [`examples/`](https://github.com/apache/iotdb-client-rust/tree/main/examples) directory:
-// request a statement id from server
-i64 requestStatementId(1:i64 sessionId);
+```sh
+cargo run --example tree_session
+cargo run --example table_session
+cargo run --example session_pool
```
diff --git a/src/UserGuide/latest-Table/API/Programming-Rust-Native-API_apache.md b/src/UserGuide/latest-Table/API/Programming-Rust-Native-API_apache.md
new file mode 100644
index 00000000..fa8252ff
--- /dev/null
+++ b/src/UserGuide/latest-Table/API/Programming-Rust-Native-API_apache.md
@@ -0,0 +1,134 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+# Rust Native API
+
+Apache IoTDB provides an official Rust client SDK: [apache/iotdb-client-rust](https://github.com/apache/iotdb-client-rust). It speaks the Thrift RPC protocol (default port 6667). This document covers the **table model** (`TableSession` / `TableSessionPool`, relational SQL dialect); the tree model is documented separately.
+
+## 1. Requirements
+
+- Rust 1.75+
+- Apache IoTDB 2.x — see [COMPATIBILITY.md](https://github.com/apache/iotdb-client-rust/blob/main/COMPATIBILITY.md) for the full server version matrix
+
+## 2. Installation
+
+Once published to crates.io:
+
+```toml
+[dependencies]
+iotdb-client-rust = "0.1"
+```
+
+Until then, use a git dependency:
+
+```toml
+[dependencies]
+iotdb-client = { git = "https://github.com/apache/iotdb-client-rust" }
+```
+
+The import name is `iotdb_client` in both cases.
+
+## 3. Quick start
+
+```rust
+use iotdb_client::{ColumnCategory, Result, TSDataType, TableSession, Tablet, Value};
+
+fn main() -> Result<()> {
+ let mut session = TableSession::builder()
+ .node_urls(&["127.0.0.1:6667"])?
+ .username("root")
+ .password("root")
+ .build()?;
+
+ session.execute_non_query("CREATE DATABASE IF NOT EXISTS demo")?;
+ session.execute_non_query("USE demo")?;
+ session.execute_non_query(
+ "CREATE TABLE IF NOT EXISTS sensors (device_id STRING TAG, temperature DOUBLE FIELD)",
+ )?;
+
+ // Column-major tablet write. columnCategories must NOT include TIME —
+ // the time column is implicit.
+ let mut tablet = Tablet::new_table(
+ "sensors",
+ vec!["device_id".into(), "temperature".into()],
+ vec![TSDataType::String, TSDataType::Double],
+ vec![ColumnCategory::Tag, ColumnCategory::Field],
+ )?;
+ tablet.add_row(
+ 1_720_000_000_000,
+ vec![
+ Some(Value::String("dev-1".into())),
+ Some(Value::Double(21.5)),
+ ],
+ )?;
+ session.insert(&tablet)?;
+
+ // Query with row iteration; the dataset borrows the session until dropped.
+ {
+ let mut dataset =
+ session.execute_query("SELECT time, device_id, temperature FROM sensors")?;
+ while let Some(row) = dataset.next_row()? {
+ println!("{:?}", row.values);
+ }
+ }
+
+ session.execute_non_query("DROP DATABASE demo")?;
+ session.close()
+}
+```
+
+## 4. Session pool
+
+`TableSessionPool` is the thread-safe pool variant for concurrent workloads; `acquire()` returns an RAII guard that releases the session back to the pool on drop. See the runnable [`session_pool` example](https://github.com/apache/iotdb-client-rust/blob/main/examples/session_pool.rs).
+
+## 5. TLS & RPC compression
+
+**RPC compression** (the Thrift compact protocol) must match the server setting `dn_rpc_thrift_compression_enable` (default `false`):
+
+```rust
+let mut session = TableSession::builder()
+ .node_urls(&["127.0.0.1:6667"])?
+ .enable_rpc_compression(true)
+ .build()?;
+```
+
+**TLS** is behind the `tls` cargo feature:
+
+```toml
+iotdb-client-rust = { version = "0.1", features = ["tls"] }
+```
+
+```rust
+let mut session = TableSession::builder()
+ .node_urls(&["127.0.0.1:6667"])?
+ .use_ssl(true)
+ .ca_cert_path("ca.pem")
+ .build()?;
+```
+
+## 6. Examples
+
+Full runnable examples live in the repository's [`examples/`](https://github.com/apache/iotdb-client-rust/tree/main/examples) directory:
+
+```sh
+cargo run --example table_session
+cargo run --example session_pool
+```
diff --git a/src/UserGuide/latest/API/Programming-Rust-Native-API.md b/src/UserGuide/latest/API/Programming-Rust-Native-API.md
index f3fcacf4..e4a8b0a0 100644
--- a/src/UserGuide/latest/API/Programming-Rust-Native-API.md
+++ b/src/UserGuide/latest/API/Programming-Rust-Native-API.md
@@ -21,168 +21,147 @@
# Rust Native API
-IoTDB uses Thrift as a cross language RPC framework, so access to IoTDB can be achieved through the interface provided by Thrift.
-This document will introduce how to generate a native Rust interface that can access IoTDB.
+Apache IoTDB provides an official Rust client SDK: [apache/iotdb-client-rust](https://github.com/apache/iotdb-client-rust). It speaks the Thrift RPC protocol (default port 6667) and supports both IoTDB data models:
-## 1. Dependents
+- **Tree model** — `Session` / `SessionPool`: device/timeseries paths (`root.sg.d1.s1`), covered in this document
+- **Table model** — `TableSession` / `TableSessionPool`: relational SQL dialect
- * JDK >= 1.8
- * Rust >= 1.0.0
- * thrift 0.14.1
- * Linux、Macos or like unix
- * Windows+bash
+## 1. Requirements
-Thrift (0.14.1 or higher) must be installed to compile Thrift files into Rust code. The following is the official installation tutorial, and in the end, you should receive a Thrift executable file.
+- Rust 1.75+
+- Apache IoTDB 2.x — see [COMPATIBILITY.md](https://github.com/apache/iotdb-client-rust/blob/main/COMPATIBILITY.md) for the full server version matrix
-```
-http://thrift.apache.org/docs/install/
-```
+## 2. Installation
-## 2. Compile the Thrift library and generate the Rust native interface
-
-1. Find the `pom.xml` file in the root directory of the IoTDB source code folder.
-2. Open the `pom.xml` file and find the following content:
- ```xml
- <execution>
- <id>generate-thrift-sources-python</id>
- <phase>generate-sources</phase>
- <goals>
- <goal>compile</goal>
- </goals>
- <configuration>
- <generator>py</generator>
- <outputDirectory>${project.build.directory}/generated-sources-python/</outputDirectory>
- </configuration>
- </execution>
- ```
-3. Duplicate this block and change the `id`, `generator` and `outputDirectory` to this:
- ```xml
- <execution>
- <id>generate-thrift-sources-rust</id>
- <phase>generate-sources</phase>
- <goals>
- <goal>compile</goal>
- </goals>
- <configuration>
- <generator>rs</generator>
- <outputDirectory>${project.build.directory}/generated-sources-rust/</outputDirectory>
- </configuration>
- </execution>
- ```
-4. In the root directory of the IoTDB source code folder，run `mvn clean generate-sources`.
-
-This command will automatically delete the files in `iotdb/iotdb-protocol/thrift/target` and `iotdb/iotdb-protocol/thrift-commons/target`, and repopulate the folder with the newly generated files.
-The newly generated Rust sources will be located in `iotdb/iotdb-protocol/thrift/target/generated-sources-rust` in the various modules of the `iotdb-protocol` module.
-
-## 3. Using the Rust native interface
-
-Copy `iotdb/iotdb-protocol/thrift/target/generated-sources-rust/` and `iotdb/iotdb-protocol/thrift-commons/target/generated-sources-rust/` into your project。
-
-## 4. RPC interface
+Once published to crates.io:
+```toml
+[dependencies]
+iotdb-client-rust = "0.1"
```
-// open a session
-TSOpenSessionResp openSession(1:TSOpenSessionReq req);
-
-// close a session
-TSStatus closeSession(1:TSCloseSessionReq req);
-
-// run an SQL statement in batch
-TSExecuteStatementResp executeStatement(1:TSExecuteStatementReq req);
-
-// execute SQL statement in batch
-TSStatus executeBatchStatement(1:TSExecuteBatchStatementReq req);
-
-// execute query SQL statement
-TSExecuteStatementResp executeQueryStatement(1:TSExecuteStatementReq req);
-
-// execute insert, delete and update SQL statement
-TSExecuteStatementResp executeUpdateStatement(1:TSExecuteStatementReq req);
-
-// fetch next query result
-TSFetchResultsResp fetchResults(1:TSFetchResultsReq req)
-
-// fetch meta data
-TSFetchMetadataResp fetchMetadata(1:TSFetchMetadataReq req)
-
-// cancel a query
-TSStatus cancelOperation(1:TSCancelOperationReq req);
-
-// close a query dataset
-TSStatus closeOperation(1:TSCloseOperationReq req);
-
-// get time zone
-TSGetTimeZoneResp getTimeZone(1:i64 sessionId);
-
-// set time zone
-TSStatus setTimeZone(1:TSSetTimeZoneReq req);
-
-// get server's properties
-ServerProperties getProperties();
-
-// CREATE DATABASE
-TSStatus setStorageGroup(1:i64 sessionId, 2:string storageGroup);
-// create timeseries
-TSStatus createTimeseries(1:TSCreateTimeseriesReq req);
+Until then, use a git dependency:
-// create multi timeseries
-TSStatus createMultiTimeseries(1:TSCreateMultiTimeseriesReq req);
-
-// delete timeseries
-TSStatus deleteTimeseries(1:i64 sessionId, 2:list<string> path)
-
-// delete sttorage groups
-TSStatus deleteStorageGroups(1:i64 sessionId, 2:list<string> storageGroup);
-
-// insert record
-TSStatus insertRecord(1:TSInsertRecordReq req);
-
-// insert record in string format
-TSStatus insertStringRecord(1:TSInsertStringRecordReq req);
-
-// insert tablet
-TSStatus insertTablet(1:TSInsertTabletReq req);
-
-// insert tablets in batch
-TSStatus insertTablets(1:TSInsertTabletsReq req);
-
-// insert records in batch
-TSStatus insertRecords(1:TSInsertRecordsReq req);
-
-// insert records of one device
-TSStatus insertRecordsOfOneDevice(1:TSInsertRecordsOfOneDeviceReq req);
+```toml
+[dependencies]
+iotdb-client = { git = "https://github.com/apache/iotdb-client-rust" }
+```
-// insert records in batch as string format
-TSStatus insertStringRecords(1:TSInsertStringRecordsReq req);
+The import name is `iotdb_client` in both cases.
+
+## 3. Quick start
+
+```rust
+use iotdb_client::{Result, Session, SessionConfig, TSDataType, Tablet, Value};
+
+fn main() -> Result<()> {
+ let config = SessionConfig::default().with_node_urls(&["127.0.0.1:6667"])?;
+ let mut session = Session::new(config);
+ session.open()?;
+
+ session.execute_non_query("CREATE DATABASE root.demo")?;
+ session.execute_non_query(
+ "CREATE TIMESERIES root.demo.d1.temperature WITH DATATYPE=DOUBLE, ENCODING=PLAIN",
+ )?;
+
+ // Batch write via a column-major tablet (nulls allowed).
+ let mut tablet = Tablet::new(
+ "root.demo.d1",
+ vec!["temperature".into()],
+ vec![TSDataType::Double],
+ )?;
+ tablet.add_row(1_720_000_000_000, vec![Some(Value::Double(21.5))])?;
+ tablet.add_row(1_720_000_001_000, vec![None])?; // null cell
+ session.insert_tablet(&tablet)?;
+
+ // Or write a single row via insertRecord (aligned variants and
+ // multi-row insert_records / insert_records_of_one_device also exist).
+ session.insert_record(
+ "root.demo.d1",
+ 1_720_000_002_000,
+ vec!["temperature".into()],
+ &[Value::Double(22.0)],
+ false, // is_aligned
+ )?;
+
+ // Query with row iteration; the dataset borrows the session until dropped.
+ {
+ let mut dataset = session.execute_query("SELECT temperature FROM root.demo.d1")?;
+ while let Some(row) = dataset.next_row()? {
+ println!("ts={:?} values={:?}", row.timestamp, row.values);
+ }
+ }
+
+ session.execute_non_query("DELETE DATABASE root.demo")?;
+ session.close()
+}
+```
-// test the latency of innsert tablet，caution：no data will be inserted, only for test latency
-TSStatus testInsertTablet(1:TSInsertTabletReq req);
+## 4. Session pool
+
+`SessionPool` is a thread-safe pool for concurrent workloads. `acquire()` returns an RAII guard that releases the session back to the pool on drop:
+
+```rust
+use std::sync::Arc;
+use iotdb_client::{Result, SessionPool, SessionPoolConfig};
+
+fn main() -> Result<()> {
+ let config = SessionPoolConfig {
+ max_size: 4,
+ ..SessionPoolConfig::default()
+ }
+ .with_node_urls(&["127.0.0.1:6667"])?;
+ let pool = Arc::new(SessionPool::new(config)?);
+
+ let handles: Vec<_> = (0..4)
+ .map(|_| {
+ let pool = Arc::clone(&pool);
+ std::thread::spawn(move || -> Result<()> {
+ let mut session = pool.acquire()?;
+ session.execute_non_query("SHOW DATABASES")?;
+ Ok(())
+ })
+ })
+ .collect();
+ for handle in handles {
+ handle.join().expect("thread panicked")?;
+ }
+
+ pool.close();
+ Ok(())
+}
+```
-// test the latency of innsert tablets，caution：no data will be inserted, only for test latency
-TSStatus testInsertTablets(1:TSInsertTabletsReq req);
+## 5. TLS & RPC compression
-// test the latency of innsert record，caution：no data will be inserted, only for test latency
-TSStatus testInsertRecord(1:TSInsertRecordReq req);
+**RPC compression** (the Thrift compact protocol) must match the server setting `dn_rpc_thrift_compression_enable` (default `false`):
-// test the latency of innsert record in string format，caution：no data will be inserted, only for test latency
-TSStatus testInsertStringRecord(1:TSInsertStringRecordReq req);
+```rust
+let config = SessionConfig { enable_rpc_compression: true, ..Default::default() };
+```
-// test the latency of innsert records，caution：no data will be inserted, only for test latency
-TSStatus testInsertRecords(1:TSInsertRecordsReq req);
+**TLS** is behind the `tls` cargo feature:
-// test the latency of innsert records of one device，caution：no data will be inserted, only for test latency
-TSStatus testInsertRecordsOfOneDevice(1:TSInsertRecordsOfOneDeviceReq req);
+```toml
+iotdb-client-rust = { version = "0.1", features = ["tls"] }
+```
-// test the latency of innsert records in string formate，caution：no data will be inserted, only for test latency
-TSStatus testInsertStringRecords(1:TSInsertStringRecordsReq req);
+```rust
+let config = SessionConfig {
+ use_ssl: true,
+ ca_cert_path: Some("ca.pem".into()), // trust a private CA / self-signed cert
+ accept_invalid_certs: false, // true skips verification (tests only!)
+ domain_override: None, // SNI/validation hostname when connecting by IP
+ ..Default::default()
+};
+```
-// delete data
-TSStatus deleteData(1:TSDeleteDataReq req);
+## 6. Examples
-// execute raw data query
-TSExecuteStatementResp executeRawDataQuery(1:TSRawDataQueryReq req);
+Full runnable examples live in the repository's [`examples/`](https://github.com/apache/iotdb-client-rust/tree/main/examples) directory:
-// request a statement id from server
-i64 requestStatementId(1:i64 sessionId);
+```sh
+cargo run --example tree_session
+cargo run --example table_session
+cargo run --example session_pool
```
diff --git a/src/zh/UserGuide/Master/Table/API/Programming-Rust-Native-API_apache.md b/src/zh/UserGuide/Master/Table/API/Programming-Rust-Native-API_apache.md
new file mode 100644
index 00000000..651fcc47
--- /dev/null
+++ b/src/zh/UserGuide/Master/Table/API/Programming-Rust-Native-API_apache.md
@@ -0,0 +1,133 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+# Rust 原生接口
+
+Apache IoTDB 提供官方 Rust 客户端 SDK：[apache/iotdb-client-rust](https://github.com/apache/iotdb-client-rust)，基于 Thrift RPC 协议（默认端口 6667）。本文档介绍**表模型**（`TableSession` / `TableSessionPool`，关系型 SQL 方言）；树模型另有单独文档。
+
+## 1. 环境要求
+
+- Rust 1.75+
+- Apache IoTDB 2.x — 完整的服务端版本兼容矩阵见 [COMPATIBILITY.md](https://github.com/apache/iotdb-client-rust/blob/main/COMPATIBILITY.md)
+
+## 2. 安装
+
+发布到 crates.io 后：
+
+```toml
+[dependencies]
+iotdb-client-rust = "0.1"
+```
+
+在此之前，可使用 git 依赖：
+
+```toml
+[dependencies]
+iotdb-client = { git = "https://github.com/apache/iotdb-client-rust" }
+```
+
+两种方式的导入名均为 `iotdb_client`。
+
+## 3. 快速上手
+
+```rust
+use iotdb_client::{ColumnCategory, Result, TSDataType, TableSession, Tablet, Value};
+
+fn main() -> Result<()> {
+ let mut session = TableSession::builder()
+ .node_urls(&["127.0.0.1:6667"])?
+ .username("root")
+ .password("root")
+ .build()?;
+
+ session.execute_non_query("CREATE DATABASE IF NOT EXISTS demo")?;
+ session.execute_non_query("USE demo")?;
+ session.execute_non_query(
+ "CREATE TABLE IF NOT EXISTS sensors (device_id STRING TAG, temperature DOUBLE FIELD)",
+ )?;
+
+ // 列式 tablet 写入。columnCategories 不包含 TIME —— 时间列是隐式的。
+ let mut tablet = Tablet::new_table(
+ "sensors",
+ vec!["device_id".into(), "temperature".into()],
+ vec![TSDataType::String, TSDataType::Double],
+ vec![ColumnCategory::Tag, ColumnCategory::Field],
+ )?;
+ tablet.add_row(
+ 1_720_000_000_000,
+ vec![
+ Some(Value::String("dev-1".into())),
+ Some(Value::Double(21.5)),
+ ],
+ )?;
+ session.insert(&tablet)?;
+
+ // 逐行迭代查询结果；dataset 在 drop 前借用 session。
+ {
+ let mut dataset =
+ session.execute_query("SELECT time, device_id, temperature FROM sensors")?;
+ while let Some(row) = dataset.next_row()? {
+ println!("{:?}", row.values);
+ }
+ }
+
+ session.execute_non_query("DROP DATABASE demo")?;
+ session.close()
+}
+```
+
+## 4. 会话池
+
+`TableSessionPool` 是面向并发场景的线程安全会话池；`acquire()` 返回 RAII guard，drop 时自动将会话归还池中。可参考可运行示例 [`session_pool`](https://github.com/apache/iotdb-client-rust/blob/main/examples/session_pool.rs)。
+
+## 5. TLS 与 RPC 压缩
+
+**RPC 压缩**（即 Thrift compact 协议）必须与服务端配置 `dn_rpc_thrift_compression_enable`（默认 `false`）保持一致：
+
+```rust
+let mut session = TableSession::builder()
+ .node_urls(&["127.0.0.1:6667"])?
+ .enable_rpc_compression(true)
+ .build()?;
+```
+
+**TLS** 通过 `tls` cargo feature 启用：
+
+```toml
+iotdb-client-rust = { version = "0.1", features = ["tls"] }
+```
+
+```rust
+let mut session = TableSession::builder()
+ .node_urls(&["127.0.0.1:6667"])?
+ .use_ssl(true)
+ .ca_cert_path("ca.pem")
+ .build()?;
+```
+
+## 6. 示例
+
+完整可运行示例见仓库 [`examples/`](https://github.com/apache/iotdb-client-rust/tree/main/examples) 目录：
+
+```sh
+cargo run --example table_session
+cargo run --example session_pool
+```
diff --git a/src/zh/UserGuide/Master/Tree/API/Programming-Rust-Native-API.md b/src/zh/UserGuide/Master/Tree/API/Programming-Rust-Native-API.md
index 32de0b42..36ee6c95 100644
--- a/src/zh/UserGuide/Master/Tree/API/Programming-Rust-Native-API.md
+++ b/src/zh/UserGuide/Master/Tree/API/Programming-Rust-Native-API.md
@@ -19,182 +19,149 @@
-->
+# Rust 原生接口
-# Rust
+Apache IoTDB 提供官方 Rust 客户端 SDK：[apache/iotdb-client-rust](https://github.com/apache/iotdb-client-rust)。它基于 Thrift RPC 协议（默认端口 6667），同时支持 IoTDB 的两种数据模型：
-IoTDB 使用 Thrift 作为跨语言的 RPC 框架，因此可以通过 Thrift 提供的接口来实现对 IoTDB 的访问。本文档将介绍如何生成可访问 IoTDB 的原生 Rust 接口。
+- **树模型** — `Session` / `SessionPool`：设备/时间序列路径（`root.sg.d1.s1`），本文档主要介绍此模型
+- **表模型** — `TableSession` / `TableSessionPool`：关系型 SQL 方言
+## 1. 环境要求
-## 1. 依赖
+- Rust 1.75+
+- Apache IoTDB 2.x — 完整的服务端版本兼容矩阵见 [COMPATIBILITY.md](https://github.com/apache/iotdb-client-rust/blob/main/COMPATIBILITY.md)
- * JDK >= 1.8
- * Rust >= 1.0.0
- * thrift 0.14.1
- * Linux、Macos 或其他类 unix 系统
- * Windows+bash (下载 IoTDB Go client 需要 git ，通过 WSL、cygwin、Git Bash 任意一种方式均可)
+## 2. 安装
-必须安装 thrift（0.14.1 或更高版本）才能将 thrift 文件编译为 Rust 代码。下面是官方的安装教程，最终，您应该得到一个 thrift 可执行文件。
+发布到 crates.io 后：
-```
-http://thrift.apache.org/docs/install/
+```toml
+[dependencies]
+iotdb-client-rust = "0.1"
```
+在此之前，可使用 git 依赖：
-## 2. 编译 thrift 库，生成 Rust 原生接口
-
-1. 在 IoTDB 源代码文件夹的根目录中找到 pom.xml 文件。
-2. 打开 pom.xml 文件，找到以下内容：
-
-```xml
-<execution>
- <id>generate-thrift-sources-java</id>
- <phase>generate-sources</phase>
- <goals>
- <goal>compile</goal>
- </goals>
- <configuration>
- <generator>java</generator>
- <thriftExecutable>${thrift.exec.absolute.path}</thriftExecutable>
- <thriftSourceRoot>${basedir}/src/main/thrift</thriftSourceRoot>
- </configuration>
-</execution>
-```
-3. 参考该设置，在 pom.xml 文件中添加以下内容，用来生成 Rust 的原生接口：
-
-```xml
-<execution>
- <id>generate-thrift-sources-rust</id>
- <phase>generate-sources</phase>
- <goals>
- <goal>compile</goal>
- </goals>
- <configuration>
- <generator>rs</generator>
- <thriftExecutable>${thrift.exec.absolute.path}</thriftExecutable>
- <thriftSourceRoot>${basedir}/src/main/thrift</thriftSourceRoot>
- <includes>**/common.thrift,**/client.thrift</includes>
- <outputDirectory>${project.build.directory}/generated-sources-rust</outputDirectory>
- </configuration>
-</execution>
+```toml
+[dependencies]
+iotdb-client = { git = "https://github.com/apache/iotdb-client-rust" }
```
-4. 在 IoTDB 源代码文件夹的根目录下，运行`mvn clean generate-sources`，
-
-这个指令将自动删除`iotdb/iotdb-protocol/thrift/target` 和 `iotdb/iotdb-protocol/thrift-commons/target`中的文件，并使用新生成的 thrift 文件重新填充该文件夹。
-
-这个文件夹在 git 中会被忽略，并且**永远不应该被推到 git 中！**
-
-**注意**不要将`iotdb/iotdb-protocol/thrift/target` 和 `iotdb/iotdb-protocol/thrift-commons/target`上传到 git 仓库中 ！
-
-## 3. 使用 Rust 原生接口
-
-将 `iotdb/iotdb-protocol/thrift/target/generated-sources-rust/` 和 `iotdb/iotdb-protocol/thrift-commons/target/generated-sources-rust/` 中的文件复制到您的项目中，即可使用。
-
-## 4. 支持的 rpc 接口
-
+两种方式的导入名均为 `iotdb_client`。
+
+## 3. 快速上手
+
+```rust
+use iotdb_client::{Result, Session, SessionConfig, TSDataType, Tablet, Value};
+
+fn main() -> Result<()> {
+ let config = SessionConfig::default().with_node_urls(&["127.0.0.1:6667"])?;
+ let mut session = Session::new(config);
+ session.open()?;
+
+ session.execute_non_query("CREATE DATABASE root.demo")?;
+ session.execute_non_query(
+ "CREATE TIMESERIES root.demo.d1.temperature WITH DATATYPE=DOUBLE, ENCODING=PLAIN",
+ )?;
+
+ // 通过列式 tablet 批量写入（允许 null）。
+ let mut tablet = Tablet::new(
+ "root.demo.d1",
+ vec!["temperature".into()],
+ vec![TSDataType::Double],
+ )?;
+ tablet.add_row(1_720_000_000_000, vec![Some(Value::Double(21.5))])?;
+ tablet.add_row(1_720_000_001_000, vec![None])?; // null 单元格
+ session.insert_tablet(&tablet)?;
+
+ // 或通过 insertRecord 写入单行（还提供 aligned 变体以及
+ // 多行的 insert_records / insert_records_of_one_device）。
+ session.insert_record(
+ "root.demo.d1",
+ 1_720_000_002_000,
+ vec!["temperature".into()],
+ &[Value::Double(22.0)],
+ false, // is_aligned
+ )?;
+
+ // 逐行迭代查询结果；dataset 在 drop 前借用 session。
+ {
+ let mut dataset = session.execute_query("SELECT temperature FROM root.demo.d1")?;
+ while let Some(row) = dataset.next_row()? {
+ println!("ts={:?} values={:?}", row.timestamp, row.values);
+ }
+ }
+
+ session.execute_non_query("DELETE DATABASE root.demo")?;
+ session.close()
+}
```
-// 打开一个 session
-TSOpenSessionResp openSession(1:TSOpenSessionReq req);
-
-// 关闭一个 session
-TSStatus closeSession(1:TSCloseSessionReq req);
-
-// 执行一条 SQL 语句
-TSExecuteStatementResp executeStatement(1:TSExecuteStatementReq req);
-
-// 批量执行 SQL 语句
-TSStatus executeBatchStatement(1:TSExecuteBatchStatementReq req);
-
-// 执行查询 SQL 语句
-TSExecuteStatementResp executeQueryStatement(1:TSExecuteStatementReq req);
-
-// 执行插入、删除 SQL 语句
-TSExecuteStatementResp executeUpdateStatement(1:TSExecuteStatementReq req);
-
-// 向服务器取下一批查询结果
-TSFetchResultsResp fetchResults(1:TSFetchResultsReq req)
-
-// 获取元数据
-TSFetchMetadataResp fetchMetadata(1:TSFetchMetadataReq req)
-
-// 取消某次查询操作
-TSStatus cancelOperation(1:TSCancelOperationReq req);
-
-// 关闭查询操作数据集，释放资源
-TSStatus closeOperation(1:TSCloseOperationReq req);
-
-// 获取时区信息
-TSGetTimeZoneResp getTimeZone(1:i64 sessionId);
-// 设置时区
-TSStatus setTimeZone(1:TSSetTimeZoneReq req);
-
-// 获取服务端配置
-ServerProperties getProperties();
-
-// 设置 database
-TSStatus setStorageGroup(1:i64 sessionId, 2:string storageGroup);
-
-// 创建时间序列
-TSStatus createTimeseries(1:TSCreateTimeseriesReq req);
-
-// 创建多条时间序列
-TSStatus createMultiTimeseries(1:TSCreateMultiTimeseriesReq req);
-
-// 删除时间序列
-TSStatus deleteTimeseries(1:i64 sessionId, 2:list<string> path)
-
-// 删除 database
-TSStatus deleteStorageGroups(1:i64 sessionId, 2:list<string> storageGroup);
-
-// 按行插入数据
-TSStatus insertRecord(1:TSInsertRecordReq req);
-
-// 按 String 格式插入一条数据
-TSStatus insertStringRecord(1:TSInsertStringRecordReq req);
-
-// 按列插入数据
-TSStatus insertTablet(1:TSInsertTabletReq req);
-
-// 按列批量插入数据
-TSStatus insertTablets(1:TSInsertTabletsReq req);
-
-// 按行批量插入数据
-TSStatus insertRecords(1:TSInsertRecordsReq req);
-
-// 按行批量插入同属于某个设备的数据
-TSStatus insertRecordsOfOneDevice(1:TSInsertRecordsOfOneDeviceReq req);
-
-// 按 String 格式批量按行插入数据
-TSStatus insertStringRecords(1:TSInsertStringRecordsReq req);
-
-// 测试按列插入数据的延迟，注意：该接口不真实插入数据，只用来测试网络延迟
-TSStatus testInsertTablet(1:TSInsertTabletReq req);
+## 4. 会话池
+
+`SessionPool` 是线程安全的会话池，适用于并发场景。`acquire()` 返回 RAII guard，drop 时自动将会话归还池中：
+
+```rust
+use std::sync::Arc;
+use iotdb_client::{Result, SessionPool, SessionPoolConfig};
+
+fn main() -> Result<()> {
+ let config = SessionPoolConfig {
+ max_size: 4,
+ ..SessionPoolConfig::default()
+ }
+ .with_node_urls(&["127.0.0.1:6667"])?;
+ let pool = Arc::new(SessionPool::new(config)?);
+
+ let handles: Vec<_> = (0..4)
+ .map(|_| {
+ let pool = Arc::clone(&pool);
+ std::thread::spawn(move || -> Result<()> {
+ let mut session = pool.acquire()?;
+ session.execute_non_query("SHOW DATABASES")?;
+ Ok(())
+ })
+ })
+ .collect();
+ for handle in handles {
+ handle.join().expect("thread panicked")?;
+ }
+
+ pool.close();
+ Ok(())
+}
+```
-// 测试批量按列插入数据的延迟，注意：该接口不真实插入数据，只用来测试网络延迟
-TSStatus testInsertTablets(1:TSInsertTabletsReq req);
+## 5. TLS 与 RPC 压缩
-// 测试按行插入数据的延迟，注意：该接口不真实插入数据，只用来测试网络延迟
-TSStatus testInsertRecord(1:TSInsertRecordReq req);
+**RPC 压缩**（即 Thrift compact 协议）必须与服务端配置 `dn_rpc_thrift_compression_enable`（默认 `false`）保持一致：
-// 测试按 String 格式按行插入数据的延迟，注意：该接口不真实插入数据，只用来测试网络延迟
-TSStatus testInsertStringRecord(1:TSInsertStringRecordReq req);
+```rust
+let config = SessionConfig { enable_rpc_compression: true, ..Default::default() };
+```
-// 测试按行插入数据的延迟，注意：该接口不真实插入数据，只用来测试网络延迟
-TSStatus testInsertRecords(1:TSInsertRecordsReq req);
+**TLS** 通过 `tls` cargo feature 启用：
-// 测试按行批量插入同属于某个设备的数据的延迟，注意：该接口不真实插入数据，只用来测试网络延迟
-TSStatus testInsertRecordsOfOneDevice(1:TSInsertRecordsOfOneDeviceReq req);
+```toml
+iotdb-client-rust = { version = "0.1", features = ["tls"] }
+```
-// 测试按 String 格式批量按行插入数据的延迟，注意：该接口不真实插入数据，只用来测试网络延迟
-TSStatus testInsertStringRecords(1:TSInsertStringRecordsReq req);
+```rust
+let config = SessionConfig {
+ use_ssl: true,
+ ca_cert_path: Some("ca.pem".into()), // 信任私有 CA / 自签名证书
+ accept_invalid_certs: false, // true 跳过证书校验（仅限测试！）
+ domain_override: None, // 按 IP 连接时指定 SNI/校验主机名
+ ..Default::default()
+};
+```
-// 删除数据
-TSStatus deleteData(1:TSDeleteDataReq req);
+## 6. 示例
-// 执行原始数据查询
-TSExecuteStatementResp executeRawDataQuery(1:TSRawDataQueryReq req);
+完整可运行示例见仓库 [`examples/`](https://github.com/apache/iotdb-client-rust/tree/main/examples) 目录：
-// 向服务器申请一个查询语句 ID
-i64 requestStatementId(1:i64 sessionId);
+```sh
+cargo run --example tree_session
+cargo run --example table_session
+cargo run --example session_pool
```
diff --git a/src/zh/UserGuide/latest-Table/API/Programming-Rust-Native-API_apache.md b/src/zh/UserGuide/latest-Table/API/Programming-Rust-Native-API_apache.md
new file mode 100644
index 00000000..651fcc47
--- /dev/null
+++ b/src/zh/UserGuide/latest-Table/API/Programming-Rust-Native-API_apache.md
@@ -0,0 +1,133 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+# Rust 原生接口
+
+Apache IoTDB 提供官方 Rust 客户端 SDK：[apache/iotdb-client-rust](https://github.com/apache/iotdb-client-rust)，基于 Thrift RPC 协议（默认端口 6667）。本文档介绍**表模型**（`TableSession` / `TableSessionPool`，关系型 SQL 方言）；树模型另有单独文档。
+
+## 1. 环境要求
+
+- Rust 1.75+
+- Apache IoTDB 2.x — 完整的服务端版本兼容矩阵见 [COMPATIBILITY.md](https://github.com/apache/iotdb-client-rust/blob/main/COMPATIBILITY.md)
+
+## 2. 安装
+
+发布到 crates.io 后：
+
+```toml
+[dependencies]
+iotdb-client-rust = "0.1"
+```
+
+在此之前，可使用 git 依赖：
+
+```toml
+[dependencies]
+iotdb-client = { git = "https://github.com/apache/iotdb-client-rust" }
+```
+
+两种方式的导入名均为 `iotdb_client`。
+
+## 3. 快速上手
+
+```rust
+use iotdb_client::{ColumnCategory, Result, TSDataType, TableSession, Tablet, Value};
+
+fn main() -> Result<()> {
+ let mut session = TableSession::builder()
+ .node_urls(&["127.0.0.1:6667"])?
+ .username("root")
+ .password("root")
+ .build()?;
+
+ session.execute_non_query("CREATE DATABASE IF NOT EXISTS demo")?;
+ session.execute_non_query("USE demo")?;
+ session.execute_non_query(
+ "CREATE TABLE IF NOT EXISTS sensors (device_id STRING TAG, temperature DOUBLE FIELD)",
+ )?;
+
+ // 列式 tablet 写入。columnCategories 不包含 TIME —— 时间列是隐式的。
+ let mut tablet = Tablet::new_table(
+ "sensors",
+ vec!["device_id".into(), "temperature".into()],
+ vec![TSDataType::String, TSDataType::Double],
+ vec![ColumnCategory::Tag, ColumnCategory::Field],
+ )?;
+ tablet.add_row(
+ 1_720_000_000_000,
+ vec![
+ Some(Value::String("dev-1".into())),
+ Some(Value::Double(21.5)),
+ ],
+ )?;
+ session.insert(&tablet)?;
+
+ // 逐行迭代查询结果；dataset 在 drop 前借用 session。
+ {
+ let mut dataset =
+ session.execute_query("SELECT time, device_id, temperature FROM sensors")?;
+ while let Some(row) = dataset.next_row()? {
+ println!("{:?}", row.values);
+ }
+ }
+
+ session.execute_non_query("DROP DATABASE demo")?;
+ session.close()
+}
+```
+
+## 4. 会话池
+
+`TableSessionPool` 是面向并发场景的线程安全会话池；`acquire()` 返回 RAII guard，drop 时自动将会话归还池中。可参考可运行示例 [`session_pool`](https://github.com/apache/iotdb-client-rust/blob/main/examples/session_pool.rs)。
+
+## 5. TLS 与 RPC 压缩
+
+**RPC 压缩**（即 Thrift compact 协议）必须与服务端配置 `dn_rpc_thrift_compression_enable`（默认 `false`）保持一致：
+
+```rust
+let mut session = TableSession::builder()
+ .node_urls(&["127.0.0.1:6667"])?
+ .enable_rpc_compression(true)
+ .build()?;
+```
+
+**TLS** 通过 `tls` cargo feature 启用：
+
+```toml
+iotdb-client-rust = { version = "0.1", features = ["tls"] }
+```
+
+```rust
+let mut session = TableSession::builder()
+ .node_urls(&["127.0.0.1:6667"])?
+ .use_ssl(true)
+ .ca_cert_path("ca.pem")
+ .build()?;
+```
+
+## 6. 示例
+
+完整可运行示例见仓库 [`examples/`](https://github.com/apache/iotdb-client-rust/tree/main/examples) 目录：
+
+```sh
+cargo run --example table_session
+cargo run --example session_pool
+```
diff --git a/src/zh/UserGuide/latest/API/Programming-Rust-Native-API.md b/src/zh/UserGuide/latest/API/Programming-Rust-Native-API.md
index 32de0b42..36ee6c95 100644
--- a/src/zh/UserGuide/latest/API/Programming-Rust-Native-API.md
+++ b/src/zh/UserGuide/latest/API/Programming-Rust-Native-API.md
@@ -19,182 +19,149 @@
-->
+# Rust 原生接口
-# Rust
+Apache IoTDB 提供官方 Rust 客户端 SDK：[apache/iotdb-client-rust](https://github.com/apache/iotdb-client-rust)。它基于 Thrift RPC 协议（默认端口 6667），同时支持 IoTDB 的两种数据模型：
-IoTDB 使用 Thrift 作为跨语言的 RPC 框架，因此可以通过 Thrift 提供的接口来实现对 IoTDB 的访问。本文档将介绍如何生成可访问 IoTDB 的原生 Rust 接口。
+- **树模型** — `Session` / `SessionPool`：设备/时间序列路径（`root.sg.d1.s1`），本文档主要介绍此模型
+- **表模型** — `TableSession` / `TableSessionPool`：关系型 SQL 方言
+## 1. 环境要求
-## 1. 依赖
+- Rust 1.75+
+- Apache IoTDB 2.x — 完整的服务端版本兼容矩阵见 [COMPATIBILITY.md](https://github.com/apache/iotdb-client-rust/blob/main/COMPATIBILITY.md)
- * JDK >= 1.8
- * Rust >= 1.0.0
- * thrift 0.14.1
- * Linux、Macos 或其他类 unix 系统
- * Windows+bash (下载 IoTDB Go client 需要 git ，通过 WSL、cygwin、Git Bash 任意一种方式均可)
+## 2. 安装
-必须安装 thrift（0.14.1 或更高版本）才能将 thrift 文件编译为 Rust 代码。下面是官方的安装教程，最终，您应该得到一个 thrift 可执行文件。
+发布到 crates.io 后：
-```
-http://thrift.apache.org/docs/install/
+```toml
+[dependencies]
+iotdb-client-rust = "0.1"
```
+在此之前，可使用 git 依赖：
-## 2. 编译 thrift 库，生成 Rust 原生接口
-
-1. 在 IoTDB 源代码文件夹的根目录中找到 pom.xml 文件。
-2. 打开 pom.xml 文件，找到以下内容：
-
-```xml
-<execution>
- <id>generate-thrift-sources-java</id>
- <phase>generate-sources</phase>
- <goals>
- <goal>compile</goal>
- </goals>
- <configuration>
- <generator>java</generator>
- <thriftExecutable>${thrift.exec.absolute.path}</thriftExecutable>
- <thriftSourceRoot>${basedir}/src/main/thrift</thriftSourceRoot>
- </configuration>
-</execution>
-```
-3. 参考该设置，在 pom.xml 文件中添加以下内容，用来生成 Rust 的原生接口：
-
-```xml
-<execution>
- <id>generate-thrift-sources-rust</id>
- <phase>generate-sources</phase>
- <goals>
- <goal>compile</goal>
- </goals>
- <configuration>
- <generator>rs</generator>
- <thriftExecutable>${thrift.exec.absolute.path}</thriftExecutable>
- <thriftSourceRoot>${basedir}/src/main/thrift</thriftSourceRoot>
- <includes>**/common.thrift,**/client.thrift</includes>
- <outputDirectory>${project.build.directory}/generated-sources-rust</outputDirectory>
- </configuration>
-</execution>
+```toml
+[dependencies]
+iotdb-client = { git = "https://github.com/apache/iotdb-client-rust" }
```
-4. 在 IoTDB 源代码文件夹的根目录下，运行`mvn clean generate-sources`，
-
-这个指令将自动删除`iotdb/iotdb-protocol/thrift/target` 和 `iotdb/iotdb-protocol/thrift-commons/target`中的文件，并使用新生成的 thrift 文件重新填充该文件夹。
-
-这个文件夹在 git 中会被忽略，并且**永远不应该被推到 git 中！**
-
-**注意**不要将`iotdb/iotdb-protocol/thrift/target` 和 `iotdb/iotdb-protocol/thrift-commons/target`上传到 git 仓库中 ！
-
-## 3. 使用 Rust 原生接口
-
-将 `iotdb/iotdb-protocol/thrift/target/generated-sources-rust/` 和 `iotdb/iotdb-protocol/thrift-commons/target/generated-sources-rust/` 中的文件复制到您的项目中，即可使用。
-
-## 4. 支持的 rpc 接口
-
+两种方式的导入名均为 `iotdb_client`。
+
+## 3. 快速上手
+
+```rust
+use iotdb_client::{Result, Session, SessionConfig, TSDataType, Tablet, Value};
+
+fn main() -> Result<()> {
+ let config = SessionConfig::default().with_node_urls(&["127.0.0.1:6667"])?;
+ let mut session = Session::new(config);
+ session.open()?;
+
+ session.execute_non_query("CREATE DATABASE root.demo")?;
+ session.execute_non_query(
+ "CREATE TIMESERIES root.demo.d1.temperature WITH DATATYPE=DOUBLE, ENCODING=PLAIN",
+ )?;
+
+ // 通过列式 tablet 批量写入（允许 null）。
+ let mut tablet = Tablet::new(
+ "root.demo.d1",
+ vec!["temperature".into()],
+ vec![TSDataType::Double],
+ )?;
+ tablet.add_row(1_720_000_000_000, vec![Some(Value::Double(21.5))])?;
+ tablet.add_row(1_720_000_001_000, vec![None])?; // null 单元格
+ session.insert_tablet(&tablet)?;
+
+ // 或通过 insertRecord 写入单行（还提供 aligned 变体以及
+ // 多行的 insert_records / insert_records_of_one_device）。
+ session.insert_record(
+ "root.demo.d1",
+ 1_720_000_002_000,
+ vec!["temperature".into()],
+ &[Value::Double(22.0)],
+ false, // is_aligned
+ )?;
+
+ // 逐行迭代查询结果；dataset 在 drop 前借用 session。
+ {
+ let mut dataset = session.execute_query("SELECT temperature FROM root.demo.d1")?;
+ while let Some(row) = dataset.next_row()? {
+ println!("ts={:?} values={:?}", row.timestamp, row.values);
+ }
+ }
+
+ session.execute_non_query("DELETE DATABASE root.demo")?;
+ session.close()
+}
```
-// 打开一个 session
-TSOpenSessionResp openSession(1:TSOpenSessionReq req);
-
-// 关闭一个 session
-TSStatus closeSession(1:TSCloseSessionReq req);
-
-// 执行一条 SQL 语句
-TSExecuteStatementResp executeStatement(1:TSExecuteStatementReq req);
-
-// 批量执行 SQL 语句
-TSStatus executeBatchStatement(1:TSExecuteBatchStatementReq req);
-
-// 执行查询 SQL 语句
-TSExecuteStatementResp executeQueryStatement(1:TSExecuteStatementReq req);
-
-// 执行插入、删除 SQL 语句
-TSExecuteStatementResp executeUpdateStatement(1:TSExecuteStatementReq req);
-
-// 向服务器取下一批查询结果
-TSFetchResultsResp fetchResults(1:TSFetchResultsReq req)
-
-// 获取元数据
-TSFetchMetadataResp fetchMetadata(1:TSFetchMetadataReq req)
-
-// 取消某次查询操作
-TSStatus cancelOperation(1:TSCancelOperationReq req);
-
-// 关闭查询操作数据集，释放资源
-TSStatus closeOperation(1:TSCloseOperationReq req);
-
-// 获取时区信息
-TSGetTimeZoneResp getTimeZone(1:i64 sessionId);
-// 设置时区
-TSStatus setTimeZone(1:TSSetTimeZoneReq req);
-
-// 获取服务端配置
-ServerProperties getProperties();
-
-// 设置 database
-TSStatus setStorageGroup(1:i64 sessionId, 2:string storageGroup);
-
-// 创建时间序列
-TSStatus createTimeseries(1:TSCreateTimeseriesReq req);
-
-// 创建多条时间序列
-TSStatus createMultiTimeseries(1:TSCreateMultiTimeseriesReq req);
-
-// 删除时间序列
-TSStatus deleteTimeseries(1:i64 sessionId, 2:list<string> path)
-
-// 删除 database
-TSStatus deleteStorageGroups(1:i64 sessionId, 2:list<string> storageGroup);
-
-// 按行插入数据
-TSStatus insertRecord(1:TSInsertRecordReq req);
-
-// 按 String 格式插入一条数据
-TSStatus insertStringRecord(1:TSInsertStringRecordReq req);
-
-// 按列插入数据
-TSStatus insertTablet(1:TSInsertTabletReq req);
-
-// 按列批量插入数据
-TSStatus insertTablets(1:TSInsertTabletsReq req);
-
-// 按行批量插入数据
-TSStatus insertRecords(1:TSInsertRecordsReq req);
-
-// 按行批量插入同属于某个设备的数据
-TSStatus insertRecordsOfOneDevice(1:TSInsertRecordsOfOneDeviceReq req);
-
-// 按 String 格式批量按行插入数据
-TSStatus insertStringRecords(1:TSInsertStringRecordsReq req);
-
-// 测试按列插入数据的延迟，注意：该接口不真实插入数据，只用来测试网络延迟
-TSStatus testInsertTablet(1:TSInsertTabletReq req);
+## 4. 会话池
+
+`SessionPool` 是线程安全的会话池，适用于并发场景。`acquire()` 返回 RAII guard，drop 时自动将会话归还池中：
+
+```rust
+use std::sync::Arc;
+use iotdb_client::{Result, SessionPool, SessionPoolConfig};
+
+fn main() -> Result<()> {
+ let config = SessionPoolConfig {
+ max_size: 4,
+ ..SessionPoolConfig::default()
+ }
+ .with_node_urls(&["127.0.0.1:6667"])?;
+ let pool = Arc::new(SessionPool::new(config)?);
+
+ let handles: Vec<_> = (0..4)
+ .map(|_| {
+ let pool = Arc::clone(&pool);
+ std::thread::spawn(move || -> Result<()> {
+ let mut session = pool.acquire()?;
+ session.execute_non_query("SHOW DATABASES")?;
+ Ok(())
+ })
+ })
+ .collect();
+ for handle in handles {
+ handle.join().expect("thread panicked")?;
+ }
+
+ pool.close();
+ Ok(())
+}
+```
-// 测试批量按列插入数据的延迟，注意：该接口不真实插入数据，只用来测试网络延迟
-TSStatus testInsertTablets(1:TSInsertTabletsReq req);
+## 5. TLS 与 RPC 压缩
-// 测试按行插入数据的延迟，注意：该接口不真实插入数据，只用来测试网络延迟
-TSStatus testInsertRecord(1:TSInsertRecordReq req);
+**RPC 压缩**（即 Thrift compact 协议）必须与服务端配置 `dn_rpc_thrift_compression_enable`（默认 `false`）保持一致：
-// 测试按 String 格式按行插入数据的延迟，注意：该接口不真实插入数据，只用来测试网络延迟
-TSStatus testInsertStringRecord(1:TSInsertStringRecordReq req);
+```rust
+let config = SessionConfig { enable_rpc_compression: true, ..Default::default() };
+```
-// 测试按行插入数据的延迟，注意：该接口不真实插入数据，只用来测试网络延迟
-TSStatus testInsertRecords(1:TSInsertRecordsReq req);
+**TLS** 通过 `tls` cargo feature 启用：
-// 测试按行批量插入同属于某个设备的数据的延迟，注意：该接口不真实插入数据，只用来测试网络延迟
-TSStatus testInsertRecordsOfOneDevice(1:TSInsertRecordsOfOneDeviceReq req);
+```toml
+iotdb-client-rust = { version = "0.1", features = ["tls"] }
+```
-// 测试按 String 格式批量按行插入数据的延迟，注意：该接口不真实插入数据，只用来测试网络延迟
-TSStatus testInsertStringRecords(1:TSInsertStringRecordsReq req);
+```rust
+let config = SessionConfig {
+ use_ssl: true,
+ ca_cert_path: Some("ca.pem".into()), // 信任私有 CA / 自签名证书
+ accept_invalid_certs: false, // true 跳过证书校验（仅限测试！）
+ domain_override: None, // 按 IP 连接时指定 SNI/校验主机名
+ ..Default::default()
+};
+```
-// 删除数据
-TSStatus deleteData(1:TSDeleteDataReq req);
+## 6. 示例
-// 执行原始数据查询
-TSExecuteStatementResp executeRawDataQuery(1:TSRawDataQueryReq req);
+完整可运行示例见仓库 [`examples/`](https://github.com/apache/iotdb-client-rust/tree/main/examples) 目录：
-// 向服务器申请一个查询语句 ID
-i64 requestStatementId(1:i64 sessionId);
+```sh
+cargo run --example tree_session
+cargo run --example table_session
+cargo run --example session_pool
```