rust examples (#11170)

* doc fix

* rust sql insert example

* rust schemaless examples

* rust stmt examples

* rust query example

* remove go async

* format code

docs-cn/06-insert-data/_rust_line.mdx

+```rust
+{{#include docs-examples/rust/schemalessexample/examples/influxdb_line_example.rs}}
+```

docs-cn/06-insert-data/_rust_opts_json.mdx

+```rust
+{{#include docs-examples/rust/schemalessexample/examples/opentsdb_json_example.rs}}
+```

docs-cn/06-insert-data/_rust_opts_telnet.mdx

+```rust
+{{#include docs-examples/rust/schemalessexample/examples/opentsdb_telnet_example.rs}}
+```

docs-cn/06-insert-data/_rust_sql.mdx

+```rust
+{{#include docs-examples/rust/restexample/examples/insert_example.rs}}
+```

docs-cn/06-insert-data/_rust_stmt.mdx

+```rust
+{{#include docs-examples/rust/nativeexample/examples/stmt_example.rs}}
+```

docs-cn/07-query-data/_rust.mdx

+```rust
+{{#include docs-examples/rust/restexample/examples/query_example.rs}}
+```

docs-cn/07-query-data/index.mdx

@@ -14,7 +14,6 @@ import NodeQuery from "./_js.mdx";
 import CsQuery from "./_cs.mdx";
 import CQuery from "./_c.mdx";
 import PyAsync from "./_py_async.mdx";
-import GoAsync from "./_go_async.mdx";
 import NodeAsync from "./_js_async.mdx";
 import CsAsync from "./_cs_async.mdx";
 import CAsync from "./_c_async.mdx";
@@ -160,9 +159,6 @@ Query OK, 5 row(s) in set (0.001521s)
   <TabItem label="Python" value="python">
     <PyAsync />
   </TabItem>
-  <TabItem label="Go" value="go">
-    <GoAsync />
-  </TabItem>
   <TabItem label="Node.js" value="nodejs">
     <NodeAsync />
   </TabItem>

docs-cn/10-cluster/01-deploy.md

@@ -30,7 +30,7 @@
 
 检查所有数据节点，以及应用程序所在物理节点的网络设置：
 
-每个物理节点上执行命令 hostname -f，查看和确认所有节点的 hostname 是不相同的(应用驱动所在节点无需做此项检查)；
+每个物理节点上执行命令 `hostname -f`，查看和确认所有节点的 hostname 是不相同的(应用驱动所在节点无需做此项检查)；
 
 每个物理节点上执行 ping host，其中 host 是其他物理节点的 hostname，看能否 ping 通其它物理节点；如果不能 ping 通，需要检查网络设置，或/etc/hosts 文件(Windows 系统默认路径为 C:\Windows\system32\drivers\etc\hosts)，或 DNS 的配置。如果无法 ping 通，是无法组成集群的；
 
@@ -42,7 +42,7 @@
 
 修改 TDengine 的配置文件（所有节点的文件/etc/taos/taos.cfg 都需要修改）。假设准备启动的第一个数据节点 End Point 为 h1.taosdata.com:6030，其与集群配置相关参数如下：
 
-```
+```c
 // firstEp 是每个数据节点首次启动后连接的第一个数据节点
 firstEp               h1.taosdata.com:6030
 
@@ -74,16 +74,16 @@ arbitrator            ha.taosdata.com:6042
 
 :::note
 在 2.0.19.0 及更早的版本中，除以上 9 项参数外，dnode 加入集群时，还会要求 locale 和 charset 参数的取值也一致。
+
 :::
 
 ## 启动集群
 
 ### 启动第一个数据节点
 
-按照《立即开始》里的指示，启动第一个数据节点，例如 h1.taosdata.com，然后执行 taos, 启动 taos shell，从 shell 里执行命令"show dnodes;"，如下所示：
+按照《立即开始》里的步骤，启动第一个数据节点，例如 h1.taosdata.com，然后执行 taos, 启动 taos shell，从 shell 里执行命令"SHOW dnodes;"，如下所示：
 
 ```
-
 Welcome to the TDengine shell from Linux, Client Version:2.0.0.0
 
 

docs-cn/11-operation/08-export.md

@@ -16,4 +16,4 @@ select * from <tb_name> >> data.csv;
 
 利用 taosdump，用户可以根据需要选择导出所有数据库、一个数据库或者数据库中的一张表，所有数据或一时间段的数据，甚至仅仅表的定义。
 
-具体使用方法，请参见博客：[TDengine DUMP 工具使用指南](https://www.taosdata.com/blog/2020/03/09/1334.html)。
+具体使用方法，请参见博客：[TDengine DUMP 工具使用指南](https://github.com/taosdata/taos-tools/blob/develop/taosdump-user-manual-CN.md)。

docs-cn/14-reference/01-taos-sql/07-function.md

@@ -682,7 +682,7 @@ SELECT INTERP(field_name) FROM { tb_name | stb_name } WHERE ts='timestamp' [FILL
 SELECT TAIL(field_name, k, offset_val) FROM {tb_name | stb_name} [WHERE clause];
 ```
 
-**功能说明**：返回跳过最后 offset_value 个，然后取连续 k 个记录，不忽略 NULL 值。offset_val 可以不输入。此时返回最后的 k 个记录。当有 offset_val 输入的情况下，该函数功能等效于 order by ts desc LIMIT k OFFSET offset_val。
+**功能说明**：返回跳过最后 offset_value 个，然后取连续 k 个记录，不忽略 NULL 值。offset_val 可以不输入。此时返回最后的 k 个记录。当有 offset_val 输入的情况下，该函数功能等效于 `order by ts desc LIMIT k OFFSET offset_val`。
 
 **参数范围**：k: [1,100] offset_val: [0,100]。
 

docs-cn/14-reference/03-connector/rust.mdx

@@ -104,6 +104,10 @@ async fn main() -> Result<(), Error> {
 
 您可以在 [bailongma-rs] - 一个 Rust 编写的 Prometheus 远程存储 API 适配器 - 看到如何在具体应用中使用 Rust 连接器。
 
+## API 参考
+
+[API 参考手册](https://docs.rs/libtaos/latest/libtaos/)
+
 [libtaos-rs]: https://github.com/taosdata/libtaos-rs
 [tdengine]: https://github.com/taosdata/TDengine
 [bailongma-rs]: https://github.com/taosdata/bailongma-rs

docs-examples/.gitignore

+.vscode
+*.lock
+.idea
\ No newline at end of file

docs-examples/.gitignre

+.vscode
+*.lock
\ No newline at end of file

docs-examples/go/insert/json/main.go

@@ -11,7 +11,7 @@ func prepareDatabase(conn *af.Connector) {
 	if err != nil {
 		panic(err)
 	}
-	_, err = conn.Exec("use test")
+	_, err = conn.Exec("USE test")
 	if err != nil {
 		panic(err)
 	}

docs-examples/go/insert/line/main.go

@@ -11,7 +11,7 @@ func prepareDatabase(conn *af.Connector) {
 	if err != nil {
 		panic(err)
 	}
-	_, err = conn.Exec("use test")
+	_, err = conn.Exec("USE test")
 	if err != nil {
 		panic(err)
 	}

docs-examples/go/insert/telnet/main.go

@@ -11,7 +11,7 @@ func prepareDatabase(conn *af.Connector) {
 	if err != nil {
 		panic(err)
 	}
-	_, err = conn.Exec("use test")
+	_, err = conn.Exec("USE test")
 	if err != nil {
 		panic(err)
 	}

docs-examples/go/query/sync/main.go

@@ -16,7 +16,7 @@ func main() {
 		return
 	}
 	defer taos.Close()
-	rows, err := taos.Query("select ts, current from meters limit 2")
+	rows, err := taos.Query("SELECT ts, current FROM meters LIMIT 2")
 	if err != nil {
 		fmt.Println("failed to select from table, err:", err)
 		return

docs-examples/java/src/main/java/com/taos/example/JSONProtocolExample.java

@@ -17,8 +17,8 @@ public class JSONProtocolExample {
 
     private static void createDatabase(Connection conn) throws SQLException {
         try (Statement stmt = conn.createStatement()) {
-            stmt.execute("create database test");
-            stmt.execute("use test");
+            stmt.execute("CREATE DATABASE test");
+            stmt.execute("USE test");
         }
     }
 

docs-examples/java/src/main/java/com/taos/example/LineProtocolExample.java

@@ -12,7 +12,8 @@ import java.sql.Statement;
 public class LineProtocolExample {
     // format: measurement,tag_set field_set timestamp
     private static String[] lines = {
-            "meters,location=Beijing.Haidian,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249000", // micro seconds
+            "meters,location=Beijing.Haidian,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249000", // micro
+                                                                                                              // seconds
             "meters,location=Beijing.Haidian,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611249500",
             "meters,location=Beijing.Haidian,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249300",
             "meters,location=Beijing.Haidian,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611249800",
@@ -26,8 +27,8 @@ public class LineProtocolExample {
     private static void createDatabase(Connection conn) throws SQLException {
         try (Statement stmt = conn.createStatement()) {
             // the default precision is ms (microsecond), but we use us(microsecond) here.
-            stmt.execute("create database test precision 'us'");
-            stmt.execute("use test");
+            stmt.execute("CREATE DATABASE test precision 'us'");
+            stmt.execute("USE test");
         }
     }
 
@@ -39,4 +40,3 @@ public class LineProtocolExample {
         }
     }
 }
-

docs-examples/java/src/main/java/com/taos/example/TelnetLineProtocolExample.java

@@ -11,7 +11,7 @@ import java.sql.Statement;
 
 public class TelnetLineProtocolExample {
     // format: <metric> <timestamp> <value> <tagk_1>=<tagv_1>[ <tagk_n>=<tagv_n>]
-    private static String[] lines = {"meters.current 1648432611249 10.3 location=Beijing.Chaoyang groupid=2",
+    private static String[] lines = { "meters.current 1648432611249 10.3 location=Beijing.Chaoyang groupid=2",
             "meters.current 1648432611250 12.6 location=Beijing.Chaoyang groupid=2",
             "meters.current 1648432611249 10.8 location=Beijing.Haidian groupid=3",
             "meters.current 1648432611250 11.3 location=Beijing.Haidian groupid=3",
@@ -29,8 +29,8 @@ public class TelnetLineProtocolExample {
     private static void createDatabase(Connection conn) throws SQLException {
         try (Statement stmt = conn.createStatement()) {
             // the default precision is ms (microsecond), but we use us(microsecond) here.
-            stmt.execute("create database test precision 'us'");
-            stmt.execute("use test");
+            stmt.execute("CREATE DATABASE test precision 'us'");
+            stmt.execute("USE test");
         }
     }
 

docs-examples/python/json_protocol_example.py

@@ -4,8 +4,10 @@ import taos
 from taos import SmlProtocol, SmlPrecision
 
 lines = [{"metric": "meters.current", "timestamp": 1648432611249, "value": 10.3, "tags": {"location": "Beijing.Chaoyang", "groupid": 2}},
-         {"metric": "meters.voltage", "timestamp": 1648432611249, "value": 219, "tags": {"location": "Beijing.Haidian", "groupid": 1}},
-         {"metric": "meters.current", "timestamp": 1648432611250, "value": 12.6, "tags": {"location": "Beijing.Chaoyang", "groupid": 2}},
+         {"metric": "meters.voltage", "timestamp": 1648432611249, "value": 219,
+             "tags": {"location": "Beijing.Haidian", "groupid": 1}},
+         {"metric": "meters.current", "timestamp": 1648432611250, "value": 12.6,
+             "tags": {"location": "Beijing.Chaoyang", "groupid": 2}},
          {"metric": "meters.voltage", "timestamp": 1648432611250, "value": 221, "tags": {"location": "Beijing.Haidian", "groupid": 1}}]
 
 
@@ -14,15 +16,16 @@ def get_connection():
 
 
 def create_database(conn):
-    conn.execute("create database test")
-    conn.execute("use test")
+    conn.execute("CREATE DATABASE test")
+    conn.execute("USE test")
 
 
 def insert_lines(conn):
     global lines
     lines = json.dumps(lines)
     # note: the first parameter must be a list with only one element.
-    affected_rows = conn.schemaless_insert([lines], SmlProtocol.JSON_PROTOCOL, SmlPrecision.NOT_CONFIGURED)
+    affected_rows = conn.schemaless_insert(
+        [lines], SmlProtocol.JSON_PROTOCOL, SmlPrecision.NOT_CONFIGURED)
     print(affected_rows)  # 4
 
 

docs-examples/python/line_protocol_example.py

@@ -15,12 +15,13 @@ def get_connection():
 
 def create_database(conn):
     # the default precision is ms (microsecond), but we use us(microsecond) here.
-    conn.execute("create database test precision 'us'")
-    conn.execute("use test")
+    conn.execute("CREATE DATABASE test precision 'us'")
+    conn.execute("USE test")
 
 
 def insert_lines(conn):
-    affected_rows = conn.schemaless_insert(lines, SmlProtocol.LINE_PROTOCOL, SmlPrecision.MICRO_SECONDS)
+    affected_rows = conn.schemaless_insert(
+        lines, SmlProtocol.LINE_PROTOCOL, SmlPrecision.MICRO_SECONDS)
     print(affected_rows)  # 8
 
 

docs-examples/python/telnet_line_protocol_example.py

@@ -19,12 +19,13 @@ def get_connection():
 
 
 def create_database(conn):
-    conn.execute("create database test")
-    conn.execute("use test")
+    conn.execute("CREATE DATABASE test")
+    conn.execute("USE test")
 
 
 def insert_lines(conn):
-    affected_rows = conn.schemaless_insert(lines, SmlProtocol.TELNET_PROTOCOL, SmlPrecision.NOT_CONFIGURED)
+    affected_rows = conn.schemaless_insert(
+        lines, SmlProtocol.TELNET_PROTOCOL, SmlPrecision.NOT_CONFIGURED)
     print(affected_rows)  # 8
 
 

docs-examples/rust/.gitignore

-*.lock
\ No newline at end of file

docs-examples/rust/Cargo.toml

 [workspace]
-members = ["restexample", "nativeexample"]
+members = ["restexample", "nativeexample", "schemalessexample"]

docs-examples/rust/nativeexample/Cargo.toml

@@ -5,4 +5,6 @@ edition = "2021"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 [dependencies]
-libtaos = { version = "0.4.2" }
+libtaos = { version = "0.4.3" }
+tokio = { version = "*", features = ["rt", "macros", "rt-multi-thread"] }
+bstr = { version = "*" }

docs-examples/rust/nativeexample/examples/stmt_example.rs

+use bstr::BString;
+use libtaos::*;
+
+#[tokio::main]
+async fn main() -> Result<(), Error> {
+    let taos = TaosCfg::default().connect().expect("fail to connect");
+    taos.create_database("power").await?;
+    taos.use_database("power").await?;
+    taos.exec("CREATE STABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)").await?;
+    let mut stmt = taos.stmt("INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)")?;
+    // bind table name and tags
+    stmt.set_tbname_tags(
+        "tb0",
+        [
+            Field::Binary(BString::from("Beijing.Chaoyang")),
+            Field::Int(2),
+        ],
+    )?;
+    // bind values.
+    let values = vec![
+        Field::Timestamp(Timestamp::new(1648432611249, TimestampPrecision::Milli)),
+        Field::Float(10.3),
+        Field::Int(219),
+        Field::Float(0.31),
+    ];
+    stmt.bind(&values)?;
+    // bind one more row
+    let values2 = vec![
+        Field::Timestamp(Timestamp::new(1648432611749, TimestampPrecision::Milli)),
+        Field::Float(12.6),
+        Field::Int(218),
+        Field::Float(0.33),
+    ];
+    stmt.bind(&values2)?;
+    // execute
+    stmt.execute()?;
+    Ok(())
+}

docs-examples/rust/restexample/Cargo.toml

@@ -3,6 +3,6 @@ name = "restexample"
 version = "0.1.0"
 edition = "2021"
 
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 [dependencies]
-libtaos = { version = "*", features = ["rest"] }
+libtaos = { version = "0.4.3", features = ["rest"] }
+tokio = { version = "*", features = ["rt", "macros", "rt-multi-thread"] }

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

@@ -14,6 +14,6 @@ fn taos_connect() -> Result<Taos, Error> {
 
 fn main() {
     #[allow(unused_variables)]
-    let taos = taos_connect().unwrap();
+    let taos = taos_connect().expect("connect error");
     println!("Connected")
 }

docs-examples/rust/restexample/examples/insert_example.rs

+use libtaos::*;
+
+#[tokio::main]
+async fn main() -> Result<(), Error> {
+    let taos = TaosCfg::default().connect().expect("fail to connect");
+    taos.create_database("power").await?;
+    taos.exec("CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)").await?;
+    let sql = "INSERT INTO power.d1001 USING power.meters TAGS(Beijing.Chaoyang, 2) VALUES ('2018-10-03 14:38:05.000', 10.30000, 219, 0.31000) ('2018-10-03 14:38:15.000', 12.60000, 218, 0.33000) ('2018-10-03 14:38:16.800', 12.30000, 221, 0.31000)
+    power.d1002 USING power.meters TAGS(Beijing.Chaoyang, 3) VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000)
+    power.d1003 USING power.meters TAGS(Beijing.Haidian, 2) VALUES ('2018-10-03 14:38:05.500', 11.80000, 221, 0.28000) ('2018-10-03 14:38:16.600', 13.40000, 223, 0.29000)
+    power.d1004 USING power.meters TAGS(Beijing.Haidian, 3) VALUES ('2018-10-03 14:38:05.000', 10.80000, 223, 0.29000) ('2018-10-03 14:38:06.500', 11.50000, 221, 0.35000)";
+    let result = taos.query(sql).await?;
+    println!("{:?}", result);
+    Ok(())
+}
+
+// stdout:
+// TaosQueryData { column_meta: [ColumnMeta { name: "affected_rows", type_: Int, bytes: 4 }], rows: [[Int(8)]] }

docs-examples/rust/restexample/examples/query_example.rs

+use libtaos::*;
+
+fn taos_connect() -> Result<Taos, Error> {
+    TaosCfgBuilder::default()
+        .ip("localhost")
+        .user("root")
+        .pass("taosdata")
+        .db("power")
+        .port(6030u16)
+        .build()
+        .expect("TaosCfg builder error")
+        .connect()
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Error> {
+    let taos = taos_connect().expect("connect error");
+    let result = taos.query("SELECT ts, current FROM meters LIMIT 2").await?;
+    // print column names
+    let meta: Vec<ColumnMeta> = result.column_meta;
+    for column in meta {
+        print!("{}\t", column.name)
+    }
+    println!();
+    // print rows
+    let rows: Vec<Vec<Field>> = result.rows;
+    for row in rows {
+        for field in row {
+            print!("{}\t", field);
+        }
+        println!();
+    }
+    Ok(())
+}
+
+// stdout:
+// ts      current
+// 2022-03-28 09:56:51.249 10.3
+// 2022-03-28 09:56:51.749 12.6

docs-examples/rust/schemalessexample/Cargo.toml

+[package]
+name = "schemalessexample"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+libtaos = { version = "0.4.3" }

docs-examples/rust/schemalessexample/examples/influxdb_line_example.rs

+use libtaos::schemaless::*;
+use libtaos::*;
+
+fn main() {
+    let taos = TaosCfg::default().connect().expect("fail to connect");
+    taos.raw_query("CREATE DATABASE test").unwrap();
+    taos.raw_query("USE test").unwrap();
+    let lines = ["meters,location=Beijing.Haidian,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249",
+    "meters,location=Beijing.Haidian,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611250",
+    "meters,location=Beijing.Haidian,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249",
+    "meters,location=Beijing.Haidian,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611250"];
+    let affected_rows = taos
+        .schemaless_insert(
+            &lines,
+            TSDB_SML_LINE_PROTOCOL,
+            TSDB_SML_TIMESTAMP_MILLISECONDS,
+        )
+        .unwrap();
+    println!("affected_rows={}", affected_rows);
+}
+
+// run with:  cargo run --example influxdb_line_example

docs-examples/rust/schemalessexample/examples/opentsdb_json_example.rs

+use libtaos::schemaless::*;
+use libtaos::*;
+
+fn main() {
+    let taos = TaosCfg::default().connect().expect("fail to connect");
+    taos.raw_query("CREATE DATABASE test").unwrap();
+    taos.raw_query("USE test").unwrap();
+    let lines = [
+        r#"[{"metric": "meters.current", "timestamp": 1648432611249, "value": 10.3, "tags": {"location": "Beijing.Chaoyang", "groupid": 2}},
+        {"metric": "meters.voltage", "timestamp": 1648432611249, "value": 219, "tags": {"location": "Beijing.Haidian", "groupid": 1}},
+        {"metric": "meters.current", "timestamp": 1648432611250, "value": 12.6, "tags": {"location": "Beijing.Chaoyang", "groupid": 2}},
+        {"metric": "meters.voltage", "timestamp": 1648432611250, "value": 221, "tags": {"location": "Beijing.Haidian", "groupid": 1}}]"#,
+    ];
+
+    let affected_rows = taos
+        .schemaless_insert(
+            &lines,
+            TSDB_SML_JSON_PROTOCOL,
+            TSDB_SML_TIMESTAMP_NOT_CONFIGURED,
+        )
+        .unwrap();
+    println!("affected_rows={}", affected_rows); // affected_rows=4
+}
+
+// run with:  cargo run --example opentsdb_json_example

docs-examples/rust/schemalessexample/examples/opentsdb_telnet_example.rs

+use libtaos::schemaless::*;
+use libtaos::*;
+
+fn main() {
+    let taos = TaosCfg::default().connect().expect("fail to connect");
+    taos.raw_query("CREATE DATABASE test").unwrap();
+    taos.raw_query("USE test").unwrap();
+    let lines = [
+        "meters.current 1648432611249 10.3 location=Beijing.Chaoyang groupid=2",
+        "meters.current 1648432611250 12.6 location=Beijing.Chaoyang groupid=2",
+        "meters.current 1648432611249 10.8 location=Beijing.Haidian groupid=3",
+        "meters.current 1648432611250 11.3 location=Beijing.Haidian groupid=3",
+        "meters.voltage 1648432611249 219 location=Beijing.Chaoyang groupid=2",
+        "meters.voltage 1648432611250 218 location=Beijing.Chaoyang groupid=2",
+        "meters.voltage 1648432611249 221 location=Beijing.Haidian groupid=3",
+        "meters.voltage 1648432611250 217 location=Beijing.Haidian groupid=3",
+    ];
+    let affected_rows = taos
+        .schemaless_insert(
+            &lines,
+            TSDB_SML_TELNET_PROTOCOL,
+            TSDB_SML_TIMESTAMP_NOT_CONFIGURED,
+        )
+        .unwrap();
+    println!("affected_rows={}", affected_rows); // affected_rows=8
+}
+
+// run with:  cargo run --example opentsdb_telnet_example

docs-examples/rust/schemalessexample/src/main.rs

+fn main() {
+    println!("Hello, world!");
+}