docs(rust): update rust documentations and examples for 3.0 (#16009)

Closes
- [TD-17895](https://jira.taosdata.com:18080/browse/TD-17895)
- [TD-18191](https://jira.taosdata.com:18080/browse/TD-18191)
- [TD-18197](https://jira.taosdata.com:18080/browse/TD-18197)

docs/en/07-develop/03-insert-data/_rust_line.mdx

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

docs/en/07-develop/03-insert-data/_rust_opts_json.mdx

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

docs/en/07-develop/03-insert-data/_rust_opts_telnet.mdx

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

docs/examples/rust/Cargo.toml

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

docs/examples/rust/nativeexample/Cargo.toml

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

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

-use libtaos::*;
+use taos::*;
 
-fn taos_connect() -> Result<Taos, Error> {
-    TaosCfgBuilder::default()
-        .ip("localhost")
-        .user("root")
-        .pass("taosdata")
-        // .db("log") // remove comment if you want to connect to database log by default.
-        .port(6030u16)
-        .build()
-        .expect("TaosCfg builder error")
-        .connect()
-}
-
-fn main() {
+#[tokio::main]
+async fn main() -> Result<(), Error> {
     #[allow(unused_variables)]
-    let taos = taos_connect().unwrap();
-    println!("Connected")
+    let taos = TaosBuilder::from_dsn("taos://")?.build()?;
+    println!("Connected");
+    Ok(())
 }

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

-use bstr::BString;
-use libtaos::*;
+use taos::*;
 
 #[tokio::main]
-async fn main() -> Result<(), Error> {
-    let taos = TaosCfg::default().connect().expect("fail to connect");
+async fn main() -> anyhow::Result<()> {
+    let taos = TaosBuilder::from_dsn("taos://")?.build()?;
     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(?, ?, ?, ?)")?;
+    taos.exec("CREATE STABLE IF NOT EXISTS meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)").await?;
+
+    let mut stmt = Stmt::init(&taos)?;
+    stmt.prepare("INSERT INTO ? USING meters TAGS(?, ?) VALUES(?, ?, ?, ?)")?;
     // bind table name and tags
     stmt.set_tbname_tags(
         "d1001",
-        [
-            Field::Binary(BString::from("California.SanFrancisco")),
-            Field::Int(2),
-        ],
+        &[Value::VarChar("San Fransico".into()), Value::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),
+        ColumnView::from_millis_timestamp(vec![1648432611249]),
+        ColumnView::from_floats(vec![10.3]),
+        ColumnView::from_ints(vec![219]),
+        ColumnView::from_floats(vec![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),
+        ColumnView::from_millis_timestamp(vec![1648432611749]),
+        ColumnView::from_floats(vec![12.6]),
+        ColumnView::from_ints(vec![218]),
+        ColumnView::from_floats(vec![0.33]),
     ];
     stmt.bind(&values2)?;
-    // execute
-    stmt.execute()?;
+    
+    stmt.add_batch()?;
+    
+    // execute.
+    let rows = stmt.execute()?;
+    assert_eq!(rows, 2);
     Ok(())
 }

docs/examples/rust/nativeexample/examples/subscribe_demo.rs

-fn main() {
-  
-}
\ No newline at end of file
+use std::time::Duration;
+
+use chrono::{DateTime, Local};
+use taos::*;
+
+// Query options 2, use deserialization with serde.
+#[derive(Debug, serde::Deserialize)]
+#[allow(dead_code)]
+struct Record {
+    // deserialize timestamp to chrono::DateTime<Local>
+    ts: DateTime<Local>,
+    // float to f32
+    current: Option<f32>,
+    // int to i32
+    voltage: Option<i32>,
+    phase: Option<f32>,
+}
+
+async fn prepare(taos: Taos) -> anyhow::Result<()> {
+    let inserted = taos.exec_many([
+        // create child table
+        "CREATE TABLE `d0` USING `meters` TAGS(0, 'Los Angles')",
+        // insert into child table
+        "INSERT INTO `d0` values(now - 10s, 10, 116, 0.32)",
+        // insert with NULL values
+        "INSERT INTO `d0` values(now - 8s, NULL, NULL, NULL)",
+        // insert and automatically create table with tags if not exists
+        "INSERT INTO `d1` USING `meters` TAGS(1, 'San Francisco') values(now - 9s, 10.1, 119, 0.33)",
+        // insert many records in a single sql
+        "INSERT INTO `d1` values (now-8s, 10, 120, 0.33) (now - 6s, 10, 119, 0.34) (now - 4s, 11.2, 118, 0.322)",
+    ]).await?;
+    assert_eq!(inserted, 6);
+    Ok(())
+}
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let dsn = "taos://localhost:6030";
+    let builder = TaosBuilder::from_dsn(dsn)?;
+
+    let taos = builder.build()?;
+    let db = "tmq";
+
+    // prepare database
+    taos.exec_many([
+        format!("DROP TOPIC IF EXISTS tmq_meters"),
+        format!("DROP DATABASE IF EXISTS `{db}`"),
+        format!("CREATE DATABASE `{db}`"),
+        format!("USE `{db}`"),
+        // create super table
+        format!("CREATE TABLE `meters` (`ts` TIMESTAMP, `current` FLOAT, `voltage` INT, `phase` FLOAT) TAGS (`groupid` INT, `location` BINARY(16))"),
+        // create topic for subscription
+        format!("CREATE TOPIC tmq_meters with META AS DATABASE {db}")
+    ])
+    .await?;
+
+    let task = tokio::spawn(prepare(taos));
+
+    tokio::time::sleep(Duration::from_secs(1)).await;
+
+    // subscribe
+    let tmq = TmqBuilder::from_dsn("taos://localhost:6030/?group.id=test")?;
+
+    let mut consumer = tmq.build()?;
+    consumer.subscribe(["tmq_meters"]).await?;
+
+    {
+        let mut stream = consumer.stream();
+
+        while let Some((offset, message)) = stream.try_next().await? {
+            // get information from offset
+
+            // the topic
+            let topic = offset.topic();
+            // the vgroup id, like partition id in kafka.
+            let vgroup_id = offset.vgroup_id();
+            println!("* in vgroup id {vgroup_id} of topic {topic}\n");
+
+            if let Some(data) = message.into_data() {
+                while let Some(block) = data.fetch_raw_block().await? {
+                    // one block for one table, get table name if needed
+                    let name = block.table_name();
+                    let records: Vec<Record> = block.deserialize().try_collect()?;
+                    println!(
+                        "** table: {}, got {} records: {:#?}\n",
+                        name.unwrap(),
+                        records.len(),
+                        records
+                    );
+                }
+            }
+            consumer.commit(offset).await?;
+        }
+    }
+
+    consumer.unsubscribe().await;
+
+    task.await??;
+
+    Ok(())
+}

docs/examples/rust/restexample/Cargo.toml

@@ -4,5 +4,9 @@ version = "0.1.0"
 edition = "2021"
 
 [dependencies]
-libtaos = { version = "0.4.3", features = ["rest"] }
-tokio = { version = "*", features = ["rt", "macros", "rt-multi-thread"] }
+anyhow = "1"
+chrono = "0.4"
+serde = { version = "1", features = ["derive"] }
+tokio = { version = "1", features = ["rt", "macros", "rt-multi-thread"] }
+
+taos = { version = "0.*" }

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

-use libtaos::*;
-
-fn taos_connect() -> Result<Taos, Error> {
-    TaosCfgBuilder::default()
-        .ip("localhost")
-        .user("root")
-        .pass("taosdata")
-        // .db("log") // remove comment if you want to connect to database log by default.
-        .port(6030u16)
-        .build()
-        .expect("TaosCfg builder error")
-        .connect()
-}
+use taos::*;
 
 #[tokio::main]
-async fn main() {
+async fn main() -> Result<(), Error> {
     #[allow(unused_variables)]
-    let taos = taos_connect().expect("connect error");
-    println!("Connected")
+    let taos = TaosBuilder::from_dsn("taos://")?.build()?;
+    println!("Connected");
+    Ok(())
 }

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

-use libtaos::*;
+use taos::*;
 
 #[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(California.SanFrancisco, 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(California.SanFrancisco, 3) VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000)
-    power.d1003 USING power.meters TAGS(California.LosAngeles, 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(California.LosAngeles, 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);
+async fn main() -> anyhow::Result<()> {
+    let dsn = "ws://";
+    let taos = TaosBuilder::from_dsn(dsn)?.build()?;
+
+
+    taos.exec_many([
+        "DROP DATABASE IF EXISTS power",
+        "CREATE DATABASE power",
+        "USE power",
+        "CREATE STABLE power.meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)"
+    ]).await?;
+
+    let inserted = taos.exec("INSERT INTO 
+    power.d1001 USING power.meters TAGS('San Francisco', 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('San Francisco', 3)
+     VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000)
+    power.d1003 USING power.meters TAGS('Los Angeles', 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('Los Angeles', 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)").await?;
+
+    assert_eq!(inserted, 8);
     Ok(())
 }
-
-// output:
-// TaosQueryData { column_meta: [ColumnMeta { name: "affected_rows", type_: Int, bytes: 4 }], rows: [[Int(8)]] }

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

-use libtaos::*;
+use taos::sync::*;
 
-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?;
+fn main() -> anyhow::Result<()> {
+    let taos = TaosBuilder::from_dsn("ws:///power")?.build()?;
+    let mut result = taos.query("SELECT ts, current FROM meters LIMIT 2")?;
     // print column names
-    let meta: Vec<ColumnMeta> = result.column_meta;
-    for column in meta {
-        print!("{}\t", column.name)
-    }
-    println!();
+    let meta = result.fields();
+    println!("{}", meta.iter().map(|field| field.name()).join("\t"));
+
     // print rows
-    let rows: Vec<Vec<Field>> = result.rows;
+    let rows = result.rows();
     for row in rows {
-        for field in row {
-            print!("{}\t", field);
+        let row = row?;
+        for (_name, value) in row {
+            print!("{}\t", value);
         }
         println!();
     }
     Ok(())
 }
 
-// output:
+// output(suppose you are in +8 timezone):
 // ts      current
-// 2022-03-28 09:56:51.249 10.3
-// 2022-03-28 09:56:51.749 12.6
+// 2018-10-03T14:38:05+08:00       10.3
+// 2018-10-03T14:38:15+08:00       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=California.LosAngeles,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249",
-    "meters,location=California.LosAngeles,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611250",
-    "meters,location=California.LosAngeles,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249",
-    "meters,location=California.LosAngeles,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": "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}}]"#,
-    ];
-
-    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=California.SanFrancisco groupid=2",
-        "meters.current 1648432611250 12.6 location=California.SanFrancisco groupid=2",
-        "meters.current 1648432611249 10.8 location=California.LosAngeles groupid=3",
-        "meters.current 1648432611250 11.3 location=California.LosAngeles groupid=3",
-        "meters.voltage 1648432611249 219 location=California.SanFrancisco groupid=2",
-        "meters.voltage 1648432611250 218 location=California.SanFrancisco groupid=2",
-        "meters.voltage 1648432611249 221 location=California.LosAngeles groupid=3",
-        "meters.voltage 1648432611250 217 location=California.LosAngeles 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!");
-}