docs: connector refine (#11607)

* docs: refine connector doc [TD-14839] * docs: use TDengine CLI [TD-14839] * docs: replace JNI with navtive connection [TD-14839]

docs: connector refine (#11607)
* docs: refine connector doc [TD-14839] * docs: use TDengine CLI [TD-14839] * docs: replace JNI with navtive connection [TD-14839]
885ad6fc · sangshuduo · GitHub · 6725baf8 · 885ad6fc · 885ad6fc
7 changed file
--- a/docs-cn/14-reference/03-connector/03-connector.mdx
+++ b/docs-cn/14-reference/03-connector/03-connector.mdx
@@ -63,7 +63,7 @@ TDengine 提供了丰富的应用程序开发接口，其中包括支持使用 C

 :::warning

- 在没有安装 TDengine 服务端软件的系统中使用连接器（除 RESTful 外）访问 TDengine 数据库，需要安装相应版本的客户端安装包来使应用驱动（Linux 系统中文件名为 libtaos.so，Windows 系统中为 taos.dll）被安装在系统中，否则会产生无法找到相应库文件的错误。
+- 在没有安装 TDengine 服务端软件的系统中使用连接器（除 RESTful 外）访问 TDengine 数据库，需要安装相应版本的客户端安装包来使客户端驱动（Linux 系统中文件名为 libtaos.so，Windows 系统中为 taos.dll）被安装在系统中，否则会产生无法找到相应库文件的错误。
 - 所有执行 SQL 语句的 API，例如 C/C++ Connector 中的 `tao_query`、`taos_query_a`、`taos_subscribe` 等，以及其它语言中与它们对应的 API，每次都只能执行一条 SQL 语句，如果实际参数中包含了多条语句，它们的行为是未定义的。
 - 升级 TDengine 到 2.0.8.0 版本的用户，必须更新 JDBC。连接 TDengine 必须升级 taos-jdbcdriver 到 2.0.12 及以上。详细的版本依赖关系请参见 [taos-jdbcdriver 文档](/reference/connector/java#version)。
 - 无论选用何种编程语言的连接器，2.0 及以上版本的 TDengine 推荐数据库应用的每个线程都建立一个独立的连接，或基于线程建立连接池，以避免连接内的“USE statement”状态量在线程之间相互干扰（但连接的查询和写入操作都是线程安全的）。

--- a/docs-cn/14-reference/03-connector/_verify_linux.mdx
+++ b/docs-cn/14-reference/03-connector/_verify_linux.mdx
-在 Linux shell 下直接执行 taos，应该就能正常连接到 TDegine 服务，进入到 taos shell 界面，示例如下：
+在 Linux shell 下直接执行 taos，应该就能正常连接到 TDegine 服务，进入到 TDengine CLI 界面，示例如下：

 ```sql
 $ taos

--- a/docs-cn/14-reference/03-connector/_verify_windows.mdx
+++ b/docs-cn/14-reference/03-connector/_verify_windows.mdx
-在 cmd 下进入到 c:\TDengine 目录下直接执行 taos.exe，应该就能正常链接到 tdegine 服务，进入到 taos shell 界面，示例如下：
+在 cmd 下进入到 c:\TDengine 目录下直接执行 taos.exe，应该就能正常链接到 tdegine 服务，进入到 TDengine CLI 界面，示例如下：

 ```sql
  C:\TDengine>taos

--- a/docs-cn/14-reference/03-connector/_windows_install.mdx
+++ b/docs-cn/14-reference/03-connector/_windows_install.mdx
@@ -6,7 +6,7 @@

   默认安装路径为：C:\TDengine，其中包括以下文件(目录)：

-   - _taos.exe_：taos shell 命令行程序
+   - _taos.exe_：TDengine CLI 命令行程序
   - _cfg_ : 配置文件目录
   - _driver_: 应用驱动动态链接库
   - _examples_: 示例程序 bash/C/C#/go/JDBC/Python/Node.js

--- a/docs-cn/14-reference/03-connector/cpp.mdx
+++ b/docs-cn/14-reference/03-connector/cpp.mdx
@@ -23,7 +23,7 @@ C/C++的 API 类似于 MySQL 的 C API。应用程序使用时，需要包含 TD

 注意：

- 在编译时需要链接 TDengine 动态库。Linux 为 _libtaos.so_ ，安装后，位于 _/usr/local/taos/driver_。Windows 为 taos.dll，安装后位于 _C:\TDengine_。
+- 在编译时需要链接 TDengine 客户端驱动。Linux 为 _libtaos.so_ ，安装后，位于 _/usr/local/taos/driver_。Windows 为 taos.dll，安装后位于 _C:\TDengine_。
 - 如未特别说明，当 API 的返回值是整数时，_0_ 代表成功，其它是代表失败原因的错误码，当返回值是指针时， _NULL_ 表示失败。
 - 在 taoserror.h 中有所有的错误码，以及对应的原因描述。

@@ -199,7 +199,7 @@ TDengine 的异步 API 均采用非阻塞调用模式。应用程序可以用多

 说明：如果 `taos_stmt_execute` 执行成功，假如不需要改变 SQL 语句的话，那么是可以复用 `taos_stmt_prepare` 的解析结果，直接进行第 3 ～ 6 步绑定新数据的。但如果执行出错，那么并不建议继续在当前的环境上下文下继续工作，而是建议释放资源，然后从 `taos_stmt_init` 步骤重新开始。

-除 C/C++ 语言外，TDengine 的 Java 语言 JNI Connector 也提供参数绑定接口支持，具体请另外参见：[参数绑定接口的 Java 用法](/reference/connector/java#通过参数绑定写入数据)。
+除 C/C++ 语言外，TDengine 的 Java 语言本地连接 Connector 也提供参数绑定接口支持，具体请另外参见：[参数绑定接口的 Java 用法](/reference/connector/java#通过参数绑定写入数据)。

 接口相关的具体函数如下（也可以参考 [prepare.c](https://github.com/taosdata/TDengine/blob/develop/examples/c/prepare.c) 文件中使用对应函数的方式）：

@@ -213,7 +213,7 @@ TDengine 的异步 API 均采用非阻塞调用模式。应用程序可以用多

 - `int taos_stmt_bind_param(TAOS_STMT *stmt, TAOS_BIND *bind)`

-  不如 `taos_stmt_bind_param_batch` 效率高，但可以支持非 INSERT 类型的 SQL 语句。  
+  不如 `taos_stmt_bind_param_batch` 效率高，但可以支持非 INSERT 类型的 SQL 语句。
  进行参数绑定，bind 指向一个数组（代表所要绑定的一行数据），需保证此数组中的元素数量和顺序与 SQL 语句中的参数完全一致。TAOS_BIND 的使用方法与 MySQL 中的 MYSQL_BIND 一致，具体定义如下：

  ```c

--- a/docs-cn/14-reference/03-connector/java.mdx
+++ b/docs-cn/14-reference/03-connector/java.mdx
@@ -6,14 +6,14 @@ title: Java Connector

 ## 总体介绍

-`taos-jdbcdriver` 的实现包括 2 种形式： JDBC-JNI 和 JDBC-RESTful（taos-jdbcdriver-2.0.18 开始支持 JDBC-RESTful）。 JDBC-JNI 通过调用客户端 libtaos.so（或 taos.dll ）的本地方法实现， JDBC-RESTful 则在内部封装了 RESTful 接口实现。
+`taos-jdbcdriver` 的实现包括 2 种形式： JDBC 本地连接和 JDBC-RESTful（taos-jdbcdriver-2.0.18 开始支持 JDBC-RESTful）。 JDBC 本地连接通过调用客户端驱动 libtaos.so（或 taos.dll ）的本地方法实现， JDBC-RESTful 则在内部封装了 RESTful 接口实现。

 ![tdengine-connector](/img/tdengine-jdbc-connector.png)

 上图显示了 3 种 Java 应用使用连接器访问 TDengine 的方式：

- JDBC-JNI：Java 应用在物理节点 1（pnode1）上使用 JDBC-JNI 的 API ，直接调用客户端 API（libtaos.so 或 taos.dll）将写入和查询请求发送到位于物理节点 2（pnode2）上的 taosd 实例。
- RESTful：应用将 SQL 发送给位于物理节点 2（pnode2）上的 RESTful 连接器，再调用客户端 API（libtaos.so）。
+- JDBC 本地连接：Java 应用在物理节点 1（pnode1）上使用 JDBC 本地连接的 API ，直接调用客户端驱动（libtaos.so 或 taos.dll）的 API 将写入和查询请求发送到位于物理节点 2（pnode2）上的 taosd 实例。
+- RESTful：应用将 SQL 发送给位于物理节点 2（pnode2）上的 RESTful 连接器，再调用客户端驱动 API。
 - JDBC-RESTful：Java 应用通过 JDBC-RESTful 的 API ，将 SQL 封装成一个 RESTful 请求，发送给物理节点 2 的 RESTful 连接器。

 TDengine 的 JDBC 驱动实现尽可能与关系型数据库驱动保持一致，但 TDengine 与关系对象型数据库的使用场景和技术特征存在差异，导致 `taos-jdbcdriver` 与传统的 JDBC driver 也存在一定差异。在使用时需要注意以下几点：
@@ -21,12 +21,12 @@ TDengine 的 JDBC 驱动实现尽可能与关系型数据库驱动保持一致
 - TDengine 目前不支持针对单条数据记录的删除操作。
 - 目前不支持事务操作。

-### JDBC-JNI 和 JDBC-RESTful 的对比
+### JDBC 本地连接和 JDBC-RESTful 的对比

 <table>
  <tr align="center">
    <th>对比项</th>
-    <th>JDBC-JNI</th>
+    <th>JDBC 本地连接</th>
    <th>JDBC-RESTful</th>
  </tr>
  <tr align="center">
@@ -46,17 +46,17 @@ TDengine 的 JDBC 驱动实现尽可能与关系型数据库驱动保持一致
  </tr>
  <tr align="center">
    <td>写入性能</td>
-    <td colspan="2">JDBC-RESTful 是 JDBC-JNI 的 50%～90% </td>
+    <td colspan="2">JDBC-RESTful 是 JDBC 本地连接的 50%～90% </td>
  </tr>
  <tr align="center">
    <td>查询性能</td>
-    <td colspan="2">JDBC-RESTful 与 JDBC-JNI 没有差别</td>
+    <td colspan="2">JDBC-RESTful 与 JDBC 本地连接没有差别</td>
  </tr>
 </table>

 注意：

- 与 JNI 方式不同，RESTful 接口是无状态的。在使用 JDBC-RESTful 时，需要在 sql 中指定表、超级表的数据库名称。例如：
+- 与本地连接方式不同，RESTful 接口是无状态的。在使用 JDBC-RESTful 时，需要在 SQL 中指定表、超级表的数据库名称。例如：

 ```sql
 INSERT INTO test.t1 USING test.weather (ts, temperature) TAGS('beijing') VALUES(now, 24.6);
@@ -106,11 +106,11 @@ TDengine 目前支持时间戳、数字、字符、布尔类型，与 Java 对

 1. Linux 或 Windows 操作系统
 2. Java 1.8 以上运行时环境
-3. TDengine-client（使用 JDBC-JNI 时必须，使用 JDBC-RESTful 时非必须）
+3. TDengine-client（使用 JDBC 本地连接时必须，使用 JDBC-RESTful 时非必须）

 **注意**：由于 TDengine 的应用驱动是使用 C 语言开发的，使用 taos-jdbcdriver 驱动包时需要依赖系统对应的本地函数库。

- libtaos.so 在 Linux 系统中成功安装 TDengine 后，依赖的本地函数库 libtaos.so 文件会被自动拷贝至 /usr/lib/libtaos.so，该目录包含在 Linux 自动扫描路径上，无需单独指定。
+- libtaos.so 在 Linux 系统中成功安装 TDengine 后，依赖的本地客户端驱动 libtaos.so 文件会被自动拷贝至 /usr/lib/libtaos.so，该目录包含在 Linux 自动扫描路径上，无需单独指定。
 - taos.dll 在 Windows 系统中安装完客户端之后，驱动包依赖的 taos.dll 文件会自动拷贝到系统默认搜索路径 C:/Windows/System32 下，同样无需要单独指定。

 **注意**：在 Windows 环境开发时需要安装 TDengine 对应的 [windows 客户端](https://www.taosdata.com/cn/all-downloads/#TDengine-Windows-Client)，Linux 服务器安装完 TDengine 之后默认已安装 client，也可以单独安装 [Linux 客户端](/get-started/) 连接远程 TDengine Server。
@@ -161,7 +161,7 @@ Connection conn = DriverManager.getConnection(jdbcUrl);

 以上示例，使用 **JDBC-RESTful** 的 driver，建立了到 hostname 为 taosdemo.com，端口为 6041，数据库名为 test 的连接。这个 URL 中指定用户名（user）为 root，密码（password）为 taosdata。

-使用 JDBC-RESTful 接口，不需要依赖本地函数库。与 JDBC-JNI 相比，仅需要：
+使用 JDBC-RESTful 接口，不需要依赖本地函数库。与 JDBC 本地连接相比，仅需要：

 1. driverClass 指定为“com.taosdata.jdbc.rs.RestfulDriver”；
 2. jdbcUrl 以“jdbc:TAOS-RS://”开头；
@@ -178,7 +178,7 @@ properties.setProperty(TSDBDriver.PROPERTY_KEY_BATCH_LOAD, "true");
 Connection connection = DriverManager.getConnection(url, properties);
 ```

-如果希望获得更好的写入和查询性能，Java 应用可以使用 **JDBC-JNI** 的 driver，如下所示：
+如果希望获得更好的写入和查询性能，Java 应用可以使用 **JDBC 本地连接** 的 driver，如下所示：

 ```java
 Class.forName("com.taosdata.jdbc.TSDBDriver");
@@ -186,13 +186,13 @@ String jdbcUrl = "jdbc:TAOS://taosdemo.com:6030/test?user=root&password=taosdata
 Connection conn = DriverManager.getConnection(jdbcUrl);
 ```

-以上示例，使用了 JDBC-JNI 的 driver，建立了到 hostname 为 taosdemo.com，端口为 6030（TDengine 的默认端口），数据库名为 test 的连接。这个 URL 中指定用户名（user）为 root，密码（password）为 taosdata。
+以上示例，使用了 JDBC 本地连接的 driver，建立了到 hostname 为 taosdemo.com，端口为 6030（TDengine 的默认端口），数据库名为 test 的连接。这个 URL 中指定用户名（user）为 root，密码（password）为 taosdata。

-**注意**：使用 JDBC-JNI 的 driver，taos-jdbcdriver 驱动包时需要依赖系统对应的本地函数库（Linux 下是 libtaos.so；Windows 下是 taos.dll）。
+**注意**：使用 JDBC 本地连接的 driver，taos-jdbcdriver 驱动包时需要依赖系统对应的本地客户端驱动（Linux 下是 libtaos.so；Windows 下是 taos.dll）。

 > 在 Windows 环境开发时需要安装 TDengine 对应的 [windows 客户端](https://www.taosdata.com/cn/all-downloads/#TDengine-Windows-Client)，Linux 服务器安装完 TDengine 之后默认已安装 client，也可以单独安装 [Linux 客户端](/get-started/) 连接远程 TDengine Server。

-JDBC-JNI 的使用请参见[视频教程](https://www.taosdata.com/blog/2020/11/11/1955.html)。
+JDBC 本地连接的使用请参见[视频教程](https://www.taosdata.com/blog/2020/11/11/1955.html)。

 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}]`
@@ -238,13 +238,13 @@ properties 中的配置参数如下：
 - TSDBDriver.PROPERTY_KEY_CHARSET：客户端使用的字符集，默认值为系统字符集。
 - TSDBDriver.PROPERTY_KEY_LOCALE：客户端语言环境，默认值系统当前 locale。
 - TSDBDriver.PROPERTY_KEY_TIME_ZONE：客户端使用的时区，默认值为系统当前时区。
- TSDBDriver.PROPERTY_KEY_BATCH_LOAD: 仅在使用 JDBC-JNI 时生效。true：在执行查询时批量拉取结果集；false：逐行拉取结果集。默认值为：false。
+- TSDBDriver.PROPERTY_KEY_BATCH_LOAD: 仅在使用 JDBC 本地连接时生效。true：在执行查询时批量拉取结果集；false：逐行拉取结果集。默认值为：false。
 - TSDBDriver.PROPERTY_KEY_TIMESTAMP_FORMAT: 仅在使用 JDBC-RESTful 时生效. 'TIMESTAMP'：结果集中 timestamp 类型的字段为一个 long 值; 'UTC'：结果集中 timestamp 类型的字段为一个 UTC 时间格式的字符串; 'STRING'：结果集中 timestamp 类型的字段为一个本地时间格式的字符串。默认值为'STRING'。
 - TSDBDriver.PROPERTY_KEY_BATCH_ERROR_IGNORE：true：在执行 Statement 的 executeBatch 时，如果中间有一条 sql 执行失败，继续执行下面的 sq 了。false：不再执行失败 sql 后的任何语句。默认值为：false。

 #### 使用客户端配置文件建立连接

-当使用 JDBC-JNI 连接 TDengine 集群时，可以使用客户端配置文件，在客户端配置文件中指定集群的 firstEp、secondEp 参数。如下所示：
+当使用 JDBC 本地连接连接 TDengine 集群时，可以使用客户端配置文件，在客户端配置文件中指定集群的 firstEp、secondEp 参数。如下所示：

 1. 在 Java 应用中不指定 hostname 和 port

@@ -362,7 +362,7 @@ try (Statement statement = connection.createStatement()) {
 }
 ```

-JDBC 连接器可能报错的错误码包括 3 种：JDBC driver 本身的报错（错误码在 0x2301 到 0x2350 之间），JNI 方法的报错（错误码在 0x2351 到 0x2400 之间），TDengine 其他功能模块的报错。
+JDBC 连接器可能报错的错误码包括 3 种：JDBC driver 本身的报错（错误码在 0x2301 到 0x2350 之间），本地连接方法的报错（错误码在 0x2351 到 0x2400 之间），TDengine 其他功能模块的报错。

 具体的错误码请参考：

@@ -371,7 +371,7 @@ JDBC 连接器可能报错的错误码包括 3 种：JDBC driver 本身的报错

 ### 通过参数绑定写入数据

-从 2.1.2.0 版本开始，TDengine 的 JDBC-JNI 实现大幅改进了参数绑定方式对数据写入（INSERT）场景的支持。采用这种方式写入数据时，能避免 SQL 语法解析的资源消耗，从而在很多情况下显著提升写入性能。
+从 2.1.2.0 版本开始，TDengine 的 JDBC 本地连接实现大幅改进了参数绑定方式对数据写入（INSERT）场景的支持。采用这种方式写入数据时，能避免 SQL 语法解析的资源消耗，从而在很多情况下显著提升写入性能。
 注意：

 - JDBC-RESTful 实现并不提供参数绑定这种使用方式
@@ -680,7 +680,7 @@ public class SchemalessInsertTest {

 ### 设置客户端参数

-从 TDengine-2.3.5.0 版本开始，jdbc driver 支持在应用的第一次连接中，设置 TDengine 的客户端参数。Driver 支持 JDBC-JNI 方式中，通过 jdbcUrl 和 properties 两种方式设置 client parameter。
+从 TDengine-2.3.5.0 版本开始，jdbc driver 支持在应用的第一次连接中，设置 TDengine 的客户端参数。Driver 支持 JDBC 本地连接方式中，通过 jdbcUrl 和 properties 两种方式设置 client parameter。
 注意：

 - JDBC-RESTful 不支持设置 client parameter 的功能。

--- a/docs-cn/14-reference/03-connector/python.mdx
+++ b/docs-cn/14-reference/03-connector/python.mdx
@@ -35,7 +35,7 @@ pip2 install taospy
 pip3 install taospy
 ```

-Python 命令行依赖 taos 动态库 `libtaos.so` 或 `taos.dll`, 对于 Windows 客户端，安装 TDengine windows 客户端后，如果不能正常 `import taos`，可以将 `C:\TDengine\driver\taos.dll` 拷贝到 `C:\windows\system32` 目录后重新尝试。
+Python 命令行依赖 taos 客户端驱动 `libtaos.so` 或 `taos.dll`, 对于 Windows 客户端，安装 TDengine windows 客户端后，如果不能正常 `import taos`，可以将 `C:\TDengine\driver\taos.dll` 拷贝到 `C:\windows\system32` 目录后重新尝试。

 对于无法联网用户，可以将 TDengine 客户端中的 `connector/python` 路径（Linux 下其安装路径为 `/usr/local/taos/connector/python/`，Windows 下默认安装路径为 `C:\TDengine\connector\python`）添加到 `PYTHONPATH` 环境变量中使用。