From b2325071a72c4c37c98046beb9cd7801bcd706b0 Mon Sep 17 00:00:00 2001 From: Shuduo Sang Date: Tue, 17 May 2022 18:11:41 +0800 Subject: [PATCH] docs: refine reference docs (#12590) * docs: reference doc in English [TD-15603] * docs: reference docs in English [TD-15603] * docs: refine reference English docs [TD-15603] * docs: refine reference docs * docs: refine refince docs --- docs-cn/14-reference/03-connector/java.mdx | 6 +- docs-cn/14-reference/03-connector/python.mdx | 12 +-- .../03-connector/03-connector.mdx | 4 +- .../03-connector/_preparition.mdx | 2 +- .../03-connector/_verify_linux.mdx | 2 +- .../03-connector/_verify_windows.mdx | 2 +- docs-en/14-reference/03-connector/cpp.mdx | 58 +++++++------- docs-en/14-reference/03-connector/csharp.mdx | 18 ++--- docs-en/14-reference/03-connector/go.mdx | 31 ++++---- docs-en/14-reference/03-connector/java.mdx | 78 +++++++++---------- docs-en/14-reference/03-connector/node.mdx | 32 ++++---- docs-en/14-reference/03-connector/python.mdx | 62 +++++++-------- docs-en/14-reference/03-connector/rust.mdx | 26 +++---- .../cn/08.connector/01.java/docs.md | 6 +- 14 files changed, 164 insertions(+), 175 deletions(-) diff --git a/docs-cn/14-reference/03-connector/java.mdx b/docs-cn/14-reference/03-connector/java.mdx index f80a019a4a..55abf84fd5 100644 --- a/docs-cn/14-reference/03-connector/java.mdx +++ b/docs-cn/14-reference/03-connector/java.mdx @@ -9,7 +9,7 @@ description: TDengine Java 连接器基于标准 JDBC API 实现, 并提供原 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -`taos-jdbcdriver` 是 TDengine 的官方 Java 语言连接器，Java 开发人员可以通过它开发存取 TDengine 数据库的应用软件。`taos-jdbcdriver` 实现了 JDBC driver 标准的接口，并提供两种形式的连接器。一种是通过 TDengine 客户端驱动程序（taosc）原生连接 TDengine 实例，支持数据写入、查询、订阅、schemaless 接口和参数绑定接口等功能，一种是通过 taosAdapter 提供的 REST 接口连接 TDengine 实例（2.0.18 及更高版本）。REST 连接实现的功能集合和原生连接有少量不同。 +`taos-jdbcdriver` 是 TDengine 的官方 Java 语言连接器，Java 开发人员可以通过它开发存取 TDengine 数据库的应用软件。`taos-jdbcdriver` 实现了 JDBC driver 标准的接口，并提供两种形式的连接器。一种是通过 TDengine 客户端驱动程序（taosc）原生连接 TDengine 实例，支持数据写入、查询、订阅、schemaless 接口和参数绑定接口等功能，一种是通过 taosAdapter 提供的 REST 接口连接 TDengine 实例（2.4.0.0 及更高版本）。REST 连接实现的功能集合和原生连接有少量不同。 ![tdengine-connector](tdengine-jdbc-connector.png) @@ -804,7 +804,7 @@ Query OK, 1 row(s) in set (0.000141s) 请参考：[JDBC example](https://github.com/taosdata/TDengine/tree/develop/examples/JDBC) -## 重要更新记录 +## 最近更新记录 | taos-jdbcdriver 版本 | 主要变化 | | :------------------: | :----------------------------: | @@ -814,7 +814,7 @@ Query OK, 1 row(s) in set (0.000141s) ## 常见问题 -1. 使用 Statement 的 `addBatch` 和 `executeBatch` 来执行“批量写入/更行”，为什么没有带来性能上的提升？ +1. 使用 Statement 的 `addBatch()` 和 `executeBatch()` 来执行“批量写入/更新”，为什么没有带来性能上的提升？ **原因**：TDengine 的 JDBC 实现中，通过 `addBatch` 方法提交的 SQL 语句，会按照添加的顺序，依次执行，这种方式没有减少与服务端的交互次数，不会带来性能上的提升。 diff --git a/docs-cn/14-reference/03-connector/python.mdx b/docs-cn/14-reference/03-connector/python.mdx index 5e6cdfba4f..6608fb7bd2 100644 --- a/docs-cn/14-reference/03-connector/python.mdx +++ b/docs-cn/14-reference/03-connector/python.mdx @@ -122,7 +122,7 @@ Requirement already satisfied: taospy in c:\users\username\appdata\local\program -请确保 TDengine 集群已经启动， 且集群中机器的 FQDN （如果启动的是单机版，FQDN 默认为 hostname）在本机能够解析, 可用 ping 命令进行测试： +请确保 TDengine 集群已经启动， 且集群中机器的 FQDN （如果启动的是单机版，FQDN 默认为 hostname）在本机能够解析, 可用 `ping` 命令进行测试： ``` ping @@ -197,7 +197,7 @@ curl -u root:taosdata http://:/rest/sql -d "select server_version()" {{#include docs-examples/python/connect_rest_examples.py:connect}} ``` -`connect` 函数的所有参数都是可选的关键字参数。下面是连接参数的具体说明： +`connect()` 函数的所有参数都是可选的关键字参数。下面是连接参数的具体说明： - `host`： 要连接的主机。默认是 localhost。 - `user`： TDenigne 用户名。默认是 root。 @@ -205,10 +205,6 @@ curl -u root:taosdata http://:/rest/sql -d "select server_version()" - `port`: taosAdapter REST 服务监听端口。默认是 6041. - `timeout`: HTTP 请求超时时间。单位为秒。默认为 `socket._GLOBAL_DEFAULT_TIMEOUT`。 一般无需配置。 -:::note - -::: - @@ -232,12 +228,12 @@ curl -u root:taosdata http://:/rest/sql -d "select server_version()" ``` :::tip -查询结果只能获取一次。比如上面的示例中 `featch_all` 和 `fetch_all_into_dict` 只能用一个。重复获取得到的结果为空列表。 +查询结果只能获取一次。比如上面的示例中 `fetch_all()` 和 `fetch_all_into_dict()` 只能用一个。重复获取得到的结果为空列表。 ::: ##### TaosResult 类的使用 -上面 `TaosConnection` 类的使用示例中，我们已经展示了两种获取查询结果的方法： `featch_all` 和 `fetch_all_into_dict`。除此之外 `TaosResult` 还提供了按行迭代(`rows_iter`)或按数据块迭代(`blocks_iter`)结果集的方法。在查询数据量较大的场景，使用这两个方法会更高效。 +上面 `TaosConnection` 类的使用示例中，我们已经展示了两种获取查询结果的方法： `fetch_all()` 和 `fetch_all_into_dict()`。除此之外 `TaosResult` 还提供了按行迭代(`rows_iter`)或按数据块迭代(`blocks_iter`)结果集的方法。在查询数据量较大的场景，使用这两个方法会更高效。 ```python title="blocks_iter 方法" {{#include docs-examples/python/result_set_examples.py}} diff --git a/docs-en/14-reference/03-connector/03-connector.mdx b/docs-en/14-reference/03-connector/03-connector.mdx index f392692f80..00e979a563 100644 --- a/docs-en/14-reference/03-connector/03-connector.mdx +++ b/docs-en/14-reference/03-connector/03-connector.mdx @@ -2,7 +2,7 @@ title: Connector --- -TDengine provides a rich application development interface. To facilitate users to develop their own applications quickly, TDengine supports connectors for multiple programming languages, including official connectors for C/C++, Java, Python, Go, Node.js, C#, and Rust. These connectors support connecting to TDengine clusters using both native interfaces (taosc) and REST interfaces (not supported in some languages yet). Community developers have also contributed several unofficial connectors, such as the ADO.NET connector, the Lua connector, and the PHP connector. +TDengine provides a rich set of APIs (application development interface). To facilitate users to develop their applications quickly, TDengine supports connectors for multiple programming languages, including official connectors for C/C++, Java, Python, Go, Node.js, C#, and Rust. These connectors support connecting to TDengine clusters using both native interfaces (taosc) and REST interfaces (not supported in a few languages yet). Community developers have also contributed several unofficial connectors, such as the ADO.NET connector, the Lua connector, and the PHP connector. ![image-connector](/img/connector.png) @@ -84,7 +84,7 @@ import InstallOnLinux from "./_windows_install.mdx"; import VerifyWindows from "./_verify_windows.mdx"; import VerifyLinux from "./_verify_linux.mdx"; -## Install client driver +## Install Client Driver :::info The client driver needs to be installed if you use the native interface connector on a system that does not have the TDengine server software installed. diff --git a/docs-en/14-reference/03-connector/_preparition.mdx b/docs-en/14-reference/03-connector/_preparition.mdx index 8f48d997b1..906fd3b66c 100644 --- a/docs-en/14-reference/03-connector/_preparition.mdx +++ b/docs-en/14-reference/03-connector/_preparition.mdx @@ -4,7 +4,7 @@ Since the TDengine client driver is written in C, using the native connection requires loading the client driver shared library file, which is usually included in the TDengine installer. You can install either standard TDengine server installation package or [TDengine client installtion package](/get-started/). For Windows development, you need to install the corresponding [Windows client](https://www.taosdata.com/cn/all-downloads/#TDengine-Windows-Client) for TDengine. -- libtaos.so: After successful installation of TDengine on a Linux system, the dependent Linux version of the client driver libtaos.so file will be automatically copied to /usr/lib/libtaos.so, which is included in the Linux scanable path and does not need to be specified separately. +- libtaos.so: After successful installation of TDengine on a Linux system, the dependent Linux version of the client driver `libtaos.so` file will be automatically linked to `/usr/lib/libtaos.so`, which is included in the Linux scannable path and does not need to be specified separately. - taos.dll: After installing the client on Windows, the dependent Windows version of the client driver taos.dll file will be automatically copied to the system default search path C:/Windows/System32, again without the need to specify it separately. ::: diff --git a/docs-en/14-reference/03-connector/_verify_linux.mdx b/docs-en/14-reference/03-connector/_verify_linux.mdx index 291c3d95aa..a6e5455224 100644 --- a/docs-en/14-reference/03-connector/_verify_linux.mdx +++ b/docs-en/14-reference/03-connector/_verify_linux.mdx @@ -1,4 +1,4 @@ -Execute `taos` directly from the Linux shell to connect to the TDengine service and enter the TDengine CLI interface, as shown in the following example. +Execute TDengine CLI program `taos` directly from the Linux shell to connect to the TDengine service and enter the TDengine CLI interface, as shown in the following example. ```text $ taos diff --git a/docs-en/14-reference/03-connector/_verify_windows.mdx b/docs-en/14-reference/03-connector/_verify_windows.mdx index bb3e97856f..c3d6af84d8 100644 --- a/docs-en/14-reference/03-connector/_verify_windows.mdx +++ b/docs-en/14-reference/03-connector/_verify_windows.mdx @@ -1,4 +1,4 @@ -Go to the C:\TDengine directory from `cmd` and execute `taos.exe` directly to connect to the TDengine service and enter the TDengine CLI interface, for example, as follows: +Go to the `C:\TDengine` directory from `cmd` and execute TDengine CLI program `taos.exe` directly to connect to the TDengine service and enter the TDengine CLI interface, for example, as follows: ```text C:\TDengine>taos diff --git a/docs-en/14-reference/03-connector/cpp.mdx b/docs-en/14-reference/03-connector/cpp.mdx index 6e653df0ae..5633f2c3e1 100644 --- a/docs-en/14-reference/03-connector/cpp.mdx +++ b/docs-en/14-reference/03-connector/cpp.mdx @@ -4,7 +4,7 @@ sidebar_label: C/C++ title: C/C++ Connector --- -C/C++ developers can use TDengine's client driver, the C/C++ connector (hereafter referred to as the TDengine client driver), to develop their applications to connect to TDengine clusters for data storing, querying, and other functions. To use it, you need to include the TDengine header file _taos.h_, which lists the function prototypes of the provided APIs; the application also needs to link to the corresponding dynamic libraries on the platform where it is located. +C/C++ developers can use TDengine's client driver and the C/C++ connector, to develop their applications to connect to TDengine clusters for data writing, querying, and other functions. To use it, you need to include the TDengine header file _taos.h_, which lists the function prototypes of the provided APIs; the application also needs to link to the corresponding dynamic libraries on the platform where it is located. ```c #include @@ -26,7 +26,7 @@ Please refer to [list of supported platforms](/reference/connector#supported pla ## Supported versions -The version number of the TDengine client driver and the version number of the TDengine server require one-to-one correspondence and recommend using the same client driver as the TDengine server. Although a lower version of the client driver is compatible with a higher version of the server, if the first three version numbers are the same (i.e., only the fourth version number is different), it is not recommended. It is strongly discouraged to use a high version of the client driver to access a low version of the server. +The version number of the TDengine client driver and the version number of the TDengine server require one-to-one correspondence and recommend using the same version of client driver as what the TDengine server version is. Although a lower version of the client driver is compatible to work with a higher version of the server, if the first three version numbers are the same (i.e., only the fourth version number is different), but it is not recommended. It is strongly discouraged to use a higher version of the client driver to access a lower version of the TDengine server. ## Installation steps @@ -34,7 +34,7 @@ Please refer to the [Installation Guide](/reference/connector#installation steps ## Establishing a connection -The basic process of accessing a TDengine cluster using the client driver is to establish a connection, query and write, close the connection, and clear the resource. +The basic process of accessing a TDengine cluster using the client driver is to establish a connection, query and write data, close the connection, and clear the resource. The following is sample code for establishing a connection, which omits the query and writing sections and shows how to establish a connection, close a connection, and clear a resource. @@ -51,12 +51,12 @@ The following is sample code for establishing a connection, which omits the quer taos_cleanup(); ``` -In the above example code, `taos_connect` establishes a connection to port 6030 on the host where the client application is located, `taos_close` closes the current connection, and `taos_cleanup` clears the resources requested and used by the client driver. +In the above example code, `taos_connect()` establishes a connection to port 6030 on the host where the client application is located, `taos_close()` closes the current connection, and `taos_cleanup()` clears the resources requested and used by the client driver. :::note - If not specified, when the return value of the API is an integer, _0_ means success, the others are error codes representing the reason for failure, and when the return value is a pointer, _NULL_ means failure. -- All error codes and their corresponding causes are described in the taoserror.h file. +- All error codes and their corresponding causes are described in the `taoserror.h` file. ::: @@ -120,15 +120,15 @@ This section shows sample code for standard access methods to TDengine clusters :::info -More example code and downloads are available at [github](https://github.com/taosdata/TDengine/tree/develop/examples/c) -You can find it in the installation directory under the examples/c path. This directory has a makefile and can be compiled under Linux by executing make directly. -**Hint:** When compiling in an ARM environment, please remove `-msse4.2` from the makefile. This option is only supported on x64/x86 hardware platforms. +More example code and downloads are available at [GitHub](https://github.com/taosdata/TDengine/tree/develop/examples/c). +You can find it in the installation directory under the `examples/c` path. This directory has a makefile and can be compiled under Linux by executing `make` directly. +**Hint:** When compiling in an ARM environment, please remove `-msse4.2` from the makefile. This option is only supported on the x64/x86 hardware platforms. ::: ## API reference -The following describes the basic API, synchronous API, asynchronous API, subscription API, and modeless write API of TDengine client driver, respectively. +The following describes the basic API, synchronous API, asynchronous API, subscription API, and schemaless write API of TDengine client driver, respectively. ### Basic API @@ -154,7 +154,7 @@ The base API is used to do things like create database connections and provide a - `TAOS *taos_connect(const char *host, const char *user, const char *pass, const char *db, int port)` - Creates a database connection and initializes the connection context. Among the parameters required from the user are + Creates a database connection and initializes the connection context. Among the parameters required from the user are: - host: FQDN of any node in the TDengine cluster - user: user name @@ -162,7 +162,7 @@ The base API is used to do things like create database connections and provide a - db: database name, if the user does not provide, it can also be connected correctly, the user can create a new database through this connection, if the user provides the database name, it means that the database user has already created, the default use of the database - port: the port the tasd program is listening on - A null return value indicates a failure. The application needs to save the returned parameters for subsequent use. + NULL indicates a failure. The application needs to save the returned parameters for subsequent use. :::info The same process can connect to multiple TDengine clusters according to different host/port @@ -187,7 +187,7 @@ The APIs described in this subsection are all synchronous interfaces. After bein - `TAOS_RES* taos_query(TAOS *taos, const char *sql)` - Executes an SQL statement, either a DQL, DML, or DDL statement. The `taos` parameter is a handle obtained with `taos_connect()`. You can't tell if the result failed by whether the return value is `NULL`, but by parsing the error code in the result set with the `taos_errno()` function. + Executes an SQL command, either a DQL, DML, or DDL statement. The `taos` parameter is a handle obtained with `taos_connect()`. You can't tell if the result failed by whether the return value is `NULL`, but by parsing the error code in the result set with the `taos_errno()` function. - `int taos_result_precision(TAOS_RES *res)` @@ -248,15 +248,15 @@ TDengine version 2.0 and above recommends that each thread of a database applica ### Asynchronous query API -TDengine also provides a higher performance asynchronous API to handle data insertion and query operations. Given the same hardware and software environment, the asynchronous API can run data insertion 2 to 4 times faster than the synchronous API. The asynchronous API is called non-blocking and returns immediately before the system completes a specific database operation. The calling thread can go to work on other tasks, which can improve the performance of the whole application. Asynchronous APIs are particularly advantageous in the case of severe network latency. +TDengine also provides a set of asynchronous API to handle data insertion and query operations with a higher performance. Given the same hardware and software environment, the asynchronous API can run data insertion 2 to 4 times faster than the synchronous API. The asynchronous API is called non-blocking and returns immediately before the system completes a specific database operation. The calling thread can go to work on other tasks, which can improve the performance of the whole application. Asynchronous APIs are particularly advantageous in the case of severe network latency. -The asynchronous APIs require the application to provide a callback function with the following parameters: the first two parameters are consistent, and the third parameter depends on the API. The first parameter, param, is provided to the system when the application calls the asynchronous API. It is used for the callback so that the application can retrieve the context of the specific operation, depending on the implementation. The second parameter is the result set of the SQL operation. If it is empty, such as insert operation, it means that there are no records returned, and if it is not empty, such as select operation, it means that there are records returned. +The asynchronous APIs require the application to provide a callback function with the following parameters: the first two parameters are consistent, and the third parameter depends on the API. The first parameter, `param`, is provided to the system when the application calls the asynchronous API. It is used for the callback so that the application can retrieve the context of the specific operation, depending on the implementation. The second parameter is the result set of the SQL operation. If it is NULL, such as insert operation, it means that there are no records returned, and if it is not NULL, such as select operation, it means that there are records returned. The asynchronous API has relatively high user requirements, so users can use it selectively according to specific application scenarios. The following are two important asynchronous APIs. - `void taos_query_a(TAOS *taos, const char *sql, void (*fp)(void *param, TAOS_RES *, int code), void *param);` - Execute SQL statements asynchronously. + Execute SQL command asynchronously. - taos: the database connection returned by calling `taos_connect()` - sql: the SQL statement to be executed @@ -270,13 +270,13 @@ The asynchronous API has relatively high user requirements, so users can use it - res: the result set returned by the `taos_query_a()` callback - fp: callback function. Its parameter `param` is a user-definable parameter structure passed to the callback function; `numOfRows` is the number of rows of the fetched data (not a function of the entire query result set). In the callback function, the application can iterate forward to fetch each row of records in the batch by calling `taos_fetch_row()`. After reading all the rows in a block, the application needs to continue calling `taos_fetch_rows_a()` in the callback function to get the next batch of rows for processing until the number of rows returned, `numOfRows`, is zero (result return complete) or the number of rows is negative (query error). -TDengine's asynchronous APIs all use a non-blocking call pattern. Applications can open multiple tables simultaneously using multiple threads and perform queries or inserts on each open table at the same time. It is important to note that **client applications must ensure that operations on the same table are fully serialized**. i.e., no second insert or query operation can be performed while an insert or query operation on the same table is incomplete (not returned). +All TDengine's asynchronous APIs use a non-blocking call pattern. Applications can open multiple tables simultaneously using multiple threads and perform queries or inserts on each open table at the same time. It is important to note that **client applications must ensure that operations on the same table are fully serialized**. i.e., no second insert or query operation can be performed while an insert or query operation on the same table is incomplete (not returned). ### Parameter Binding API -In addition to direct calls to `taos_query()` to perform queries, TDengine also provides a Prepare API that supports parameter binding, similar in style to MySQL, and currently only supports using a question mark `? ` to represent the parameter to be bound. +In addition to direct calls to `taos_query()` to perform queries, TDengine also provides a set of `bind` APIs that supports parameter binding, similar in style to MySQL, and currently only supports using a question mark `? ` to represent the parameter to be bound. -Starting with versions 2.1.1.0 and 2.1.2.0, TDengine has significantly improved the parameter binding interface's support for data writing (INSERT) scenarios. This avoids the resource consumption of SQL syntax parsing when writing data through the parameter binding interface, thus significantly improving write performance in most cases. A typical operation, in this case, is as follows. +Starting with versions 2.1.1.0 and 2.1.2.0, TDengine has significantly improved the bind APIs to support for data writing (INSERT) scenarios. This avoids the resource consumption of SQL syntax parsing when writing data through the parameter binding interface, thus significantly improving write performance in most cases. A typical operation, in this case, is as follows. 1. call `taos_stmt_init()` to create the parameter binding object. 2. call `taos_stmt_prepare()` to parse the INSERT statement. 3. @@ -288,7 +288,7 @@ Starting with versions 2.1.1.0 and 2.1.2.0, TDengine has significantly improved 8. call `taos_stmt_execute()` to execute the prepared batch instructions. 9. When execution is complete, call `taos_stmt_close()` to release all resources. -Note: If `taos_stmt_execute()` succeeds, you can reuse the parsed result of `taos_stmt_prepare()` to bind new data in steps 3 to 6 if you don't need to change the SQL statement. However, if there is an execution error, it is not recommended to continue working in the current context but release the resources and start again with `taos_stmt_init()` steps. +Note: If `taos_stmt_execute()` succeeds, you can reuse the parsed result of `taos_stmt_prepare()` to bind new data in steps 3 to 6 if you don't need to change the SQL command. However, if there is an execution error, it is not recommended to continue working in the current context but release the resources and start again with `taos_stmt_init()` steps. The specific functions related to the interface are as follows (see also the [prepare.c](https://github.com/taosdata/TDengine/blob/develop/examples/c/prepare.c) file for the way to use the corresponding functions) @@ -298,7 +298,7 @@ The specific functions related to the interface are as follows (see also the [pr - ` int taos_stmt_prepare(TAOS_STMT *stmt, const char *sql, unsigned long length)` - Parse a SQL statement, and bind the parsed result and parameter information to stmt. If the parameter length is greater than 0, use this parameter as the length of the SQL statement. If it is equal to 0, the length of the SQL statement will be determined automatically. + Parse a SQL command, and bind the parsed result and parameter information to `stmt`. If the parameter length is greater than 0, use this parameter as the length of the SQL command. If it is equal to 0, the length of the SQL command will be determined automatically. - `int taos_stmt_bind_param(TAOS_STMT *stmt, TAOS_BIND *bind)` @@ -320,12 +320,12 @@ The specific functions related to the interface are as follows (see also the [pr - `int taos_stmt_set_tbname(TAOS_STMT* stmt, const char* name)` (New in version 2.1.1.0, only supported for replacing parameter values in INSERT statements) - When the table name in the SQL statement uses `? ` placeholder, you can use this function to bind a specific table name. + When the table name in the SQL command uses `? ` placeholder, you can use this function to bind a specific table name. - `int taos_stmt_set_tbname_tags(TAOS_STMT* stmt, const char* name, TAOS_BIND* tags)` (New in version 2.1.2.0, only supported for replacing parameter values in INSERT statements) - When the table name and TAGS in the SQL statement both use `? `, you can use this function to bind the specific table name and the specific TAGS value. The most typical usage scenario is an INSERT statement that uses the automatic table building function (the current version does not support specifying specific TAGS columns.) The number of columns in the TAGS parameter needs to be the same as the number of TAGS requested in the SQL statement. + When the table name and TAGS in the SQL command both use `? `, you can use this function to bind the specific table name and the specific TAGS value. The most typical usage scenario is an INSERT statement that uses the automatic table building function (the current version does not support specifying specific TAGS columns.) The number of columns in the TAGS parameter needs to be the same as the number of TAGS requested in the SQL command. - `int taos_stmt_bind_param_batch(TAOS_STMT* stmt, TAOS_MULTI_BIND* bind)` @@ -345,7 +345,7 @@ The specific functions related to the interface are as follows (see also the [pr - ` int taos_stmt_add_batch(TAOS_STMT *stmt)` - Adds the currently bound parameter to the batch. After calling this function, you can call `taos_stmt_bind_param()` or `taos_stmt_bind_param_batch()` again to bind a new parameter. Note that this function only supports INSERT/IMPORT statements. Other SQL statements such as SELECT will return an error. + Adds the currently bound parameter to the batch. After calling this function, you can call `taos_stmt_bind_param()` or `taos_stmt_bind_param_batch()` again to bind a new parameter. Note that this function only supports INSERT/IMPORT statements. Other SQL command such as SELECT will return an error. - `int taos_stmt_execute(TAOS_STMT *stmt)` @@ -366,7 +366,7 @@ The specific functions related to the interface are as follows (see also the [pr ### Write-without-mode API -In addition to writing data using the SQL method or the parameter binding API, writing can also be done using Schemaless, which eliminates the need to create a super table/data sub-table structure in advance and writes the data directly. The TDengine system automatically creates and maintains the required table structure based on the written data content. The use of Schemaless is described in the chapter [Schemaless Writing](/reference/schemaless/), and the C/C++ API used with it is described here. +In addition to writing data using the SQL method or the parameter binding API, writing can also be done using schemaless writing, which eliminates the need to create a super table/data sub-table structure in advance and writes the data directly. The TDengine system automatically creates and maintains the required table structure based on the written data content. The use of schemaless writing is described in the chapter [Schemaless Writing](/reference/schemaless/), and the C/C++ API used with it is described here. - `TAOS_RES* taos_schemaless_insert(TAOS* taos, const char* lines[], int numLines, int protocol, int precision)` @@ -374,11 +374,11 @@ In addition to writing data using the SQL method or the parameter binding API, w This interface writes the text data of the line protocol to TDengine. **Parameter description** - taos: database connection, established by the `taos_connect()` function. - lines: text data. A pattern-free text string that meets the parsing format requirements. - numLines: the number of lines of text data, cannot be 0. - protocol: the protocol type of the lines, used to identify the text data format. - precision: precision string for the timestamp in the text data. + - taos: database connection, established by the `taos_connect()` function. + - lines: text data. A pattern-free text string that meets the parsing format requirements. + - numLines: the number of lines of text data, cannot be 0. + - protocol: the protocol type of the lines, used to identify the text data format. + - precision: precision string for the timestamp in the text data. **return value** TAOS_RES structure, application can get error message by using `taos_errstr()` and also error code by using `taos_errno()`. diff --git a/docs-en/14-reference/03-connector/csharp.mdx b/docs-en/14-reference/03-connector/csharp.mdx index 336039c18f..66f1d4defd 100644 --- a/docs-en/14-reference/03-connector/csharp.mdx +++ b/docs-en/14-reference/03-connector/csharp.mdx @@ -17,9 +17,9 @@ import CSQuery from "../../04-develop/04-query-data/_cs.mdx" import CSAsyncQuery from "../../04-develop/04-query-data/_cs_async.mdx" -TDengine.Connector` is a C# language connector provided by TDengine that allows C# developers to develop C# applications that access TDengine cluster data. +`TDengine.Connector` is a C# language connector provided by TDengine that allows C# developers to develop C# applications that access TDengine cluster data. -The `TDengine.Connector` connector supports connection to TDengine runtime instances via the TDengine client driver (taosc), providing data writing, querying, subscription, schemaless data writing, bind interface data writing, etc. The `TDengine.Connector` currently does not provide a REST connection. REST connection is not yet available. Users can write their RESTful APIs by referring to the [RESTful APIs](https://docs.taosdata.com//reference/restful-api/) documentation. +The `TDengine.Connector` connector supports connect to TDengine instances via the TDengine client driver (taosc), providing data writing, querying, subscription, schemaless writing, bind interface, etc. The `TDengine.Connector` currently does not provide a REST connection interface. Developers can write their RESTful application by referring to the [RESTful APIs](https://docs.taosdata.com//reference/restful-api/) documentation. This article describes how to install `TDengine.Connector` in a Linux or Windows environment and connect to TDengine clusters via `TDengine.Connector` to perform basic operations such as data writing and querying. @@ -35,11 +35,11 @@ Please refer to [version support list](/reference/connector#version support) ## Supported features -1. connection management -2. general query -3. continuous query -4. parameter binding -5. subscription function +1. Connection Mmanagement +2. General Query +3. Continuous Query +4. Parameter Binding +5. Subscription 6. Schemaless ## Installation Steps @@ -50,7 +50,7 @@ Please refer to [version support list](/reference/connector#version support) * [Nuget Client](https://docs.microsoft.com/en-us/nuget/install-nuget-client-tools) (optional installation) * Install TDengine client driver, please refer to [Install client driver](/reference/connector#Install client driver) for details -### Install using dotnet CLI +### Install via dotnet CLI @@ -179,7 +179,7 @@ namespace TDengineExample 1. "Unable to establish connection", "Unable to resolve FQDN" - Usually, because the FQDN configuration is incorrect, you can refer to [How to understand TDengine's FQDN thoroughly](https://www.taosdata.com/blog/2021/07/29/2741.html) to solve it. 2. + Usually, it cause by the FQDN configuration is incorrect, you can refer to [How to understand TDengine's FQDN (Chinese)](https://www.taosdata.com/blog/2021/07/29/2741.html) to solve it. 2. Unhandled exception. System.DllNotFoundException: Unable to load DLL 'taos' or one of its dependencies: The specified module cannot be found. diff --git a/docs-en/14-reference/03-connector/go.mdx b/docs-en/14-reference/03-connector/go.mdx index 90f6041042..fb8f8d7ca5 100644 --- a/docs-en/14-reference/03-connector/go.mdx +++ b/docs-en/14-reference/03-connector/go.mdx @@ -15,9 +15,9 @@ import GoOpenTSDBTelnet from "../../04-develop/03-insert-data/_go_opts_telnet.md import GoOpenTSDBJson from "../../04-develop/03-insert-data/_go_opts_json.mdx" import GoQuery from "../../04-develop/04-query-data/_go.mdx" -`driver-go` is the official Go language connector for TDengine, which implements the interface to the Go language [ database/sql ](https://golang.org/pkg/database/sql/) package. Go developers can use it to develop applications that access TDengine cluster data. +`driver-go` is the official Go language connector for TDengine, which implements the interface to the Go language [database/sql](https://golang.org/pkg/database/sql/) package. Go developers can use it to develop applications that access TDengine cluster data. -`driver-go` provides two ways to establish connections. One is **native connection**, which connects to TDengine runtime instances natively through the TDengine client driver (taosc), supporting data writing, querying, subscriptions, schemaless interface, and parameter binding interface. The other is the **REST connection**, which connects to TDengine runtime instances via the REST interface provided by taosAdapter. The set of features implemented by the REST connection differs slightly from the native connection. +`driver-go` provides two ways to establish connections. One is **native connection**, which connects to TDengine instances natively through the TDengine client driver (taosc), supporting data writing, querying, subscriptions, schemaless writing, and bind interface. The other is the **REST connection**, which connects to TDengine instances via the REST interface provided by taosAdapter. The set of features implemented by the REST connection differs slightly from the native connection. This article describes how to install `driver-go` and connect to TDengine clusters and perform basic operations such as data query and data writing through `driver-go`. @@ -36,7 +36,7 @@ Please refer to [version support list](/reference/connector#version support) ### Native connections -A "native connection" is established by the connector directly to the TDengine runtime instance via the TDengine client driver (taosc). The supported functional features are +A "native connection" is established by the connector directly to the TDengine instance via the TDengine client driver (taosc). The supported functional features are: * Normal queries * Continuous queries @@ -46,7 +46,7 @@ A "native connection" is established by the connector directly to the TDengine r ### REST connection -A "REST connection" is a connection between a connector and a TDengine runtime instance via the REST API provided by the taosAdapter component. The following features are supported. +A "REST connection" is a connection between the application and the TDengine instance via the REST API provided by the taosAdapter component. The following features are supported: * General queries * Continuous queries @@ -75,7 +75,7 @@ Configure the environment variables and check the command. go mod init taos-demo ``` text -2. Introduce taosSql: ``text +2. Introduce taosSql ```go import ( @@ -101,7 +101,7 @@ Configure the environment variables and check the command. ### Data source name (DSN) -Data source names have a standard format, e.g. [PEAR DB](http://pear.php.net/manual/en/package.database.db.intro-dsn.php), but no type prefix (square brackets indicate optionally): the +Data source names have a standard format, e.g. [PEAR DB](http://pear.php.net/manual/en/package.database.db.intro-dsn.php), but no type prefix (square brackets indicate optionally): ``` text [username[:password]@][protocol[(address)]]/[dbname][?param1=value1&... ¶mN=valueN] @@ -112,7 +112,8 @@ DSN in full form. ```text username:password@protocol(address)/dbname?param=value ``` -### Connecting using connectors + +### Connecting via connector @@ -121,7 +122,7 @@ _taosSql_ implements Go's `database/sql/driver` interface via cgo. You can use t Use `taosSql` as `driverName` and use a correct [DSN](#DSN) as `dataSourceName`, DSN supports the following parameters. -* configPath specifies the taos.cfg directory +* configPath specifies the `taos.cfg` directory Example. @@ -210,7 +211,7 @@ func main() { ## Usage limitations -Since the REST interface is stateless, the `use db` syntax will not work. You need to put the db name into the SQL statement, e.g. `create table if not exists tb1 (ts timestamp, a int)` to `create table if not exists test.tb1 (ts timestamp, a int)` otherwise it will report the error `[0x217] Database not specified or available`. +Since the REST interface is stateless, the `use db` syntax will not work. You need to put the db name into the SQL command, e.g. `create table if not exists tb1 (ts timestamp, a int)` to `create table if not exists test.tb1 (ts timestamp, a int)` otherwise it will report the error `[0x217] Database not specified or available`. You can also put the db name in the DSN by changing `root:taosdata@http(localhost:6041)/` to `root:taosdata@http(localhost:6041)/test`. This method is supported by taosAdapter in TDengine 2.4.0.5. is supported since TDengine 2.4.0.5. Executing the `create database` statement when the specified db does not exist will not report an error while executing other queries or writing against that db will report an error. @@ -268,27 +269,27 @@ func main() { 1. Cannot find the package `github.com/taosdata/driver-go/v2/taosRestful` - Change the reference to `github.com/taosdata/driver-go/v2` in the require block in `go.mod` to `github.com/taosdata/driver-go/v2 develop`, then execute `go mod tidy`. + Change the `github.com/taosdata/driver-go/v2` line in the require block of the `go.mod` file to `github.com/taosdata/driver-go/v2 develop`, then execute `go mod tidy`. -2. stmt (parameter binding) related interface in database/sql crashes +2. bind interface in database/sql crashes REST does not support parameter binding related interface. It is recommended to use `db.Exec` and `db.Query`. 3. error `[0x217] Database not specified or available` after executing other statements with `use db` statement - The execution of SQL statements in the REST interface is not contextual, so using `use db` statement will not work, see the usage restrictions section above. + The execution of SQL command in the REST interface is not contextual, so using `use db` statement will not work, see the usage restrictions section above. -4. use taosSql without error use taosRestful with error `[0x217] Database not specified or available` +4. use `taosSql` without error but use `taosRestful` with error `[0x217] Database not specified or available` Because the REST interface is stateless, using the `use db` statement will not take effect. See the usage restrictions section above. 5. Upgrade `github.com/taosdata/driver-go/v2/taosRestful` - Change the reference to `github.com/taosdata/driver-go/v2` in the `go.mod` file to `github.com/taosdata/driver-go/v2 develop`, then execute `go mod tidy`. + Change the `github.com/taosdata/driver-go/v2` line in the `go.mod` file to `github.com/taosdata/driver-go/v2 develop`, then execute `go mod tidy`. 6. `readBufferSize` parameter has no significant effect after being increased - If you increase `readBufferSize` will reduce the number of `syscall` calls when fetching results. If the query result is more petite, modifying this parameter will not improve significantly. If you increase the parameter too much, the bottleneck will be parsing JSON data. If you need to optimize the query speed, you must adjust the value according to the actual situation to achieve the best query result. + If you increase `readBufferSize` will reduce the number of `syscall` calls when fetching results. If the query result is smaller, modifying this parameter will not improve significantly. If you increase the parameter value too much, the bottleneck will be parsing JSON data. If you need to optimize the query speed, you must adjust the value according to the actual situation to achieve the best query result. 7. `disableCompression` parameter is set to `false` when the query efficiency is reduced diff --git a/docs-en/14-reference/03-connector/java.mdx b/docs-en/14-reference/03-connector/java.mdx index 7530f4734a..194475f0a3 100644 --- a/docs-en/14-reference/03-connector/java.mdx +++ b/docs-en/14-reference/03-connector/java.mdx @@ -9,16 +9,16 @@ description: TDengine Java based on JDBC API and provide both native and REST co import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -'taos-jdbcdriver' is TDengine's official Java language connector, which allows Java developers to develop applications that access the TDengine database. 'taos-jdbcdriver' implements the interface of the JDBC driver standard and provides two forms of connectors. One is to connect to a TDengine instance natively through the TDengine client driver (taosc), which supports functions such as data writing, querying, subscription, schemaless interface, and parameter binding interface. And the other is to connect to a TDengine instance through the REST interface provided by taosAdapter (2.0.18 and later). Rest connections implement small differences between the set of features implemented and native connections. +'taos-jdbcdriver' is TDengine's official Java language connector, which allows Java developers to develop applications that access the TDengine database. 'taos-jdbcdriver' implements the interface of the JDBC driver standard and provides two forms of connectors. One is to connect to a TDengine instance natively through the TDengine client driver (taosc), which supports functions including data writing, querying, subscription, schemaless writing, and bind interface. And the other is to connect to a TDengine instance through the REST interface provided by taosAdapter (2.4.0.0 and later). REST connections implement has a slight differences to compare the set of features implemented and native connections. -! [tdengine-connector] (tdengine-jdbc-connector.png) +![tdengine-connector](tdengine-jdbc-connector.png) -The preceding diagram shows two ways for a Java app to access TDengine using connectors: +The preceding diagram shows two ways for a Java app to access TDengine via connector: -- JDBC native connectivity: Java applications use TSDBDriver on physical node 1 (pnode1) to call client-driven directly (libtaos.so or taos.dll) APIs to send writing and query requests to taosd instances located on physical node 2 (pnode2). -- JDBC REST connection: The Java application encapsulates the SQL as a REST request via RestfulDriver, sends it to the REST server of physical node 2 (taosAdapter), requests taosd through the REST server, and returns the result. +- JDBC native connection: Java applications use TSDBDriver on physical node 1 (pnode1) to call client-driven directly (`libtaos.so` or `taos.dll`) APIs to send writing and query requests to taosd instances located on physical node 2 (pnode2). +- JDBC REST connection: The Java application encapsulates the SQL as a REST request via RestfulDriver, sends it to the REST server of physical node 2 (taosAdapter), requests TDengine server through the REST server, and returns the result. -Using REST connectivity, which does not rely on TDengine client drivers, can be cross-platform, more convenient, and flexible but has about 30% lower performance than native connectors. +Using REST connection, which does not rely on TDengine client drivers.It can be cross-platform more convenient and flexible but introduce about 30% lower performance than native connection. :::info TDengine's JDBC driver implementation is as consistent as possible with the relational database driver. Still, there are differences in the use scenarios and technical characteristics of TDengine and relational object databases, so 'taos-jdbcdriver' also has some differences from traditional JDBC drivers. You need to pay attention to the following points when using: @@ -30,12 +30,12 @@ TDengine's JDBC driver implementation is as consistent as possible with the rela ## Supported platforms -Native connectivity supports the same platform as TDengine client-driven support. -REST connectivity supports all platforms that can run Java. +Native connection supports the same platform as TDengine client-driven support. +REST connection supports all platforms that can run Java. ## Version support -Please refer to [Version Support List] (/reference/connector# version support) +Please refer to [Version Support List](/reference/connector# version support). ## TDengine DataType vs. Java DataType @@ -64,7 +64,7 @@ TDengine currently supports timestamp, number, character, Boolean type, and the Before using Java Connector to connect to the database, the following conditions are required. - Java 1.8 or above runtime environment and Maven 3.6 or above installed -- TDengine client driver installed (required for native connections, not required for REST connections), please refer to [Installing Client Driver](/reference/connector#Install Client Driver) +- TDengine client driver installed (required for native connections, not required for REST connections), please refer to [Installing Client Driver](/reference/connector#Install-Client-Driver) ### Install the connectors @@ -75,7 +75,7 @@ Before using Java Connector to connect to the database, the following conditions - [mvnrepository](https://mvnrepository.com/artifact/com.taosdata.jdbc/taos-jdbcdriver) - [maven.aliyun](https://maven.aliyun.com/mvn/search) -Add following dependency in the pom.xml file of your Maven project: +Add following dependency in the `pom.xml` file of your Maven project: ```xml-dtd @@ -109,7 +109,7 @@ TDengine's JDBC URL specification format is: For establishing connections, native connections differ slightly from REST connections. - + ```java Class.forName("com.taosdata.jdbc.TSDBDriver"); @@ -117,9 +117,9 @@ String jdbcUrl = "jdbc:TAOS://taosdemo.com:6030/test?user=root&password=taosdata Connection conn = DriverManager.getConnection(jdbcUrl); ``` -In the above example, TSDBDriver, which uses a JDBC native connection, establishes a connection to a hostname of taosdemo.com, port 6030 (the default port for TDengine), and a database named test. In this URL, the user name (user) is specified as root, and the password (password) is taosdata. +In the above example, TSDBDriver, which uses a JDBC native connection, establishes a connection to a hostname `taosdemo.com`, port `6030` (the default port for TDengine), and a database named `test`. In this URL, the user name `user` is specified as `root`, and the `password` is `taosdata`. -Note: With JDBC native connections, taos-jdbcdriver relies on the client driver (libtaos.so under Linux; taos .dll under Windows). +Note: With JDBC native connections, taos-jdbcdriver relies on the client driver (`libtaos.so` on Linux; `taos.dll` on Windows). The configuration parameters in the URL are as follows: @@ -129,14 +129,14 @@ The configuration parameters in the URL are as follows: - charset: The character set used by the client, the default value is the system character set. - locale: Client locale, by default, use the system's current locale. - timezone: The time zone used by the client, the default value is the system's current time zone. -- batchfetch: true: pulls result sets in batches when executing queries; false: pulls result sets row by row. The default value is: false. Enabling batch pull and obtaining a batch of data can improve query performance when the query data volume is large. +- batchfetch: true: pulls result sets in batches when executing queries; false: pulls result sets row by row. The default value is: false. Enabling batch pulling and obtaining a batch of data can improve query performance when the query data volume is large. - batchErrorIgnore:true: When executing statement executeBatch, if there is a SQL execution failure in the middle, the following SQL will continue to be executed. false: No more statements after the failed SQL are executed. The default value is: false. -For more information about JDBC native connections, see [Video Tutorial] (https://www.taosdata.com/blog/2020/11/11/1955.html). +For more information about JDBC native connections, see [Video Tutorial](https://www.taosdata.com/blog/2020/11/11/1955.html). **Connect using the TDengine client-driven configuration file ** -When you use a JDBC native connection to connect to a TDengine cluster, you can use the TDengine client-driven configuration file to specify parameters such as firstEp and secondEp of the cluster in the configuration file as below: +When you use a JDBC native connection to connect to a TDengine cluster, you can use the TDengine client driver configuration file to specify parameters such as `firstEp` and `secondEp` of the cluster in the configuration file as below: 1. Do not specify hostname and port in Java applications. @@ -169,14 +169,14 @@ secondEp cluster_node2:6030 # locale en_US.UTF-8 ``` -In the above example, JDBC uses the client's configuration file to establish a connection to a hostname of cluster_node1, port 6030, and a database named test. When the firstEp node in the cluster fails, JDBC attempts to connect to the cluster using secondEp. +In the above example, JDBC uses the client's configuration file to establish a connection to a hostname `cluster_node1`, port 6030, and a database named `test`. When the firstEp node in the cluster fails, JDBC attempts to connect to the cluster using secondEp. In TDengine, as long as one node in firstEp and secondEp is valid, the connection to the cluster can be established normally. -> **Note**: The configuration file here refers to the configuration file on the machine where the application that calls the JDBC Connector is located, the default value of /etc/taos/taos .cfg on Linux OS, and the default value of C://TDengine/cfg/taos.cfg on Windows OS. +> **Note**: The configuration file here refers to the configuration file on the machine where the application that calls the JDBC Connector is located, the default path is `/etc/taos/taos.cfg` on Linux, and the default path is `C://TDengine/cfg/taos.cfg` on Windows. - + ```java Class.forName("com.taosdata.jdbc.rs.RestfulDriver"); @@ -184,12 +184,12 @@ String jdbcUrl = "jdbc:TAOS-RS://taosdemo.com:6041/test?user=root&password=taosd Connection conn = DriverManager.getConnection(jdbcUrl); ``` -In the above example, a RestfulDriver with a JDBC REST connection is used to establish a connection to a database named test with hostname taosdemo.com on port 6041. The URL specifies the user name (user) as root and the password (password) as taosdata. +In the above example, a RestfulDriver with a JDBC REST connection is used to establish a connection to a database named `test` with hostname `taosdemo.com` on port `6041`. The URL specifies the user name as `root` and the password as `taosdata`. There is no dependency on the client driver when Using a JDBC REST connection. Compared to a JDBC native connection, only the following are required: 1. 1. driverClass specified as "com.taosdata.jdbc.rs.RestfulDriver". -2. jdbcUrl starting with "jdbc:TAOS-RS://". 3. +2. jdbcUrl starting with "jdbc:TAOS-RS://". 3. use 6041 as the connection port. The configuration parameters in the URL are as follows. @@ -209,7 +209,7 @@ The configuration parameters in the URL are as follows. INSERT INTO test.t1 USING test.weather (ts, temperature) TAGS('beijing') VALUES(now, 24.6); ``` -- Starting from taos-jdbcdriver-2.0.36 and TDengine 2.2.0.0, if dbname is specified in the url, JDBC REST connections will use /rest/sql/dbname as the url for restful requests by default, and there is no need to specify dbname in SQL. For example, if the url is jdbc:TAOS-RS://127.0.0.1:6041/test, then the sql can be executed: insert into t1 using weather(ts, temperature) tags('beijing') values(now, 24.6); +- Starting from taos-jdbcdriver-2.0.36 and TDengine 2.2.0.0, if dbname is specified in the URL, JDBC REST connections will use `/rest/sql/dbname` as the URL for REST requests by default, and there is no need to specify dbname in SQL. For example, if the URL is `jdbc:TAOS-RS://127.0.0.1:6041/test`, then the SQL can be executed: insert into t1 using weather(ts, temperature) tags('beijing') values(now, 24.6); ::: @@ -249,7 +249,7 @@ public Connection getRestConn() throws Exception{ } ``` -In the above example, a connection is established to taosdemo.com with hostname taosdemo.com, port 6030/6041, and database named test. The connection specifies the user name (user) as root and the password (password) as taosdata in the URL and specifies the character set, language environment, time zone, and whether to enable bulk fetching in the connProps. +In the above example, a connection is established to `taosdemo.com`, port is 6030/6041, and database named `test`. The connection specifies the user name as `root` and the password as `taosdata` in the URL and specifies the character set, language environment, time zone, and whether to enable bulk fetching in the connProps. The configuration parameters in properties are as follows. @@ -265,7 +265,7 @@ For JDBC native connections, you can specify other parameters, such as log level ### Priority of configuration parameters -If the configuration parameters are duplicated in the URL, Properties, or client configuration file, the `priority` of the parameters, from highest to lowest, are as follows. +If the configuration parameters are duplicated in the URL, Properties, or client configuration file, the `priority` of the parameters, from highest to lowest, are as follows: 1. JDBC URL parameters, as described above, can be specified in the parameters of the JDBC URL. 2. Properties connProps @@ -350,16 +350,16 @@ There are three types of error codes that the JDBC connector can report: For specific error codes, please refer to. -- [TDengine Java Connector](https://github.com/taosdata/TDengine/blob/develop/src/connector/jdbc/src/main/java/com/taosdata/jdbc/ TSDBErrorNumbers.java) +- [TDengine Java Connector](https://github.com/taosdata/TDengine/blob/develop/src/connector/jdbc/src/main/java/com/taosdata/jdbc/TSDBErrorNumbers.java) - [TDengine_ERROR_CODE](https://github.com/taosdata/TDengine/blob/develop/src/inc/taoserror.h) ### Writing data via parameter binding -TDengine's native JDBC connection implementation has significantly improved its support for data writing (INSERT) scenarios via parameter binding with version 2.1.2.0 and later versions. Writing data in this way avoids the resource consumption of SQL syntax parsing, resulting in significant write performance improvements in many cases. +TDengine's native JDBC connection implementation has significantly improved its support for data writing (INSERT) scenarios via bind interface with version 2.1.2.0 and later versions. Writing data in this way avoids the resource consumption of SQL syntax parsing, resulting in significant write performance improvements in many cases. **Note**. -- JDBC REST connections do not currently support parameter binding +- JDBC REST connections do not currently support bind interface - The following sample code is based on taos-jdbcdriver-2.0.36 - The setString method should be called for binary type data, and the setNString method should be called for nchar type data - both setString and setNString require the user to declare the width of the corresponding column in the size parameter of the table definition @@ -669,13 +669,13 @@ The TDengine Java Connector supports subscription functionality with the followi TSDBSubscribe sub = ((TSDBConnection)conn).subscribe("topic", "select * from meters", false); ``` -The three parameters of the `subscribe` method have the following meanings. +The three parameters of the `subscribe()` method have the following meanings. - topic: the subscribed topic (i.e., name). This parameter is the unique identifier of the subscription - sql: the query statement of the subscription, this statement can only be `select` statement, only the original data should be queried, and you can query only the data in the positive time order - restart: if the subscription already exists, whether to restart or continue the previous subscription -The above example will use the SQL statement `select * from meters` to create a subscription named `topic`. If the subscription exists, it will continue the progress of the previous query instead of consuming all the data from the beginning. +The above example will use the SQL command `select * from meters` to create a subscription named `topic`. If the subscription exists, it will continue the progress of the previous query instead of consuming all the data from the beginning. #### Subscribe to consume data @@ -693,7 +693,7 @@ while(true) { } ``` -The `consume` method returns a result set containing all new data from the last `consume`. Be sure to choose a reasonable frequency for calling `consume` as needed (e.g. `Thread.sleep(1000)` in the example). Otherwise, it will cause unnecessary stress on the server-side. +The `consume()` method returns a result set containing all new data from the last `consume()`. Be sure to choose a reasonable frequency for calling `consume()` as needed (e.g. `Thread.sleep(1000)` in the example). Otherwise, it will cause unnecessary stress on the server-side. #### Close subscriptions @@ -701,7 +701,7 @@ The `consume` method returns a result set containing all new data from the last sub.close(true); ``` -The ``close`` method closes a subscription. If its argument is ``true`'' it means that the subscription progress information is retained, and the subscription with the same name can be created to continue consuming data; if it is ``false`'' it does not retain the subscription progress. +The `close()` method closes a subscription. If its argument is `true` it means that the subscription progress information is retained, and the subscription with the same name can be created to continue consuming data; if it is `false` it does not retain the subscription progress. ### Closing resources @@ -711,9 +711,9 @@ stmt.close(); conn.close(); ``` -> ``Be sure to close the connection``, otherwise, there will be a connection leak. +> **Be sure to close the connection**, otherwise, there will be a connection leak. -### Use with connection pools +### Use with connection pool #### HikariCP @@ -806,7 +806,7 @@ The source code of the sample application is under `TDengine/examples/JDBC`: Please refer to: [JDBC example](https://github.com/taosdata/TDengine/tree/develop/examples/JDBC) -## Important update logs +## Recent update logs | taos-jdbcdriver version | major changes | | :------------------: | :----------------------------: | @@ -816,17 +816,17 @@ Please refer to: [JDBC example](https://github.com/taosdata/TDengine/tree/develo ## Frequently Asked Questions -1. Why is there no performance improvement when using Statement's `addBatch` and `executeBatch` to perform `batch writes/reviews`? +1. Why is there no performance improvement when using Statement's `addBatch()` and `executeBatch()` to perform `batch data writing/update`? - **Cause**: In TDengine's JDBC implementation, SQL statements submitted by `addBatch` method are executed sequentially in the order they are added, which does not reduce the number of interactions with the server and does not bring performance improvement. + **Cause**: In TDengine's JDBC implementation, SQL statements submitted by `addBatch()` method are executed sequentially in the order they are added, which does not reduce the number of interactions with the server and does not bring performance improvement. **Solution**: 1. splice multiple values in a single insert statement; 2. use multi-threaded concurrent insertion; 3. use parameter-bound writing 2. java.lang.UnsatisfiedLinkError: no taos in java.library.path - **Cause**: The program did not find the dependent native library taos. + **Cause**: The program did not find the dependent native library `taos`. - **Solution**: Under Windows you can copy C:\TDengine\driver\taos.dll to the C:\Windows\System32\ directory, under Linux the following softlink will be created `ln -s /usr/local/taos/driver/libtaos.so.x.x. x.x /usr/lib/libtaos.so` will work. + **Solution**: On Windows you can copy `C:\TDengine\driver\taos.dll` to the `C:\Windows\System32` directory, on Linux the following soft link will be created `ln -s /usr/local/taos/driver/libtaos.so.x.x.x.x /usr/lib/libtaos.so` will work. 3. java.lang.UnsatisfiedLinkError: taos.dll Can't load AMD 64 bit on an IA 32-bit platform diff --git a/docs-en/14-reference/03-connector/node.mdx b/docs-en/14-reference/03-connector/node.mdx index 039beefe32..0760784f18 100644 --- a/docs-en/14-reference/03-connector/node.mdx +++ b/docs-en/14-reference/03-connector/node.mdx @@ -16,9 +16,9 @@ import NodeOpenTSDBJson from "../../04-develop/03-insert-data/_js_opts_json.mdx" import NodeQuery from "../../04-develop/04-query-data/_js.mdx"; import NodeAsyncQuery from "../../04-develop/04-query-data/_js_async.mdx"; -`td2.0-connector` and `td2.0-rest-connector` are the official Node.js language connectors for TDengine, through which Node.js developers can develop applications that can access TDengine cluster data. +`td2.0-connector` and `td2.0-rest-connector` are the official Node.js language connectors for TDengine. Node.js developers can develop applications to access TDengine instance data. -`td2.0-connector` is a **native connector** that connects to TDengine runtime instances via the TDengine client driver (taosc) and supports data writing, querying, subscriptions, schemaless interface, and parameter binding interface. The `td2.0-rest-connector` is a **REST connector** that connects to TDengine runtime instances via the REST interface provided by taosAdapter. The REST connector can run on any platform, but performance is slightly degraded, and the interface implements a somewhat different set of functional features than the native interface. +`td2.0-connector` is a **native connector** that connects to TDengine instances via the TDengine client driver (taosc) and supports data writing, querying, subscriptions, schemaless writing, and bind interface. The `td2.0-rest-connector` is a **REST connector** that connects to TDengine instances via the REST interface provided by taosAdapter. The REST connector can run on any platform, but performance is slightly degraded, and the interface implements a somewhat different set of functional features than the native interface. The Node.js connector source code is hosted on [GitHub](https://github.com/taosdata/taos-connector-node). @@ -53,7 +53,7 @@ Please refer to [version support list](/reference/connector#version support) ### Pre-installation - Install the Node.js development environment -- If you are using the REST connector, skip this step. However, if you use the native connector, please install the TDengine client driver. Please refer to [install client driver](/reference/connector#install-client-driver) for more details. We use [node-gyp](https://github.com/nodejs/node-gyp) to interact with TDengine instances and also need to install some dependencies mentioned below depending on the specific OS. +- If you are using the REST connector, skip this step. However, if you use the native connector, please install the TDengine client driver. Please refer to [Install Client Driver](/reference/connector#Install-Client-Driver) for more details. We use [node-gyp](https://github.com/nodejs/node-gyp) to interact with TDengine instances and also need to install some dependencies mentioned below depending on the specific OS. @@ -68,17 +68,17 @@ Please refer to [version support list](/reference/connector#version support) - Installation method 1 -Use Microsoft's [ windows-build-tools ](https://github.com/felixrieseberg/windows-build-tools) to execute `npm install --global --production` from the `cmd` command-line interface to install all the necessary tools. +Use Microsoft's [windows-build-tools](https://github.com/felixrieseberg/windows-build-tools) to execute `npm install --global --production` from the `cmd` command-line interface to install all the necessary tools. - Installation method 2 Manually install the following tools. -- Install Visual Studio related: [Visual Studio Build Tools](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools) or [ Visual Studio 2017 Community](https://visualstudio.microsoft.com/pl/thank-you-downloading-visual-studio/?sku=Community) +- Install Visual Studio related: [Visual Studio Build Tools](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools) or [Visual Studio 2017 Community](https://visualstudio.microsoft.com/pl/thank-you-downloading-visual-studio/?sku=Community) - Install [Python](https://www.python.org/downloads/) 2.7 (`v3.x.x` is not supported) and execute `npm config set python python2.7`. - Go to the `cmd` command-line interface, `npm config set msvs_version 2017` -Refer to Microsoft's Node.js User Manual [ Microsoft's Node.js Guidelines for Windows ](https://github.com/Microsoft/nodejs-guidelines/blob/master/windows- environment. md#compiling-native-addon-modules). +Refer to Microsoft's Node.js User Manual [Microsoft's Node.js Guidelines for Windows](https://github.com/Microsoft/nodejs-guidelines/blob/master/windows- environment. md#compiling-native-addon-modules). If using ARM64 Node.js on Windows 10 ARM, you must add "Visual C++ compilers and libraries for ARM64" and "Visual C++ ATL for ARM64". @@ -106,11 +106,11 @@ npm i td2.0-rest-connector ### Installation verification -After installing the TDengine client, use the nodejsChecker.js program to verify that the current environment supports Node.js access to TDengine. +After installing the TDengine client, use the `nodejsChecker.js` program to verify that the current environment supports Node.js access to TDengine. -Validation method. +Verification in details: -- Create a new installation verification directory, e.g. `~/tdengine-test`, and download the [nodejsChecker.js source code](https://github.com/taosdata/TDengine/tree/develop/examples/nodejs/) from GitHub. nodejsChecker.js) to local. +- Create a new installation verification directory, e.g. `~/tdengine-test`, and download the [nodejsChecker.js source code](https://github.com/taosdata/TDengine/tree/develop/examples/nodejs/) from GitHub. to the work directory. - Execute the following command from the command-line. @@ -120,7 +120,7 @@ npm install td2.0-connector node nodejsChecker.js host=localhost ``` -- After executing the above steps, the command-line will output the result of nodejsChecker.js connecting to the TDengine instance and performing a simple insert and query. +- After executing the above steps, the command-line will output the result of `nodejsChecker.js` connecting to the TDengine instance and performing a simple insert and query. ## Establishing a connection @@ -148,7 +148,7 @@ conn.close(); ``` - + Install and refer to `td2.0-rest-connector`package: @@ -220,7 +220,7 @@ Node.js Connector >= v2.0.6 currently supports node versions >=v12.8.0 <= v12.9. ## Other notes -See [video tutorial](https://www.taosdata.com/blog/2020/11/11/1957.html) for the Node.js connector. +See [video tutorial](https://www.taosdata.com/blog/2020/11/11/1957.html) for the Node.js connector usage. ## Frequently Asked Questions @@ -230,13 +230,9 @@ See [video tutorial](https://www.taosdata.com/blog/2020/11/11/1957.html) for the sudo systemctl start taosadapter ``` -2. Node.js version +2. "Unable to establish connection", "Unable to resolve FQDN" - Connector >v2.0.6 Currently compatible Node.js versions are: >=v10.20.0 <= v10.9.0 || >=v12.8.0 <= v12.9.1 - -3. "Unable to establish connection", "Unable to resolve FQDN" - - Usually, it is because the FQDN is not configured correctly. You can refer to [How to understand TDengine's FQDN thoroughly](https://www.taosdata.com/blog/2021/07/29/2741.html). + Usually, root cause is the FQDN is not configured correctly. You can refer to [How to understand TDengine's FQDN (In Chinese)](https://www.taosdata.com/blog/2021/07/29/2741.html). ## Important Updates diff --git a/docs-en/14-reference/03-connector/python.mdx b/docs-en/14-reference/03-connector/python.mdx index 6463314084..99a84f657b 100644 --- a/docs-en/14-reference/03-connector/python.mdx +++ b/docs-en/14-reference/03-connector/python.mdx @@ -8,10 +8,10 @@ description: "taospy is the official Python connector for TDengine. taospy provi import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; -`taospy` is the official Python connector for TDengine. `taospy` provides a rich API that makes it easy for Python applications to use TDengine. `taospy` wraps both the [native interface](/reference/connector/cpp) and [REST interface](/reference/rest-api) of TDengine, which correspond to the `taos` and `taosrest` modules of the `taospy` package, respectively. -In addition to wrapping the native and REST interfaces, `taospy` also provides a programming interface that conforms to the [Python Data Access Specification (PEP 249)](https://peps.python.org/pep-0249/). It is easy to integrate `taospy` with many third-party tools, such as [SQLAlchemy](https://www.sqlalchemy.org/) and [pandas](https://pandas.pydata.org/). +`taospy` is the official Python connector for TDengine. `taospy` provides a rich set of APIs that makes it easy for Python applications to access TDengine. `taospy` wraps both the [native interface](/reference/connector/cpp) and [REST interface](/reference/rest-api) of TDengine, which correspond to the `taos` and `taosrest` modules of the `taospy` package, respectively. +In addition to wrapping the native and REST interfaces, `taospy` also provides a set of programming interfaces that conforms to the [Python Data Access Specification (PEP 249)](https://peps.python.org/pep-0249/). It is easy to integrate `taospy` with many third-party tools, such as [SQLAlchemy](https://www.sqlalchemy.org/) and [pandas](https://pandas.pydata.org/). -The connection to the server directly using the native interface provided by the client driver is referred to hereinafter as a "native connection"; the connection to the server using the REST interface provided by taosAdapter is referred to hereinafter as a "REST connection". ". +The connection to the server directly using the native interface provided by the client driver is referred to hereinafter as a "native connection"; the connection to the server using the REST interface provided by taosAdapter is referred to hereinafter as a "REST connection". The source code for the Python connector is hosted on [GitHub](https://github.com/taosdata/taos-connector-python). @@ -22,33 +22,34 @@ The source code for the Python connector is hosted on [GitHub](https://github.co ## Version selection -We recommend using the latest version of `taospy`, regardless of the version of TDengine used. +We recommend using the latest version of `taospy`, regardless what the version of TDengine is. ## Supported features -- Native connections support all the core features of TDeingine, including connection management, SQL execution, parameter binding, subscriptions, and schemaless writing. +- Native connections support all the core features of TDeingine, including connection management, SQL execution, bind interface, subscriptions, and schemaless writing. - REST connections support features such as connection management and SQL execution. (SQL execution allows you to: manage databases, tables, and supertables, write data, query data, create continuous queries, etc.). ## Installation ### Preparation -1. Install Python. Python >= 3.6 is recommended. If Python is not available on your system, refer to the [Python BeginnersGuide](https://wiki.python.org/moin/BeginnersGuide/Download) to install it. 2. -Install [pip](https://pypi.org/project/pip/). In most cases, the Python installer comes with the pip utility. If not, please refer to [pip docuemntation](https://pip.pypa.io/en/stable/installation/) to install it. -If you use a native connection, you will also need to [install the client driver](../#install client driver). The client software contains the TDengine client dynamic link library (libtaos.so or taos.dll) and the TDengine CLI. +1. Install Python. Python >= 3.6 is recommended. If Python is not available on your system, refer to the [Python BeginnersGuide](https://wiki.python.org/moin/BeginnersGuide/Download) to install it. +2. Install [pip](https://pypi.org/project/pip/). In most cases, the Python installer comes with the pip utility. If not, please refer to [pip docuemntation](https://pip.pypa.io/en/stable/installation/) to install it. -### Install using pip +If you use a native connection, you will also need to [Install Client Driver](/reference/connector#Install-Client-Driver). The client install package includes the TDengine client dynamic link library (`libtaos.so` or `taos.dll`) and the TDengine CLI. + +### Install via pip #### Uninstalling an older version -If you have previously installed an older version of the Python Connector, please uninstall it beforehand. +If you have installed an older version of the Python Connector, please uninstall it beforehand. ``` pip3 uninstall taos taospy ``` :::note -Earlier TDengine client software includes the Python connector. If the Python connector is installed from the client software's installation directory, the corresponding Python package name is `taos`. So the above uninstall command includes `taos`, and it doesn't matter if it doesn't exist. +Earlier TDengine client software includes the Python connector. If the Python connector is installed from the client package's installation directory, the corresponding Python package name is `taos`. So the above uninstall command includes `taos`, and it doesn't matter if it doesn't exist. ::: @@ -57,13 +58,13 @@ Earlier TDengine client software includes the Python connector. If the Python co -Install the latest version of +Install the latest version of: ``` pip3 install taospy ``` -You can also specify a specific version to install. +You can also specify a specific version to install: ``` pip3 install taospy==2.3.0 @@ -84,7 +85,7 @@ pip3 install git+https://github.com/taosdata/taos-connector-python.git -For native connections, you need to verify that both the client driver and the Python connector itself are installed correctly. The client driver and Python connector have been installed properly if you can successfully import the `taos` module. In the Python Interactive Shell, you can type. +For native connection, you need to verify that both the client driver and the Python connector itself are installed correctly. The client driver and Python connector have been installed properly if you can successfully import the `taos` module. In the Python Interactive Shell, you can type. ```python import taos @@ -93,7 +94,7 @@ import taos -For REST connections, verifying that the ``taosrest`'' module can be imported successfully can be done in the Python Interactive Shell by typing. +For REST connections, verifying that the `taosrest` module can be imported successfully can be done in the Python Interactive Shell by typing. ```python import taosrest @@ -109,7 +110,6 @@ If you have multiple versions of Python on your system, you may have various `pi C:\> pip3 install taospy Looking in indexes: https://pypi.tuna.tsinghua.edu.cn/simple Requirement already satisfied: taospy in c:\users\username\appdata\local\programs\python\python310\lib\site-packages (2.3.0) -ðŸ™'ðŸ™' ::: @@ -122,13 +122,13 @@ Before establishing a connection with the connector, we recommend testing the co -Ensure that the TDengine cluster is up and that the FQDN of the machines in the cluster (the FQDN defaults to hostname if you are starting a standalone version) can be resolved locally, by testing with the ping command. +Ensure that the TDengine instance is up and that the FQDN of the machines in the cluster (the FQDN defaults to hostname if you are starting a standalone version) can be resolved locally, by testing with the `ping` command. ``` ping ``` -Then test if the cluster can be appropriately connected with TDengine CLI: ``` ping ``` +Then test if the cluster can be appropriately connected with TDengine CLI: ``` taos -h -p @@ -145,7 +145,7 @@ For REST connections and making sure the cluster is up, make sure the taosAdapte curl -u root:taosdata http://:/rest/sql -d "select server_version()" ``` -The FQDN above is the FQDN of the machine running taosAdapter, PORT is the port taosAdapter listening, default is 6041. +The FQDN above is the FQDN of the machine running taosAdapter, PORT is the port taosAdapter listening, default is `6041`. If the test is successful, it will output the server version information, e.g. ```json @@ -172,7 +172,7 @@ The following example code assumes that TDengine is installed locally and that t {{#include docs-examples/python/connect_native_reference.py}} ``` -All arguments of the ``connect`` function are optional keyword arguments. The following are the connection parameters specified. +All arguments of the `connect()` function are optional keyword arguments. The following are the connection parameters specified. - `host` : The FQDN of the node to connect to. There is no default value. If this parameter is not provided, the firstEP in the client configuration file will be connected. - `user` : The TDengine user name. The default value is `root`. @@ -182,11 +182,11 @@ All arguments of the ``connect`` function are optional keyword arguments. The fo - `timezone` : The timezone used to convert the TIMESTAMP data in the query results to python `datetime` objects. The default is the local timezone. :::warning -`config` and `timezone` are both process-level configurations. we recommend that all connections made by a process use the same parameter values. Otherwise, unpredictable errors may occur. +`config` and `timezone` are both process-level configurations. We recommend that all connections made by a process use the same parameter values. Otherwise, unpredictable errors may occur. ::: :::tip -The `connect` function returns a `taos.TaosConnection` instance. In client-side multi-threaded scenarios, we recommend that each thread request a separate connection instance rather than sharing a connection between multiple threads. +The `connect()` function returns a `taos.TaosConnection` instance. In client-side multi-threaded scenarios, we recommend that each thread request a separate connection instance rather than sharing a connection between multiple threads. ::: @@ -197,7 +197,7 @@ The `connect` function returns a `taos.TaosConnection` instance. In client-side {{#include docs-examples/python/connect_rest_examples.py:connect}} ``` -All arguments to the `connect` function are optional keyword arguments. The following are the connection parameters specified. +All arguments to the `connect()` function are optional keyword arguments. The following are the connection parameters specified. - `host`: The host to connect to. The default is localhost. - `user`: TDenigne user name. The default is `root`. @@ -205,23 +205,19 @@ All arguments to the `connect` function are optional keyword arguments. The foll - `port`: The port on which the taosAdapter REST service listens. Default is 6041. - `timeout`: HTTP request timeout in seconds. The default is `socket._GLOBAL_DEFAULT_TIMEOUT`. Usually, no configuration is needed. -:::note - -::: - ## Sample program -### Basic use +### Basic Usage -Use of the ##### TaosConnection class +##### TaosConnection class -The `TaosConnection` class contains both an implementation of the PEP249 Connection interface (e.g., the `cursor` method and the `close` method) and many extensions (e.g., the `execute`, `query`, `schemaless_insert`, and `subscribe` methods). . +The `TaosConnection` class contains both an implementation of the PEP249 Connection interface (e.g., the `cursor()` method and the `close()` method) and many extensions (e.g., the `execute()`, `query()`, `schemaless_insert()`, and `subscribe()` methods). ```python title="execute method" {{#include docs-examples/python/connection_usage_native_reference.py:insert}} @@ -232,12 +228,12 @@ The `TaosConnection` class contains both an implementation of the PEP249 Connect ``` :::tip -The queried results can only be fetched once. For example, only one of `featch_all` and `fetch_all_into_dict` can be used in the example above. Repeated fetches will result in an empty list. +The queried results can only be fetched once. For example, only one of `fetch_all()` and `fetch_all_into_dict()` can be used in the example above. Repeated fetches will result in an empty list. ::: ##### Use of TaosResult class -In the above example of using the `TaosConnection` class, we have shown two ways to get the result of a query: `featch_all` and `fetch_all_into_dict`. In addition, `TaosResult` also provides methods to iterate through the result set by rows (`rows_iter`) or by data blocks (`blocks_iter`). Using these two methods will be more efficient in scenarios where the query has a large amount of data. +In the above example of using the `TaosConnection` class, we have shown two ways to get the result of a query: `fetch_all()` and `fetch_all_into_dict()`. In addition, `TaosResult` also provides methods to iterate through the result set by rows (`rows_iter`) or by data blocks (`blocks_iter`). Using these two methods will be more efficient in scenarios where the query has a large amount of data. ```python title="blocks_iter method" {{#include docs-examples/python/result_set_examples.py}} @@ -271,7 +267,7 @@ The ``TaosRestCursor`` class is an implementation of the PEP249 Cursor interface ##### Use of the RestClient class -The `RestClient` class is a direct wrapper for the [REST API](/reference/rest-api). It contains only a ``sql()` method for executing arbitrary SQL statements and returning the result. +The `RestClient` class is a direct wrapper for the [REST API](/reference/rest-api). It contains only a `sql()` method for executing arbitrary SQL statements and returning the result. ```python title="Use of RestClient" {{#include docs-examples/python/rest_client_example.py}} diff --git a/docs-en/14-reference/03-connector/rust.mdx b/docs-en/14-reference/03-connector/rust.mdx index 13c17f5771..6989e80638 100644 --- a/docs-en/14-reference/03-connector/rust.mdx +++ b/docs-en/14-reference/03-connector/rust.mdx @@ -15,9 +15,9 @@ import RustOpenTSDBTelnet from "../../04-develop/03-insert-data/_rust_opts_telne import RustOpenTSDBJson from "../../04-develop/03-insert-data/_rust_opts_json.mdx" import RustQuery from "../../04-develop/04-query-data/_rust.mdx" -`libtaos` is the official Rust language connector for TDengine, through which Rust developers can develop applications that access the TDengine database. +`libtaos` is the official Rust language connector for TDengine. Rust developers can develop applications to access the TDengine instance data. -`libtaos` provides two ways to establish connections. One is the **Native Connection**, which connects to TDengine runtime instances via the TDengine client driver (taosc). The other is **REST connection**, which connects to TDengine runtime instances via taosAdapter's REST interface. The REST connection supports any platform, but the native connection supports all platforms on which the TDengine client can run. +`libtaos` provides two ways to establish connections. One is the **Native Connection**, which connects to TDengine instances via the TDengine client driver (taosc). The other is **REST connection**, which connects to TDengine instances via taosAdapter's REST interface. The source code for `libtaos` is hosted on [GitHub](https://github.com/taosdata/libtaos-rs). @@ -28,7 +28,7 @@ REST connections are supported on all platforms that can run Rust. ## Version support -Please refer to [version support list](/reference/connector#version support) +Please refer to [version support list](/reference/connector#version-support). The Rust Connector is still under rapid development and is not guaranteed to be backward compatible before 1.0. Recommend to use TDengine version 2.4 or higher to avoid known issues. @@ -36,7 +36,7 @@ The Rust Connector is still under rapid development and is not guaranteed to be ### Pre-installation * Install the Rust development toolchain -* If using the native connection, please install the TDengine client driver. Please refer to [install client driver](/reference/connector#install client driver) +* If using the native connection, please install the TDengine client driver. Please refer to [install client driver](/reference/connector#install-client-driver) ### Adding libtaos dependencies @@ -56,7 +56,7 @@ libtaos = "*" -Add [libtaos][libtaos] to the ``Cargo.toml`'' file and enable the ``rest`'' feature. +Add [libtaos][libtaos] to the `Cargo.toml` file and enable the `rest` feature. ```toml [dependencies] @@ -180,7 +180,7 @@ async fn demo() -> Result<(), Error> { The [Builder Pattern](https://doc.rust-lang.org/1.0.0/style/ownership/builders.html) constructor pattern is Rust's solution for handling complex data types or optional configuration types. The [libtaos] implementation uses the connection constructor [TaosCfgBuilder] as the entry point for the TDengine Rust connector. The [TaosCfgBuilder] provides optional configuration of servers, ports, databases, usernames, passwords, etc. -Using the ``default()` method, you can construct a [TaosCfg] with default parameters for subsequent connections to the database or establishing connection pools. +Using the `default()` method, you can construct a [TaosCfg] with default parameters for subsequent connections to the database or establishing connection pools. ```rust let cfg = TaosCfgBuilder::default().build()? ; @@ -206,7 +206,7 @@ let conn: Taos = cfg.connect(); ### Connection pooling -In complex applications, recommand to enable connection pooling. Connection pooling for [libtaos] is implemented using [r2d2]. +In complex applications, recommand to enable connection pool. Connection pool for [libtaos] is implemented using [r2d2]. As follows, a connection pool with default parameters can be generated. @@ -226,7 +226,7 @@ You can set the same connection pool parameters using the connection pool's cons .build(cfg); ``` -In the application code, use ``pool.get()? ` to get a connection object [Taos]. +In the application code, use `pool.get()? ` to get a connection object [Taos]. ```rust let taos = pool.get()? ; @@ -234,13 +234,13 @@ let taos = pool.get()? ; The [Taos] structure is the connection manager in [libtaos] and provides two main APIs. -1. ``exec``: Execute some non-query SQL statements, such as ``CREATE`, ``ALTER`, ``INSERT`, etc. +1. `exec`: Execute some non-query SQL statements, such as `CREATE`, `ALTER`, `INSERT`, etc. ```rust taos.exec().await? ``` -2. ``query``: Execute the query statement and return the [TaosQueryData] object. +2. `query`: Execute the query statement and return the [TaosQueryData] object. ```rust let q = taos.query("select * from log.logs").await? @@ -277,15 +277,15 @@ Note that Rust asynchronous functions and an asynchronous runtime are required. In addition, this structure is also the entry point for [Parameter Binding](#Parameter Binding Interface) and [Line Protocol Interface](#Line Protocol Interface). Please refer to the specific API descriptions for usage. -### Parameter Binding Interface +### Bind Interface -Similar to the C interface, Rust provides a parameter binding interface. First, create a parameter binding object [Stmt] for a SQL statement from the [Taos] object. +Similar to the C interface, Rust provides the bind interface's wraping. First, create a bind object [Stmt] for a SQL command from the [Taos] object. ```rust let mut stmt: Stmt = taos.stmt("insert into ? values(? ,?)") ? ; ``` -The parameter binding object provides a set of interfaces for implementing parameter binding. +The bind object provides a set of interfaces for implementing parameter binding. ##### `.set_tbname(tbname: impl ToCString)` diff --git a/documentation20/cn/08.connector/01.java/docs.md b/documentation20/cn/08.connector/01.java/docs.md index c5e0a92bd7..cc2b445af1 100644 --- a/documentation20/cn/08.connector/01.java/docs.md +++ b/documentation20/cn/08.connector/01.java/docs.md @@ -864,9 +864,9 @@ Query OK, 1 row(s) in set (0.000141s) 请参考：[JDBC example](https://github.com/taosdata/TDengine/tree/develop/examples/JDBC) ## 常见问题 -* 使用Statement的addBatch和executeBatch来执行“批量写入/更行”，为什么没有带来性能上的提升？ - **原因**：TDengine的JDBC实现中，通过addBatch方法提交的sql语句，会按照添加的顺序，依次执行，这种方式没有减少与服务端的交互次数，不会带来性能上的提升。 - **解决方法**：1. 在一条insert语句中拼接多个values值；2. 使用多线程的方式并发插入；3. 使用参数绑定的写入方式 +* 使用 Statement 的 addBatch() 和 executeBatch() 来执行“批量写入/更新”，为什么没有带来性能上的提升？ + **原因**：TDengine 的 JDBC 实现中，通过 addBatch() 方法提交的sql语句，会按照添加的顺序，依次执行，这种方式没有减少与服务端的交互次数，不会带来性能上的提升。 + **解决方法**：1. 在一条 insert 语句中拼接多个 values 值；2. 使用多线程的方式并发插入；3. 使用参数绑定的写入方式 * java.lang.UnsatisfiedLinkError: no taos in java.library.path **原因**：程序没有找到依赖的本地函数库 taos。 -- GitLab