diff --git a/docs-cn/14-reference/03-connector/03-connector.mdx b/docs-cn/14-reference/03-connector/03-connector.mdx index 2f417d65a27aa76d161c11a70594af890cda49c6..aadfa3e885e1036b01580339390dc57742d16e53 100644 --- 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”状态量在线程之间相互干扰（但连接的查询和写入操作都是线程安全的）。 diff --git a/docs-cn/14-reference/03-connector/_verify_linux.mdx b/docs-cn/14-reference/03-connector/_verify_linux.mdx index 794f95dd702a9684fd1299e5b0fd380b174ca04c..6af11ff2951b5155edbba173255c61228bdd1cc6 100644 --- a/docs-cn/14-reference/03-connector/_verify_linux.mdx +++ b/docs-cn/14-reference/03-connector/_verify_linux.mdx @@ -1,4 +1,4 @@ -在 Linux shell 下直接执行 taos，应该就能正常连接到 TDegine 服务，进入到 taos shell 界面，示例如下： +在 Linux shell 下直接执行 taos，应该就能正常连接到 TDegine 服务，进入到 TDengine CLI 界面，示例如下： ```sql $ taos diff --git a/docs-cn/14-reference/03-connector/_verify_windows.mdx b/docs-cn/14-reference/03-connector/_verify_windows.mdx index 0e16f272ae478ffbd1eebb2dfec4d4ea7c47e18d..b4ec391b7d7e06353518e614132448b82b65a450 100644 --- a/docs-cn/14-reference/03-connector/_verify_windows.mdx +++ b/docs-cn/14-reference/03-connector/_verify_windows.mdx @@ -1,4 +1,4 @@ -在 cmd 下进入到 c:\TDengine 目录下直接执行 taos.exe，应该就能正常链接到 tdegine 服务，进入到 taos shell 界面，示例如下： +在 cmd 下进入到 c:\TDengine 目录下直接执行 taos.exe，应该就能正常链接到 tdegine 服务，进入到 TDengine CLI 界面，示例如下： ```sql C:\TDengine>taos diff --git a/docs-cn/14-reference/03-connector/_windows_install.mdx b/docs-cn/14-reference/03-connector/_windows_install.mdx index 3275101d07317e15824cc2a8bc31d6d9282d4c6b..148adcae59ef123fede4b734b6cab4648c4a8b62 100644 --- 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 diff --git a/docs-cn/14-reference/03-connector/cpp.mdx b/docs-cn/14-reference/03-connector/cpp.mdx index af4f43ca38c139088f79b564ae33306ba5846a3e..f0b206d3e7c58c355b2f06e8a8b6e14bbb569ab6 100644 --- 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 diff --git a/docs-cn/14-reference/03-connector/java.mdx b/docs-cn/14-reference/03-connector/java.mdx index 65a75e21ff6eece7164daac27a618cbed4412dbd..2ba772897f0c84dfca45c609883c0926d6d8f494 100644 --- 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 的对比 - + @@ -46,17 +46,17 @@ TDengine 的 JDBC 驱动实现尽可能与关系型数据库驱动保持一致 - + - +
对比项JDBC-JNIJDBC 本地连接 JDBC-RESTful
写入性能JDBC-RESTful 是 JDBC-JNI 的 50%～90% JDBC-RESTful 是 JDBC 本地连接的 50%～90%
查询性能JDBC-RESTful 与 JDBC-JNI 没有差别JDBC-RESTful 与 JDBC 本地连接没有差别
注意： -- 与 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 的功能。 diff --git a/docs-cn/14-reference/03-connector/python.mdx b/docs-cn/14-reference/03-connector/python.mdx index 7b1dc1ff1d0024b0605b82c7eb1e85465b1d66fe..ce4cf9a3d721b96a8b59f6482b4158c669ebf7e6 100644 --- 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` 环境变量中使用。