docs: refine connect page

docs-cn/04-connect/_connect_cs_native.mdx

-首先添加 [TDengine.Connector](https://www.nuget.org/packages/TDengine.Connector/) 的引用：
-
-```xml title=csharp.csproj
-<Project Sdk="Microsoft.NET.Sdk">
-
-  <PropertyGroup>
-    <OutputType>Exe</OutputType>
-    <TargetFramework>net6.0</TargetFramework>
-    <ImplicitUsings>enable</ImplicitUsings>
-    <Nullable>enable</Nullable>
-    <StartupObject>TDengineExample.ConnectExample</StartupObject>
-  </PropertyGroup>
-
-  <ItemGroup>
-    <PackageReference Include="TDengine.Connector" Version="1.0.6" />
-  </ItemGroup>
-
-</Project>
-```
-
 ```csharp
 {{#include docs-examples/csharp/ConnectExample.cs}}
 ```
+:::info
+C# 连接器目前只支持本地连接。
+
+:::
\ No newline at end of file

docs-cn/04-connect/_connect_go.mdx

-```go-mod title=go.mod
-module goexample
-
-go 1.17
-
-require github.com/taosdata/driver-go/v2 develop
+#### 使用数据库访问统一接口
+```go title="本地连接"
+{{#include docs-examples/go/connect/cgoexample/main.go}}
 ```
-
-```go
+```go title="RESTful 连接"
 {{#include docs-examples/go/connect/restexample/main.go}}
 ```
+#### 使用高级封装
+也可以使用 driver-go 的 af 包建立连接。这个模块封装了 TDengine 的高级功能, 如：动态绑定、订阅等。
+
+```go title="使用 af 包建立本地连接"
+{{#include docs-examples/go/connect/afconn/main.go}}
+```
+
+

docs-cn/04-connect/_connect_go_native.mdx

-:::note
-driver-go 使用 cgo 封装了 taosc 的 API。cgo 需要使用 gcc 编译 C 的源码。因此需要确保你的系统上有 gcc。
-
-:::
-
-```go-mod title=go.mod
-module goexample
-
-go 1.17
-
-require github.com/taosdata/driver-go/v2 develop
-```
-
-```go title="使用 database/sql 包建立连接"
-{{#include docs-examples/go/connect/cgoexample/main.go}}
-```
-
-也可以使用 driver-go 的 af 包建立连接。这个模块封装了 TDengine 的高级功能, 如：动态绑定、订阅等。
-
-```go title="使用 af 包建立连接"
-{{#include docs-examples/go/connect/afconn/main.go}}
-```

docs-cn/04-connect/_connect_java.mdx

-```xml title=pom.xml
-<dependency>
-    <groupId>com.taosdata.jdbc</groupId>
-    <artifactId>taos-jdbcdriver</artifactId>
-    <version>2.0.37</version>
-</dependency>
+```java title="本地连接"
+{{#include docs-examples/java/src/main/java/com/taos/example/JNIConnectExample.java}}
 ```
-
-```java
-{{#include docs-examples/java/src/main/java/com/taos/example/RESTConnectExample.java}}
+```java title="RESTful 连接"
+{{#include docs-examples/java/src/main/java/com/taos/example/RESTConnectExample.java:main}}
 ```
+```java title="WebSocket 连接" {4}
+{{#include docs-examples/java/src/main/java/com/taos/example/WSConnectExample.java:main}}
+```
\ No newline at end of file

docs-cn/04-connect/_connect_java_native.mdx

-```xml title=pom.xml
-<dependency>
-    <groupId>com.taosdata.jdbc</groupId>
-    <artifactId>taos-jdbcdriver</artifactId>
-    <version>2.0.37</version>
-</dependency>
-```
-
-```java
-{{#include docs-examples/java/src/main/java/com/taos/example/JNIConnectExample.java}}
-```

docs-cn/04-connect/_connect_node.mdx

+```js title="本地连接"
+{{#include docs-examples/node/nativeexample/connect.js}}
+```
+```js title="RESTful 连接"
+{{#include docs-examples/node/restexample/connect.js}}
+```
\ No newline at end of file

docs-cn/04-connect/_connect_node_native.mdx

-首先需要安装 node.js 的连接器 `td2.0-connector`：
-
-```bash
-npm install td2.0-connector
-```
-
-:::note
-推荐Node版本大于等于 `node-v12.8.0` 小于 `node-v13.0.0` 
-
-:::
-
-```js
-{{#include docs-examples/node/nativeexample/connect.js}}
-```

docs-cn/04-connect/_connect_python_native.mdx

-推荐使用 `python >= 3.4`。首先需要安装 python 连接器 `taospy`。执行以下命令即可：
-
-```
-pip3 install taospy
-```
-
 ```python
 {{#include docs-examples/python/connect_exmaple.py}}
 ```
+
+:::info
+Python 连接器目前只支持本地连接。
+
+:::

docs-cn/04-connect/_connect_r.mdx

+```R
+> library("DBI")
+> library("rJava")
+> library("RJDBC")
+> driver_path = "C:/TDengine/connector/jdbc/taos-jdbcdriver-2.0.37-dist.jar"
+> driver = JDBC("com.taosdata.jdbc.TSDBDriver", driver_path)
+> conn = dbConnect(driver, "jdbc:TAOS://127.0.0.1:6030/?user=root&password=taosdata")
+> dbGetQuery(conn, "SELECT server_version()")
+  server_version()
+1         2.4.0.12
+> dbDisconnect(conn)
+[1] TRUE
+```
\ No newline at end of file

docs-cn/04-connect/_connect_rust.mdx

-```toml title=Cargo.toml
-[dependencies]
-libtaos = { version = "*", features = ["rest"] }
-```
-
 ```rust
-{{#include docs-examples/rust/restexample/examples/connect.rs}}
+{{#include docs-examples/rust/nativeexample/examples/connect.rs}}
 ```
+:::note
+对于 Rust 连接器， 连接方式的不同只体现在使用的特性不同。如果启用了 "rest" 特性，那么只有 RESTful 的实现会被编译进来。
+
+:::

docs-cn/04-connect/_connect_rust_native.mdx

-```toml title=Cargo.toml
-[dependencies]
-libtaos = { version = "0.4.2"}
-```
-
-```rust
-{{#include docs-examples/rust/nativeexample/examples/connect.rs}}
-```

docs-cn/04-connect/index.mdx

@@ -9,80 +9,171 @@ import ConnJava from "./_connect_java.mdx";
 import ConnGo from "./_connect_go.mdx";
 import ConnRust from "./_connect_rust.mdx";
 import ConnNode from "./_connect_node.mdx";
-import ConnJavaNative from "./_connect_java_native.mdx";
 import ConnPythonNative from "./_connect_python_native.mdx";
-import ConnGoNative from "./_connect_go_native.mdx";
-import ConnRustNative from "./_connect_rust_native.mdx";
-import ConnNodeNative from "./_connect_node_native.mdx";
 import ConnCSNative from "./_connect_cs_native.mdx";
 import ConnC from "./_connect_c.mdx";
+import ConnR from "./_connect_r.mdx";
 
-## 连接器介绍
+TDengine 提高了多种编程语言的连接器方便用户开发应用程序。本节介绍如何使用连接器建立与 TDengine 的连接。
 
-TDengine 提供了丰富的应用程序开发接口，其中包括 C/C++、Java、Python、Go、Node.js、C# 、RESTful 等，便于用户快速开发应用。
+## 连接器建立连接的方式
 
-![image-connecotr](/img/connector.png)
+连接器建立连接的方式，从本质上分为三种:
+  1. 通过 taosAdapter 组件提供的 RESTful API 建立连接。
+  2. 通过 taosAdapter 组件提供的 WebSocket API 建立连接（目前只有 Java 连接器支持）。
+  3. 通过客户端驱动程序直接与服务端程序(taosd)建立连接，这种连接方式下文中简称“本地连接”。
 
-<center>(图：连接器工作原理)</center>
+无论使用何种方式建立连接，连接器都提供了相同或相似的 API 操作数据库，都可以执行 SQL 语句，只是初始化连接的方式稍有不同，用户在使用上不会感到太大差别。
 
-TDengine 提供了 RESTful 接口，应用程序无需安装任何依赖，只需发送 HTTP 请求就可以连接到 TDengine。同时也提供了各语言的连接器，使用驱动程序 (taosc) 连接 TDengine。通过驱动程序可以使用 TDengine 更丰富的功能。
+关键不同点在于：
+1. 使用 RESTful 方式，用户无需安装客户端驱动程序，具有跨平台和易用的优势。
+2. WebSocket 方式可以看作对 RESTful 方式的优化，在批量拉取大量数据的场景具有性能优势。
+3. 使用本地连接可以体验 TDengine 的全部功能，如[原生接口写入](/reference/connector/cpp#参数绑定-api)、[订阅](reference/connector/cpp#数据订阅接口)等等。
 
-## 前提条件
+## 安装连接器
 
-在执行这一步之前，请确保有一个正在运行的，且可以访问到的 TDengine。以下所有示例代码，都假设 TDengine 安装在本机，且 fqdn（默认 localhost） 和 serverPort（默认 6030） 都使用默认配置。
+<Tabs groupId="lang">
+<TabItem label="Java" value="java">
+  
+如果使用 maven 管理项目，只需在 pom.xml 中加入以下依赖。
+
+```xml
+<dependency>
+  <groupId>com.taosdata.jdbc</groupId>
+  <artifactId>taos-jdbcdriver</artifactId>
+  <version>2.0.38</version>
+</dependency>
+```
+
+</TabItem>
+<TabItem label="Python" value="python">
+
+使用 `pip` 从 PyPI 安装:
+```
+pip install taospy
+```
+从 Git URL 安装：
+```
+pip install git+https://github.com/taosdata/taos-connector-python.git
+```
+如果安装了 TDengine 服务端或客户端驱动程序，也可以从本地安装。比如：
+```
+pip install /usr/local/taos/connector/python
+```
+
+</TabItem>
+<TabItem label="Go" value="go">
+
+编辑 `go.mod` 添加 `driver-go` 依赖即可。
+```go-mod title=go.mod
+module goexample
+
+go 1.17
+
+require github.com/taosdata/driver-go/v2 develop
+```
+:::note
+driver-go 使用 cgo 封装了 taosc 的 API。cgo 需要使用 gcc 编译 C 的源码。因此需要确保你的系统上有 gcc。
 
-## 建立连接
+:::
 
-### RESTful
+</TabItem>
+<TabItem label="Rust" value="rust">
 
-如果你安装的是 TDengine 2.4 之后的版本，使用 RESTful 方式连接时还需启动 taosAdaper。
+编辑 `Cargo.toml` 添加 `libtaos` 依赖即可。
+```toml title=Cargo.toml
+[dependencies]
+libtaos = { version = "0.4.2"}
+```
+:::info
+Rust 连接器通过不同的特性区分不同的连接方式。如果要建立 RESTful 连接，需要开启 `rest` 特性：
+```toml
+libtaos = { version = "*", features = ["rest"] }
+```
 
-<Tabs groupId="lang">
-  <TabItem label="curl" value="">
-    <ConnRest />
-  </TabItem>
-  <TabItem label="Java" value="java">
-    <ConnJava />
-  </TabItem>
-  <TabItem label="Go" value="go">
-    <ConnGo />
-  </TabItem>
-  <TabItem label="Rust" value="rust">
-    <ConnRust />
-  </TabItem>
-  <TabItem label="Node.js" value="node">
-    <ConnNode />
-  </TabItem>
+:::
+
+</TabItem>
+<TabItem label="Node.js" value="node">
+
+Node.js 连接器通过不同的包提供不同的连接方式。
+
+1. 安装 Node.js 本地连接器
+  ```
+  npm i td2.0-connector
+  ```
+  :::note
+  推荐Node版本大于等于 `node-v12.8.0` 小于 `node-v13.0.0` 
+
+  :::
+2. 安装 Node.js RESTful 连接器
+  ```
+  npm i td2.0-rest-connector
+  ```
+
+</TabItem>
+<TabItem label="C#" value="csharp">
+
+编辑项目配置文件中添加 [TDengine.Connector](https://www.nuget.org/packages/TDengine.Connector/) 的引用即可：
+
+```xml title=csharp.csproj
+<ItemGroup>
+  <PackageReference Include="TDengine.Connector" Version="1.0.6" />
+</ItemGroup>
+```
+也可通过 dotnet 命令添加：
+```
+dotnet add package TDengine.Connector
+```
+
+</TabItem>
+<TabItem label="R" value="r">
+
+首先系统上要有 TDeninge 客户端驱动，安装目录下有`connector/jdbc/taos-jdbcdriver-xxx-dist.jar`。然后需要安装 R 的依赖包`RJDBC`：
+```R
+install.packages("RJDBC")
+```
+
+</TabItem>
 </Tabs>
 
-### 本地驱动
 
-在没有安装 TDengine 服务端软件的系统上使用本地驱动连接 TDengine, 需要提前[安装客户端驱动程序](/reference/connector/#安装客户端驱动)。
-:::note
-需要单独安装客户端时，为避免客户端驱动和服务端不兼容，请尽量使用一致的版本。
+## 建立连接
 
-:::
+在执行这一步之前，请确保有一个正在运行的，且可以访问到的 TDengine。以下示例代码，都假设 TDengine 安装在本机，且 fqdn（默认 localhost） 和 serverPort（默认 6030） 都使用默认配置。
 
 <Tabs groupId="lang" defaultValue="java">
   <TabItem label="Java" value="java">
-    <ConnJavaNative />
+    <ConnJava />
   </TabItem>
   <TabItem label="Python" value="python">
     <ConnPythonNative />
   </TabItem>
   <TabItem label="Go" value="go">
-    <ConnGoNative />
+      <ConnGo />
   </TabItem>
   <TabItem label="Rust" value="rust">
-    <ConnRustNative />
+    <ConnRust />
   </TabItem>
   <TabItem label="Node.js" value="node">
     <ConnNodeNative />
+    <ConnNode />
   </TabItem>
   <TabItem label="C#" value="csharp">
     <ConnCSNative />
   </TabItem>
+  <TabItem label="R" value="r">
+    <ConnR/>
+  </TabItem>
   <TabItem label="C" value="c">
     <ConnC />
   </TabItem>
 </Tabs>
+
+:::tip
+在没有安装 TDengine 服务端程序的机器上建立本地连接，需要单独[安装客户端驱动](/reference/connector/#安装客户端驱动)。
+为避免客户端驱动和服务端不兼容，请尽量使用一致的版本。另外还要配置好[FQDN](https://www.taosdata.com/blog/2020/09/11/1824.html)。
+
+:::
+
+

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

@@ -172,7 +172,8 @@ Connection conn = DriverManager.getConnection(jdbcUrl);
 连接开启批量拉取方式：
 
 ```java
-String url = "jdbc:TAOS-RS://taosdemo.com:6041/?user=root&password=taosdata";Properties properties = new Properties();
+String url = "jdbc:TAOS-RS://taosdemo.com:6041/?user=root&password=taosdata";
+Properties properties = new Properties();
 properties.setProperty(TSDBDriver.PROPERTY_KEY_BATCH_LOAD, "true");
 Connection connection = DriverManager.getConnection(url, properties);
 ```

docs-examples/java/pom.xml

@@ -20,7 +20,7 @@
     <dependency>
       <groupId>com.taosdata.jdbc</groupId>
       <artifactId>taos-jdbcdriver</artifactId>
-      <version>2.0.37</version>
+      <version>2.0.38</version>
     </dependency>
     <dependency>
       <groupId>junit</groupId>

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

@@ -8,18 +8,14 @@ import java.sql.SQLException;
 import java.util.Properties;
 
 public class RESTConnectExample {
+    // ANCHOR: main
     public static void main(String[] args) throws SQLException {
         String jdbcUrl = "jdbc:TAOS-RS://localhost:6041?user=root&password=taosdata";
         Properties connProps = new Properties();
-        connProps.setProperty(TSDBDriver.PROPERTY_KEY_CHARSET, "UTF-8");
-        connProps.setProperty(TSDBDriver.PROPERTY_KEY_LOCALE, "en_US.UTF-8");
         connProps.setProperty(TSDBDriver.PROPERTY_KEY_TIME_ZONE, "UTC-8");
         Connection conn = DriverManager.getConnection(jdbcUrl, connProps);
         System.out.println("Connected");
         conn.close();
     }
-}
-
-// use
-// String jdbcUrl = "jdbc:TAOS-RS://localhost:6041/dbName?user=root&password=taosdata";
-// if you want to connect to a default database.
\ No newline at end of file
+    // ANCHOR_END: main
+}
\ No newline at end of file

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

@@ -49,7 +49,7 @@ public class RestQueryExample {
     }
 }
 
-// possible stdout:
+// possible output:
 // avg(voltage)	location
 // 222.0	Beijing.Haidian
 // 219.0	Beijing.Chaoyang

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

+package com.taos.example;
+
+import com.taosdata.jdbc.TSDBDriver;
+
+import java.sql.Connection;
+import java.sql.DriverManager;
+import java.sql.SQLException;
+import java.util.Properties;
+
+public class WSConnectExample {
+    // ANCHOR: main
+    public static void main(String[] args) throws SQLException {
+        String jdbcUrl = "jdbc:TAOS-RS://localhost:6041?user=root&password=taosdata";
+        Properties connProps = new Properties();
+        connProps.setProperty(TSDBDriver.PROPERTY_KEY_BATCH_LOAD, "true");
+        Connection conn = DriverManager.getConnection(jdbcUrl, connProps);
+        System.out.println("Connected");
+        conn.close();
+    }
+    // ANCHOR_END: main
+}

docs-examples/node/nativeexample/connect.js

@@ -9,5 +9,5 @@ var conn = taos.connect({
 conn.close();
 
 // run with: node connect.js
-// stdout:
+// output:
 // Successfully connected to TDengine

docs-examples/node/nativeexample/insert_example.js

@@ -22,7 +22,7 @@ power.d1004 USING power.meters TAGS(Beijing.Haidian, 3) VALUES ('2018-10-03 14:3
 }
 
 // run with: node insert_example.js
-// stdout:
+// output:
 // Successfully connected to TDengine
 // Query OK, 0 row(s) affected (0.00509570s)
 // Query OK, 0 row(s) affected (0.00130880s)

docs-examples/node/nativeexample/query_example.js

@@ -7,7 +7,7 @@ query.execute().then(function (result) {
   result.pretty();
 });
 
-// stdout:
+// output:
 // Successfully connected to TDengine
 // Query OK, 2 row(s) in set (0.00317767s)
 

docs-examples/node/package.json

@@ -4,6 +4,7 @@
   "main": "index.js",
   "license": "MIT",
   "dependencies": {
-    "td2.0-connector": "^2.0.11"
+    "td2.0-connector": "^2.0.11",
+    "td2.0-rest-connector": "^1.0.0"
   }
 }

docs-examples/node/restexample/connect.js

+const { options, connect } = require("td2.0-rest-connector");
+
+async function test() {
+  options.path = "/rest/sqlt";
+  options.host = "localhost";
+  let conn = connect(options);
+  let cursor = conn.cursor();
+  try {
+    let res = await cursor.query("SELECT server_version()");
+    res.toString();
+  } catch (err) {
+    console.log(err);
+  }
+}
+test();
+
+// output:
+// server_version() |
+// ===================
+// 2.4.0.12         |

docs-examples/python/async_query_example.py

@@ -56,7 +56,7 @@ def test_query(conn):
 if __name__ == "__main__":
     test_query(connect())
 
-# possible stdout:
+# possible output:
 # { count: 0, done: False }
 # fetched  8 rows
 # 1538548685000 10.300000 219

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

@@ -14,5 +14,5 @@ async fn main() -> Result<(), Error> {
     Ok(())
 }
 
-// stdout:
+// output:
 // TaosQueryData { column_meta: [ColumnMeta { name: "affected_rows", type_: Int, bytes: 4 }], rows: [[Int(8)]] }

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

@@ -33,7 +33,7 @@ async fn main() -> Result<(), Error> {
     Ok(())
 }
 
-// stdout:
+// output:
 // ts      current
 // 2022-03-28 09:56:51.249 10.3
 // 2022-03-28 09:56:51.749 12.6