mod rust dev guide

docs/examples/rust/nativeexample/examples/connect.rs

@@ -3,7 +3,7 @@ use taos::*;
 #[tokio::main]
 async fn main() -> Result<(), Error> {
     #[allow(unused_variables)]
-    let taos = TaosBuilder::from_dsn("taos://")?.build()?;
+    let taos = TaosBuilder::from_dsn("taos://localhost:6030")?.build()?;
-    println!("Connected");
+    println!("Connected to localhost with native connection successfully.");
     Ok(())
 }

docs/examples/rust/nativeexample/examples/query.rs

@@ -11,18 +11,19 @@ async fn main() -> anyhow::Result<()> {
 let db = "power";
 // create database
 taos.exec_many([
-        format!("DROP DATABASE IF EXISTS `{db}`"),
+    format!("CREATE DATABASE IF NOT EXISTS `{db}`"),
-        format!("CREATE DATABASE `{db}`"),
     format!("USE `{db}`"),
 ])
 .await?;
+println!("Create database power successfully.");
 
-    // create table
-    taos.exec_many([
 // create super table
+taos.exec_many([
     "CREATE TABLE `meters` (`ts` TIMESTAMP, `current` FLOAT, `voltage` INT, `phase` FLOAT) \
         TAGS (`groupid` INT, `location` BINARY(24))",
 ]).await?;
+println!("Create stable meters successfully.");
+
 // ANCHOR_END: create_db_and_table
 
 // ANCHOR: insert_data
@@ -36,11 +37,12 @@ async fn main() -> anyhow::Result<()> {
 "VALUES " +
 "(NOW + 1a, 10.30000, 218, 0.25000) ").await?;
 
-    println!("inserted: {} rows", inserted);
+println!("inserted: {} rows to power.meters successfully.", inserted);
 // ANCHOR_END: insert_data
 
 // ANCHOR: query_data
-    let mut result = taos.query("SELECT * FROM power.meters").await?;
+// query data, make sure the database and table are created before
+let mut result = taos.query("SELECT ts, current, location FROM power.meters limit 100").await?;
 
 for field in result.fields() {
     println!("got field: {}", field.name());
@@ -60,7 +62,7 @@ async fn main() -> anyhow::Result<()> {
 // ANCHOR_END: query_data
 
 // ANCHOR: query_with_req_id
-    let result = taos.query_with_req_id("SELECT * FROM power.meters", 0).await?;
+let result = taos.query_with_req_id("SELECT ts, current, location FROM power.meters limit 1", 1).await?;
 // ANCHOR_END: query_with_req_id
 
 }

docs/examples/rust/nativeexample/examples/schemaless.rs

@@ -17,8 +17,6 @@ async fn put() -> anyhow::Result<()> {
 
     let db = "power";
 
-    client.exec(format!("drop database if exists {db}")).await?;
-
     client
         .exec(format!("create database if not exists {db}"))
         .await?;
@@ -44,7 +42,7 @@ async fn put() -> anyhow::Result<()> {
 
     // SchemalessProtocol::Telnet
     let data = [
-        "meters.current 1648432611249 10.3 location=California.SanFrancisco group=2",
+        "metric_telnet 1648432611249 10.3 location=California.SanFrancisco group=2",
     ]
     .map(String::from)
     .to_vec();
@@ -60,7 +58,7 @@ async fn put() -> anyhow::Result<()> {
 
     // SchemalessProtocol::Json
     let data = [
-        r#"[{"metric": "meters.current", "timestamp": 1681345954000, "value": 10.3, "tags": {"location": "California.SanFrancisco", "groupid": 2}}, {"metric": "meters.voltage", "timestamp": 1648432611249, "value": 219, "tags": {"location": "California.LosAngeles", "groupid": 1}}, {"metric": "meters.current", "timestamp": 1648432611250, "value": 12.6, "tags": {"location": "California.SanFrancisco", "groupid": 2}}, {"metric": "meters.voltage", "timestamp": 1648432611250, "value": 221, "tags": {"location": "California.LosAngeles", "groupid": 1}}]"#
+        r#"[{"metric": "metric_json", "timestamp": 1681345954000, "value": 10.3, "tags": {"location": "California.SanFrancisco", "groupid": 2}}, {"metric": "meters.voltage", "timestamp": 1648432611249, "value": 219, "tags": {"location": "California.LosAngeles", "groupid": 1}}, {"metric": "meters.current", "timestamp": 1648432611250, "value": 12.6, "tags": {"location": "California.SanFrancisco", "groupid": 2}}, {"metric": "meters.voltage", "timestamp": 1648432611250, "value": 221, "tags": {"location": "California.LosAngeles", "groupid": 1}}]"#
     ]
     .map(String::from)
     .to_vec();
@@ -74,7 +72,5 @@ async fn put() -> anyhow::Result<()> {
         .build()?;
     assert_eq!(client.put(&sml_data).await?, ());
 
-    client.exec(format!("drop database if exists {db}")).await?;
-
     Ok(())
 }

docs/examples/rust/nativeexample/examples/stmt.rs

@@ -17,6 +17,8 @@ async fn main() -> anyhow::Result<()> {
     for i in 0..NUM_TABLES {
         let table_name = format!("d{}", i);
         let tags = vec![Value::VarChar("California.SanFransico".into()), Value::Int(2)];
+
+        // set table name and tags for the prepared statement.
         stmt.set_tbname_tags(&table_name, &tags).await?;
         for j in 0..NUM_ROWS {
             let values = vec![
@@ -25,13 +27,16 @@ async fn main() -> anyhow::Result<()> {
                 ColumnView::from_ints(vec![219 + j as i32]),
                 ColumnView::from_floats(vec![0.31 + j as f32]),
             ];
+            // bind values to the prepared statement.    
             stmt.bind(&values).await?;
         }
+
         stmt.add_batch().await?;
     }
 
     // execute.
     let rows = stmt.execute().await?;
     assert_eq!(rows, NUM_TABLES * NUM_ROWS);
+    
     Ok(())
 }

docs/examples/rust/restexample/examples/connect.rs

@@ -3,7 +3,7 @@ use taos::*;
 #[tokio::main]
 async fn main() -> Result<(), Error> {
     #[allow(unused_variables)]
-    let taos = TaosBuilder::from_dsn("taos://")?.build()?;
+    let taos = TaosBuilder::from_dsn("taos+ws://localhost:6041")?.build()?;
-    println!("Connected");
+    println!("Connected to localhost with websocket connection successfully.");
     Ok(())
 }

docs/zh/08-develop/01-connect/index.md

@@ -321,7 +321,7 @@ Java 连接器建立连接的参数有 URL 和 Properties。
 TDengine 的 JDBC URL 规范格式为：
 `jdbc:[TAOS|TAOS-RS]://[host_name]:[port]/[database_name]?[user={user}|&password={password}|&charset={charset}|&cfgdir={config_dir}|&locale={locale}|&timezone={timezone}]`  
 
-URL 和 Properties 的详细参数说明和如何使用详见 [API 说明](../../reference/connector/java/#url-规范)
+URL 和 Properties 的详细参数说明和如何使用详见 [url 规范](../../reference/connector/java/#url-规范)
 
     </TabItem>
     <TabItem label="Python" value="python">
@@ -329,6 +329,16 @@ URL 和 Properties 的详细参数说明和如何使用详见 [API 说明](../..
     <TabItem label="Go" value="go">
     </TabItem>
     <TabItem label="Rust" value="rust">
+Rust 连接器使用 DSN 来创建连接， DSN 描述字符串基本结构如下：
+
+```text
+<driver>[+<protocol>]://[[<username>:<password>@]<host>:<port>][/<database>][?<p1>=<v1>[&<p2>=<v2>]]
+|------|------------|---|-----------|-----------|------|------|------------|-----------------------|
+|driver|   protocol |   | username  | password  | host | port |  database  |  params               |
+```
+
+DSN 的详细说明和如何使用详见 [连接功能](../../reference/connector/rust/#连接功能)
+
     </TabItem>
     <TabItem label="C#" value="csharp">
     </TabItem>
@@ -387,7 +397,9 @@ URL 和 Properties 的详细参数说明和如何使用详见 [API 说明](../..
         <ConnGo />
     </TabItem>
     <TabItem label="Rust" value="rust">
-        <ConnRust />
+```rust
+{{#include docs/examples/rust/restexample/examples/connect.rs}}
+```
     </TabItem>
     <TabItem label="Node.js" value="node">
 ```js
@@ -424,7 +436,10 @@ URL 和 Properties 的详细参数说明和如何使用详见 [API 说明](../..
         <ConnGo />
     </TabItem>
     <TabItem label="Rust" value="rust">
-        <ConnRust />
+```rust 
+{{#include docs/examples/rust/nativeexample/examples/connect.rs}}
+```
+
     </TabItem>
     <TabItem label="C#" value="csharp">
         <ConnCSNative />
@@ -459,7 +474,7 @@ URL 和 Properties 的详细参数说明和如何使用详见 [API 说明](../..
         <ConnGo />
     </TabItem>
     <TabItem label="Rust" value="rust">
-        <ConnRust />
+不支持
     </TabItem>
     <TabItem label="C#" value="csharp">
         <ConnCSNative />
@@ -519,7 +534,33 @@ URL 和 Properties 的详细参数说明和如何使用详见 [API 说明](../..
         <ConnGo />
     </TabItem>
     <TabItem label="Rust" value="rust">
-        <ConnRust />
+
+在复杂应用中，建议启用连接池。[taos] 的连接池默认（异步模式）使用 [deadpool] 实现。
+
+如下，可以生成一个默认参数的连接池。
+
+```rust
+let pool: Pool<TaosBuilder> = TaosBuilder::from_dsn("taos:///")
+    .unwrap()
+    .pool()
+    .unwrap();
+```
+
+同样可以使用连接池的构造器，对连接池参数进行设置：
+
+```rust
+let pool: Pool<TaosBuilder> = Pool::builder(Manager::from_dsn(self.dsn.clone()).unwrap().0)
+    .max_size(88)  // 最大连接数
+    .build()
+    .unwrap();
+```
+
+在应用代码中，使用 `pool.get()?` 来获取一个连接对象 [Taos]。
+
+```rust
+let taos = pool.get()?;
+```
+
     </TabItem>
     <TabItem label="C#" value="csharp">
         <ConnCSNative />

docs/zh/08-develop/02-sql.md

@@ -21,7 +21,6 @@ TDengine 对 SQL 语言提供了全面的支持，允许用户以熟悉的 SQL
 ```java
 {{#include examples/JDBC/JDBCDemo/src/main/java/com/taosdata/example/JdbcCreatDBDemo.java:create_db_and_table}}
 ```
-> **注意**：如果不使用 `USE power` 指定数据库，则后续对表的操作都需要增加数据库名称作为前缀，如 power.meters。
 
 </TabItem>
 <TabItem label="Python" value="python">
@@ -31,6 +30,11 @@ TDengine 对 SQL 语言提供了全面的支持，允许用户以熟悉的 SQL
 <TabItem label="Go" value="go">
 </TabItem>
 <TabItem label="Rust" value="rust">
+
+```rust
+{{#include docs/examples/rust/nativeexample/examples/query.rs:create_db_and_table}}
+```
+
 </TabItem>
 <TabItem label="C#" value="csharp">
 </TabItem>
@@ -45,6 +49,7 @@ TDengine 对 SQL 语言提供了全面的支持，允许用户以熟悉的 SQL
 <TabItem label="PHP" value="php">
 </TabItem>
 </Tabs>
+> **注意**：如果不使用 `USE power` 指定数据库，则后续对表的操作都需要增加数据库名称作为前缀，如 `power.meters`。
 
 ## 插入数据
 下面以智能电表为例，展示如何使用连接器执行 SQL 来插入数据到 `power` 数据库的 `meters` 超级表。样例使用 TDengine 自动建表 SQL 语法，写入 d1001 子表中 3 条数据，写入 d1002 子表中 1 条数据，然后打印出实际插入数据条数。
@@ -65,6 +70,11 @@ NOW 为系统内部函数，默认为客户端所在计算机当前时间。 NOW
 <TabItem label="Go" value="go">
 </TabItem>
 <TabItem label="Rust" value="rust">
+
+```rust
+{{#include docs/examples/rust/nativeexample/examples/query.rs:insert_data}}
+```
+
 </TabItem>
 <TabItem label="C#" value="csharp">
 </TabItem>
@@ -100,6 +110,11 @@ NOW 为系统内部函数，默认为客户端所在计算机当前时间。 NOW
 <TabItem label="Go" value="go">
 </TabItem>
 <TabItem label="Rust" value="rust">
+
+```rust
+{{#include docs/examples/rust/nativeexample/examples/query.rs:query_data}}
+```
+
 </TabItem>
 <TabItem label="C#" value="csharp">
 </TabItem>
@@ -140,6 +155,11 @@ reqId 可用于请求链路追踪，reqId 就像分布式系统中的 traceId
 <TabItem label="Go" value="go">
 </TabItem>
 <TabItem label="Rust" value="rust">
+
+```rust
+{{#include docs/examples/rust/nativeexample/examples/query.rs:query_with_req_id}}
+```
+
 </TabItem>
 <TabItem label="C#" value="csharp">
 </TabItem>

docs/zh/08-develop/04-schemaless.md

@@ -181,6 +181,11 @@ writer.write(lineDemo, SchemalessProtocolType.LINE, SchemalessTimestampType.NANO
 <TabItem label="Go" value="go">
 </TabItem>
 <TabItem label="Rust" value="rust">
+
+```rust
+{{#include docs/examples/rust/restexample/examples/schemaless.rs}}
+```
+
 </TabItem>
 <TabItem label="C#" value="csharp">
 </TabItem>
@@ -211,6 +216,7 @@ writer.write(lineDemo, SchemalessProtocolType.LINE, SchemalessTimestampType.NANO
     <TabItem label="Go" value="go">
     </TabItem>
     <TabItem label="Rust" value="rust">
+除 DSN 不同，其余同 Websocket 代码示例。  
     </TabItem>
     <TabItem label="C#" value="csharp">
     </TabItem>
@@ -234,6 +240,7 @@ writer.write(lineDemo, SchemalessProtocolType.LINE, SchemalessTimestampType.NANO
     <TabItem label="Go" value="go">
     </TabItem>
     <TabItem label="Rust" value="rust">
+    不支持
     </TabItem>
     <TabItem label="C#" value="csharp">
     </TabItem>

docs/zh/08-develop/05-stmt.md

@@ -43,6 +43,10 @@ import TabItem from "@theme/TabItem";
 </TabItem>
 <TabItem label="Rust" value="rust">
 
+```rust
+{{#include docs/examples/rust/restexample/examples/stmt.rs}}
+```
+
 </TabItem>
 <TabItem label="Node.js" value="node">
 
@@ -82,7 +86,7 @@ import TabItem from "@theme/TabItem";
 
 </TabItem>
 <TabItem label="Rust" value="rust">
-
+除 DSN 不同，其余同 Websocket 代码示例。
 </TabItem>
 <TabItem label="C#" value="csharp">
 

docs/zh/08-develop/07-tmq.md

@@ -46,7 +46,7 @@ TDengine 消费者的概念跟 Kafka 类似，消费者通过订阅主题来接
 下面是各语言连接器创建参数：
 <Tabs defaultValue="java" groupId="lang">
 <TabItem value="java" label="Java">
-Java 连接器创建消费者的参数为 Properties， 可以设置的参数列表请参考 [API 说明](../../reference/connector/java/#消费者)  
+Java 连接器创建消费者的参数为 Properties， 可以设置的参数列表请参考 [消费者参数](../../reference/connector/java/#消费者)  
 其他参数请参考上文通用基础配置项。
 
 
@@ -58,6 +58,8 @@ Java 连接器创建消费者的参数为 Properties， 可以设置的参数列
 
 </TabItem>
 <TabItem label="Rust" value="rust">
+Rust 连接器创建消费者的参数为 DSN， 可以设置的参数列表请参考 [DSN](../../reference/connector/rust/#dsn)  
+其他参数请参考上文通用基础配置项。
 
 </TabItem>
 <TabItem label="Node.js" value="node">
@@ -102,6 +104,11 @@ Java 连接器创建消费者的参数为 Properties， 可以设置的参数列
 
 <TabItem label="Rust" value="rust">
 
+
+```rust
+{{#include docs/examples/rust/nativeexample/examples/tmq.rs:create_consumer}}
+```
+
 </TabItem>
 
 <TabItem label="Node.js" value="node">

docs/zh/14-reference/05-connector/26-rust.mdx

@@ -168,7 +168,7 @@ DSN 描述字符串基本结构如下：
 各部分意义见下表：
 
 - **driver**: 必须指定驱动名以便连接器选择何种方式创建连接，支持如下驱动名：
-  - **taos**: 表名使用 TDengine 连接器驱动。
+  - **taos**: 表明使用 TDengine 连接器驱动。
   - **tmq**: 使用 TMQ 订阅数据。
   - **http/ws**: 使用 Websocket 创建连接。
   - **https/wss**: 在 Websocket 连接方式下显示启用 SSL/TLS 连接。
@@ -640,7 +640,7 @@ DSN 描述字符串基本结构如下：
 一个完整的 DSN 描述字符串示例如下：`taos+ws://localhost:6041/test`， 表示使用 Websocket（`ws`）方式通过 `6041` 端口连接服务器 `localhost`，并指定默认数据库为 `test`。
 
 #### TaosBuilder
-TaosBuilder 结构体提供了建立连接，检查连接，以及获取服务端版本号等功能。
+TaosBuilder 结构体主要提供了根据 DSN 构建 Taos 对象的方法，还提供了检查连接，以及获取客户端版本号等功能。
 
 - `fn available_params() -> &'static [&'static str]`
   - **接口说明**：获取 DSN 中可用的参数列表。
@@ -664,14 +664,15 @@ TaosBuilder 结构体提供了建立连接，检查连接，以及获取服务
 
 - `fn ready(&self) -> bool`
   - **接口说明**：检查是否准备好连接。
-  - **返回值**：大多数情况下返回true，表示地址准备好连接。
+  - **返回值**：大多数情况下返回 `true`，表示地址准备好连接。
 
 - `fn build(&self) -> RawResult<Self::Target>`
-  - **接口说明**：从此结构创建新的连接。
+  - **接口说明**：从此结构创建新的 Taos 对象。
   - **返回值**：成功时返回目标连接类型的 `RawResult`，失败时返回错误。
 
 ### 执行 SQL
-执行 SQL 主要涉及到 Taos 结构体，以及结果集 ResultSet 结构体，还有列信息 Field。
+执行 SQL 主要使用 Taos 结构体，获取结果集以及元数据需要使用下节介绍的 ResultSet 结构体 和列信息 Field 结构体。
+
 #### Taos
 Taos 结构体提供了多个数据库操作的 API，包括：执行 SQL，无模式写入，以及一些常用数据库查询的封装（如创建数据库，获取）
 
@@ -737,7 +738,7 @@ Taos 结构体提供了多个数据库操作的 API，包括：执行 SQL，无
   - **接口说明**：描述表结构。
   - **参数说明**：
     - `table`：表名称。
-  - **返回值**：成功时返回表描述的 `RawResult`，失败时返回错误。
+  - **返回值**：成功时返回表结构描述的 `RawResult`，失败时返回错误。
 
 - `fn database_exists(&self, name: &str) -> RawResult<bool>`
   - **接口说明**：检查数据库是否存在。
@@ -746,12 +747,43 @@ Taos 结构体提供了多个数据库操作的 API，包括：执行 SQL，无
   - **返回值**：成功时返回布尔值的 `RawResult`，指示数据库是否存在，失败时返回错误。
 
 - `fn put(&self, data: &SmlData) -> RawResult<()>`
-  - **接口说明**：写入无模式数据。
+  - **接口说明**：写入无模式数据，SmlData 结构介绍见下文。
   - **参数说明**：
     - `data`：无模式数据。
   - **返回值**：成功时返回空的 `RawResult`，失败时返回错误。
 
+### SmlData  
+SmlData 结构体提供了无模式写入的数据结构，以及获取属性的方法。
+- `pub struct SmlData`
+  - **结构体说明**：`SmlData` 结构体用于存储无模式数据及其相关信息。
+  - **字段说明**：
+    - `protocol`：无模式协议，支持 `Line`, `Telnet`, `Json`, 三种。
+    - `precision`：时间戳精度，支持 `Hours`, `Minutes`, `Seconds`, `Millisecond`（默认）, `Microsecond`, `Nanosecond`。
+    - `data`：数据列表。
+    - `ttl`：数据存活时间，单位为秒。
+    - `req_id`：请求 ID。
 
+- `pub fn protocol(&self) -> SchemalessProtocol`
+  - **接口说明**：获取无模式协议。
+  - **返回值**：无模式协议类型，支持 `Line`, `Telnet`, `Json`, 三种。
+
+- `pub fn precision(&self) -> SchemalessPrecision`
+  - **接口说明**：获取时间戳精度。
+  - **返回值**：时间戳精度类型，支持 `Hours`, `Minutes`, `Seconds`, `Millisecond`（默认）, `Microsecond`, `Nanosecond`。
+
+- `pub fn data(&self) -> &Vec<String>`
+  - **接口说明**：获取数据列表。
+  - **返回值**：数据列表的引用。
+
+- `pub fn ttl(&self) -> Option<i32>`
+  - **接口说明**：获取数据存活时间。
+  - **返回值**：数据存活时间（可选），单位为秒。
+
+- `pub fn req_id(&self) -> Option<u64>`
+  - **接口说明**：获取请求 ID。
+  - **返回值**：请求 ID（可选）。
+
+### 结果获取  
 #### ResultSet
 ResultSet 结构体提供了结果集的一些方法，可以用来获取结果集的数据和元数据。
 
@@ -921,7 +953,7 @@ Stmt 结构体提供了参数绑定相关功能，用于实现高效写入。
 
 - `fn ready(&self) -> bool`
   - **接口说明**：检查是否准备好连接。
-  - **返回值**：大多数情况下返回true，表示地址准备好连接。
+  - **返回值**：大多数情况下返回 `true`，表示地址准备好连接。
 
 - `fn build(&self) -> RawResult<Self::Target>`
   - **接口说明**：从此结构创建新的连接。
@@ -1002,12 +1034,8 @@ Offset 结构体提供了获取当前消息所属的数据库，主题和分区
   - **接口说明**：获取当前消息的分区 ID。
   - **返回值**：分区 ID。
 
-其他相关结构体 API 使用说明请移步 Rust 文档托管网页：https://docs.rs/taos。
+## 附录  
-
+- Rust 连接器文档：https://docs.rs/taos
-[taos]: https://github.com/taosdata/rust-connector-taos
+- Rust 连接器项目地址: https://github.com/taosdata/rust-connector-taos  
-[deadpool]: https://crates.io/crates/deadpool
+- deadpool 连接池: https://crates.io/crates/deadpool  
-[r2d2]: https://crates.io/crates/r2d2
+- r2d2 连接池: https://crates.io/crates/r2d2  
-[TaosBuilder]: https://docs.rs/taos/latest/taos/struct.TaosBuilder.html
-[TaosCfg]: https://docs.rs/taos/latest/taos/struct.TaosCfg.html
-[struct.Taos]: https://docs.rs/taos/latest/taos/struct.Taos.html
-[Stmt]: https://docs.rs/taos/latest/taos/struct.Stmt.html