Skip to content

Commit 11550eb

Browse files
committed
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.
1 parent a2b8f6e commit 11550eb

10 files changed

Lines changed: 1026 additions & 598 deletions

File tree

src/.vuepress/sidebar/V2.0.x/en-Table.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -184,6 +184,7 @@ export const enSidebar = {
184184
{ text: 'C++ Native API', link: 'Programming-Cpp-Native-API_apache' },
185185
{ text: 'GO Native API', link: 'Programming-Go-Native-API_apache' },
186186
{ text: 'C# Native API', link: 'Programming-CSharp-Native-API_apache' },
187+
{ text: 'Rust Native API', link: 'Programming-Rust-Native-API_apache' },
187188
{ text: 'JDBC', link: 'Programming-JDBC_apache' },
188189
{ text: 'MQTT Protocol', link: 'Programming-MQTT_apache' },
189190
{ text: 'RESTAPI V1 ', link: 'RestAPI-V1_apache' },

src/.vuepress/sidebar/V2.0.x/zh-Table.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -183,6 +183,7 @@ export const zhSidebar = {
183183
{ text: 'C++原生接口', link: 'Programming-Cpp-Native-API_apache' },
184184
{ text: 'GO原生接口', link: 'Programming-Go-Native-API_apache' },
185185
{ text: 'C#原生接口', link: 'Programming-CSharp-Native-API_apache' },
186+
{ text: 'Rust原生接口', link: 'Programming-Rust-Native-API_apache' },
186187
{ text: 'JDBC', link: 'Programming-JDBC_apache' },
187188
{ text: 'MQTT协议', link: 'Programming-MQTT_apache' },
188189
{ text: 'RESTAPI V1 ', link: 'RestServiceV1_apache' },
Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
<!--
2+
3+
Licensed to the Apache Software Foundation (ASF) under one
4+
or more contributor license agreements. See the NOTICE file
5+
distributed with this work for additional information
6+
regarding copyright ownership. The ASF licenses this file
7+
to you under the Apache License, Version 2.0 (the
8+
"License"); you may not use this file except in compliance
9+
with the License. You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing,
14+
software distributed under the License is distributed on an
15+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16+
KIND, either express or implied. See the License for the
17+
specific language governing permissions and limitations
18+
under the License.
19+
20+
-->
21+
22+
# Rust Native API
23+
24+
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.
25+
26+
## 1. Requirements
27+
28+
- Rust 1.75+
29+
- Apache IoTDB 2.x — see [COMPATIBILITY.md](https://github.com/apache/iotdb-client-rust/blob/main/COMPATIBILITY.md) for the full server version matrix
30+
31+
## 2. Installation
32+
33+
Once published to crates.io:
34+
35+
```toml
36+
[dependencies]
37+
iotdb-client-rust = "0.1"
38+
```
39+
40+
Until then, use a git dependency:
41+
42+
```toml
43+
[dependencies]
44+
iotdb-client = { git = "https://github.com/apache/iotdb-client-rust" }
45+
```
46+
47+
The import name is `iotdb_client` in both cases.
48+
49+
## 3. Quick start
50+
51+
```rust
52+
use iotdb_client::{ColumnCategory, Result, TSDataType, TableSession, Tablet, Value};
53+
54+
fn main() -> Result<()> {
55+
let mut session = TableSession::builder()
56+
.node_urls(&["127.0.0.1:6667"])?
57+
.username("root")
58+
.password("root")
59+
.build()?;
60+
61+
session.execute_non_query("CREATE DATABASE IF NOT EXISTS demo")?;
62+
session.execute_non_query("USE demo")?;
63+
session.execute_non_query(
64+
"CREATE TABLE IF NOT EXISTS sensors (device_id STRING TAG, temperature DOUBLE FIELD)",
65+
)?;
66+
67+
// Column-major tablet write. columnCategories must NOT include TIME —
68+
// the time column is implicit.
69+
let mut tablet = Tablet::new_table(
70+
"sensors",
71+
vec!["device_id".into(), "temperature".into()],
72+
vec![TSDataType::String, TSDataType::Double],
73+
vec![ColumnCategory::Tag, ColumnCategory::Field],
74+
)?;
75+
tablet.add_row(
76+
1_720_000_000_000,
77+
vec![
78+
Some(Value::String("dev-1".into())),
79+
Some(Value::Double(21.5)),
80+
],
81+
)?;
82+
session.insert(&tablet)?;
83+
84+
// Query with row iteration; the dataset borrows the session until dropped.
85+
{
86+
let mut dataset =
87+
session.execute_query("SELECT time, device_id, temperature FROM sensors")?;
88+
while let Some(row) = dataset.next_row()? {
89+
println!("{:?}", row.values);
90+
}
91+
}
92+
93+
session.execute_non_query("DROP DATABASE demo")?;
94+
session.close()
95+
}
96+
```
97+
98+
## 4. Session pool
99+
100+
`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).
101+
102+
## 5. TLS & RPC compression
103+
104+
**RPC compression** (the Thrift compact protocol) must match the server setting `dn_rpc_thrift_compression_enable` (default `false`):
105+
106+
```rust
107+
let mut session = TableSession::builder()
108+
.node_urls(&["127.0.0.1:6667"])?
109+
.enable_rpc_compression(true)
110+
.build()?;
111+
```
112+
113+
**TLS** is behind the `tls` cargo feature:
114+
115+
```toml
116+
iotdb-client-rust = { version = "0.1", features = ["tls"] }
117+
```
118+
119+
```rust
120+
let mut session = TableSession::builder()
121+
.node_urls(&["127.0.0.1:6667"])?
122+
.use_ssl(true)
123+
.ca_cert_path("ca.pem")
124+
.build()?;
125+
```
126+
127+
## 6. Examples
128+
129+
Full runnable examples live in the repository's [`examples/`](https://github.com/apache/iotdb-client-rust/tree/main/examples) directory:
130+
131+
```sh
132+
cargo run --example table_session
133+
cargo run --example session_pool
134+
```

0 commit comments

Comments
 (0)