@@ -8,10 +8,10 @@ TDengine provides a rich set of APIs (application development interface). To fac
## Supported platforms
Currently, TDengine's native interface connectors can support platforms such as X64/ARM64 hardware platforms and Linux/Win64 development environments. The comparison matrix is as follows.
Currently, TDengine's native interface connectors can support platforms such as x64 and ARM hardware platforms and Linux and Windows development environments. The comparison matrix is as follows.
| **Connection Management** | Support | Support | Support | N/A | Support | Support |
| **Regular Query** | Support | Support | Support | N/A | Support | Support |
| **Continous Query ** | Support | Support | Support | N/A | Support | Support |
| **Parameter Binding** | Not Supported | Not Supported | Not Supported | N/A | Not Supported | Not Supported |
| **Subscription** | Not Supported | Not Supported | Not Supported | N/A | Not Supported | Not Supported |
| **Schemaless** | Not supported | Not Supported | Not Supported | N/A | Not Supported | Not supported |
| **Bulk Pulling (based on WebSocket) **| Support | Not Supported | Not Supported | N/A | Not Supported | Not Supported |
| **Parameter Binding** | Not supported | Not supported | Not supported | N/A | Not supported | Support |
| ** TMQ ** | Not supported | Not supported | Not supported | N/A | Not supported | Support |
| **Schemaless** | Not supported | Not supported | Not supported | N/A | Not supported | Not supported |
| **Bulk Pulling (based on WebSocket) **| Support | Support | Not Supported | N/A | Not Supported | Supported |
| **DataFrame** | Not supported | Support | Not supported | N/A | Not supported | Not supported |
:::warning
...
...
@@ -85,7 +85,7 @@ The client driver needs to be installed if you use the native interface connecto
:::
### Installation steps
### Install
<Tabs defaultValue="linux" groupId="os">
<TabItem value="linux" label="Linux">
...
...
@@ -96,7 +96,7 @@ The client driver needs to be installed if you use the native interface connecto
</TabItem>
</Tabs>
### Installation Verification
### Verify
After completing the above installation and configuration and you have confirmed that the TDengine service is up and running, you can execute the TDengine CLI tool to log in.
Download the package to any directory the current user has read/write permission. Then execute `tar -xzvf TDengine-client-VERSION.tar.gz` command.
The VERSION should be the version of the package you just downloaded.
3. Execute the install script
Once the package is unzipped, you will see the following files in the directory:
...
...
@@ -18,17 +17,14 @@ import PkgList from "/components/PkgList";
- _ taos.tar.gz_: client driver package
- _ driver_: TDengine client driver
- _examples_: some example programs of different programming languages (C/C#/go/JDBC/MATLAB/python/R)
You can run `install_client.sh` to install it.
4. Edit taos.cfg
4. configure taos.cfg
Edit `taos.cfg` file (full path is `/etc/taos/taos.cfg` by default), modify `firstEP` with actual TDengine server's End Point, for example `h1.tdengine.com:6030`
:::tip
1. If the computer does not run the TDengine service but installs the TDengine client driver, then you need to config `firstEP` in `taos.cfg` only, and there is no need to configure `FQDN`;
2. If you encounter the "Unable to resolve FQDN" error, please make sure the FQDN in the `/etc/hosts` file of the current computer is correctly configured, or the DNS service is correctly configured.
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
Welcome to the TDengine shell from Windows, Client Version:3.0.0.0
Copyright (c) 2022 by TAOS Data, Inc. All rights reserved.
@@ -12,8 +12,8 @@ C/C++ developers can use TDengine's client driver and the C/C++ connector, to de
After TDengine server or client installation, `taos.h` is located at
- Linux: `/usr/local/taos/include`
- Windows: `C:\TDengine\include`
- Linux：`/usr/local/taos/include`
- Windows：`C:\TDengine\include`
The dynamic libraries for the TDengine client driver are located in.
...
...
@@ -28,7 +28,7 @@ Please refer to [list of supported platforms](/reference/connector#supported-pla
The version number of the TDengine client driver and the version number of the TDengine server should be same. 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). For e.g. if the client version is x.y.z.1 and the server version is x.y.z.2 the client and server are compatible. But in general we do not recommend using a lower client version with a newer server version. It is also strongly discouraged to use a higher version of the client driver to access a lower version of the TDengine server.
## Installation steps
## Installation Steps
Please refer to the [Installation Steps](/reference/connector#installation-steps) for TDengine client driver installation
...
...
@@ -45,7 +45,7 @@ The following is sample code for establishing a connection, which omits the quer
exit(1);
}
/* put your code here for query and writing */
/* put your code here for read and write */
taos_close(taos);
taos_cleanup();
...
...
@@ -60,7 +60,7 @@ In the above example code, `taos_connect()` establishes a connection to port 603
:::
## Example program
## Sample program
This section shows sample code for standard access methods to TDengine clusters using the client driver.
...
...
@@ -125,7 +125,7 @@ You can find it in the installation directory under the `examples/c` path. This
:::
## API reference
## API Reference
The following describes the basic API, synchronous API, asynchronous API, subscription API, and schemaless write API of TDengine client driver, respectively.
...
...
@@ -141,10 +141,9 @@ The base API is used to do things like create database connections and provide a
Cleans up the runtime environment and should be called before the application exits.
Set client options, currently supports region setting (`TSDB_OPTION_LOCALE`), character set
(`TSDB_OPTION_CHARSET`), time zone (`TSDB_OPTION_TIMEZONE`), configuration file path (`TSDB_OPTION_CONFIGDIR`). The region setting, character set, and time zone default to the current settings of the operating system.
Set client options, currently supports region setting (`TSDB_OPTION_LOCALE`), character set (`TSDB_OPTION_CHARSET`), time zone (`TSDB_OPTION_TIMEZONE`), configuration file path (`TSDB_OPTION_CONFIGDIR`). The region setting, character set, and time zone default to the current settings of the operating system.
- `char *taos_get_client_info()`
...
...
@@ -171,7 +170,7 @@ The base API is used to do things like create database connections and provide a
@@ -211,7 +210,7 @@ The APIs described in this subsection are all synchronous interfaces. After bein
Get the number of rows affected by the executed SQL statement.
- `TAOS_FIELD *taos_fetch_fields(TAOS_RES *res)`
- `TAOS_FIELD *taos_fetch_fields(TAOS_RES *res)`
Gets the properties of each column of the query result set (column name, column data type, column length), used in conjunction with `taos_num_fields()` to parse a tuple (one row) of data returned by `taos_fetch_row()`. The structure of `TAOS_FIELD` is as follows.
...
...
@@ -227,7 +226,7 @@ typedef struct taosField {
Stops the execution of the current query.
- `void taos_free_result(TAOS_RES *res)`
- `void taos_free_result(TAOS_RES *res)`
Frees the query result set and the associated resources. Be sure to call this API to free the resources after the query is completed. Failing to call this, may lead to a memory leak in the application. However, note that the application will crash if you call a function like `taos_consume()` to get the query results after freeing the resources.
...
...
@@ -235,7 +234,7 @@ typedef struct taosField {
Get the reason for the failure of the last API call. The return value is an error message identified by a string.
- 'int taos_errno(TAOS_RES *res)`
- `int taos_errno(TAOS_RES *res)`
Get the reason for the last API call failure. The return value is the error code.
...
...
@@ -294,7 +293,7 @@ The specific functions related to the interface are as follows (see also the [pr
Creates a TAOS_STMT object for subsequent calls.
- `int taos_stmt_prepare(TAOS_STMT *stmt, const char *sql, unsigned long length)`
- `int taos_stmt_prepare(TAOS_STMT *stmt, const char *sql, unsigned long length)`
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.
...
...
@@ -341,7 +340,7 @@ The specific functions related to the interface are as follows (see also the [pr
} TAOS_MULTI_BIND;
```
- `int taos_stmt_add_batch(TAOS_STMT *stmt)`
- `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 command such as SELECT will return an error.
...
...
@@ -349,7 +348,7 @@ The specific functions related to the interface are as follows (see also the [pr
Execute the prepared statement. Currently, a statement can only be executed once.
Gets the result set of a statement. Use the result set in the same way as in the non-parametric call. When finished, `taos_free_result()` should be called on this result set to free resources.
...
...
@@ -357,7 +356,7 @@ The specific functions related to the interface are as follows (see also the [pr
Finish execution and release all resources.
- `char * taos_stmt_errstr(TAOS_STMT *stmt)`
- `char * taos_stmt_errstr(TAOS_STMT *stmt)`
(Available in 2.1.3.0 and later versions)
Used to get error information if other STMT APIs return errors (return error codes or null pointers).
...
...
@@ -405,46 +404,3 @@ In addition to writing data using the SQL method or the parameter binding API, w
**Supported Versions**
This feature interface is supported from version 2.3.0.0.
### Subscription and Consumption API
The Subscription API currently supports subscribing to one or more tables and continuously fetching the latest data written to them by polling periodically.
- `TAOS_SUB *taos_subscribe(TAOS* taos, int restart, const char* topic, const char *sql, TAOS_SUBSCRIBE_CALLBACK fp, void *param, int interval)`
This function is responsible for starting the subscription service, returning the subscription object on success and `NULL` on failure, with the following parameters.
- taos: the database connection that has been established.
- restart: if the subscription already exists, whether to restart or continue the previous subscription.
- topic: the topic of the subscription (i.e., the name). This parameter is the unique identifier of the subscription.
- sql: the query statement of the subscription which can only be a _select_ statement. Only the original data should be queried, and data can only be queried in temporal order.
- fp: the callback function when the query result is received only used when called asynchronously. This parameter should be passed `NULL` when called synchronously. The function prototype is described below.
- param: additional parameter when calling the callback function. The system API will pass it to the callback function as is, without any processing.
- interval: polling period in milliseconds. The callback function will be called periodically according to this parameter when called asynchronously. The interval should not be too small to avoid impact on system performance when called synchronously. If the interval between two calls to `taos_consume()` is less than this period, the API will block until the interval exceeds this period.
The prototype of the callback function in asynchronous mode with the following parameters
- tsub: subscription object
- res: query result set, note that there may be no records in the result set
- param: additional parameters provided by the client program when calling `taos_subscribe()`
- code: error code
:::note
The callback function should not take too long to process, especially if the returned result set has a lot of data. Otherwise, it may lead to an abnormal state, such as client blocking. If you must perform complex calculations, we recommend handling them in a separate thread.
:::
- `TAOS_RES *taos_consume(TAOS_SUB *tsub)`
In synchronous mode, this function is used to fetch the results of a subscription. The user application places it in a loop. If the interval between two calls to `taos_consume()` is less than the polling period of the subscription, the API will block until the interval exceeds this period. If a new record arrives in the database, the API returns that latest record. Otherwise, it returns an empty result set with no records. If the return value is `NULL`, there is a system error. This API should not be called by user programs in asynchronous mode.
:::note
After calling `taos_consume()`, the user application should make sure to call `taos_fetch_row()` or `taos_fetch_block()` to process the subscription results as soon as possible. Otherwise, the server-side will keep caching the query result data waiting to be read by the client, which in extreme cases will cause the server side to run out of memory and affect the stability of the service.
:::
- `void taos_unsubscribe(TAOS_SUB *tsub, int keepProgress)`
Unsubscribe. If the parameter `keepProgress` is not 0, the API will keep the progress information of the subscription, and subsequent calls to `taos_subscribe()` will continue based on this progress; otherwise, the progress information will be deleted, and subsequent readings will have to be restarted.
import CSInsert from "../../07-develop/03-insert-data/_cs_sql.mdx"
import CSInfluxLine from "../../07-develop/03-insert-data/_cs_line.mdx"
import CSOpenTSDBTelnet from "../../07-develop/03-insert-data/_cs_opts_telnet.mdx"
...
...
@@ -16,16 +16,17 @@ import CSOpenTSDBJson from "../../07-develop/03-insert-data/_cs_opts_json.mdx"
import CSQuery from "../../07-develop/04-query-data/_cs.mdx"
import CSAsyncQuery from "../../07-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.
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 [REST API](/reference/rest-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.
The source code of `TDengine.Connector` is hosted on [GitHub](https://github.com/taosdata/taos-connector-dotnet).
Note: TDengine Connector 3.x is not compatible with TDengine 2.x. In an environment with TDengine 2.x, you must use TDengine.Connector 1.x for the C# connector.
The source code of `TDengine.Connector` is hosted on [GitHub](https://github.com/taosdata/taos-connector-dotnet/tree/3.0).
## Supported Platforms
## Supported platforms
The supported platforms are the same as those supported by the TDengine client driver.
...
...
@@ -57,29 +58,29 @@ Please refer to [version support list](/reference/connector#version-support)
You can reference the `TDengine.Connector` published in Nuget to the current project via the `dotnet` command under the path of the existing .NET project.
```
``` bash
dotnet add package TDengine.Connector
```
</TabItem>
<TabItem value="source" label="Use source code to get C# driver">
You can download TDengine's source code and directly reference the latest version of the TDengine.Connector library
You can [download the source code](https://github.com/taosdata/taos-connector-dotnet/tree/3.0) and directly reference the latest version of the TDengine.Connector library.
| [C#checker](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/C%23checker) | Using TDengine.Connector, you can test C# Driver's synchronous writes and queries |
| [TDengineTest](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/TDengineTest) | A simple example of writing and querying using TDengine.
| [insertCn](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/insertCn) | Example of writing and querying Chinese characters using TDengine.
| [jsonTag](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/jsonTag) | Example of writing and querying JSON tag type data using TDengine.
| [stmt](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/stmt) | Example of parameter binding using TDengine.
| [schemaless](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/schemaless) | Example of writing with schemaless implemented using TDengine. |schemaless
| [benchmark](https://github.com/taosdata/TDengine/tree/develop/examples/C%23/taosdemo) | A simple benchmark implemented using TDengine.
| [async query](https://github.com/taosdata/taos-connector-dotnet/blob/develop/examples/QueryAsyncSample.cs) | Example of an asynchronous query implemented using TDengine. Example of an asynchronous query
| [subscribe](https://github.com/taosdata/taos-connector-dotnet/blob/develop/examples/SubscribeSample.cs) | Example of subscribing to data using TDengine. Data example
| [CURD](https://github.com/taosdata/taos-connector-dotnet/blob/3.0/examples/Query/Query.cs) | Table creation, data insertion, and query examples with TDengine.Connector |
| [JSON Tag](https://github.com/taosdata/taos-connector-dotnet/blob/3.0/examples/JSONTag) | Writing and querying JSON tag data with TDengine Connector |
| [stmt](https://github.com/taosdata/taos-connector-dotnet/tree/3.0/examples/Stmt) | Parameter binding with TDengine Connector |
| [schemaless](https://github.com/taosdata/taos-connector-dotnet/blob/3.0/examples/schemaless) | Schemaless writes with TDengine Connector |
| [async query](https://github.com/taosdata/taos-connector-dotnet/blob/3.0/examples/AsyncQuery/QueryAsync.cs) | Asynchronous queries with TDengine Connector |
| [TMQ](https://github.com/taosdata/taos-connector-dotnet/blob/3.0/examples/TMQ/TMQ.cs) | Data subscription with TDengine Connector |
8.`goget`commandcan't get the package, or timeout to get the package
6.`goget`commandcan't get the package, or timeout to get the package
Set Go proxy `go env -w GOPROXY=https://goproxy.cn,direct`.
...
...
@@ -311,14 +300,13 @@ func main() {
:::info
This API is created successfully without checking permissions, but only when you execute a Query or Exec, and check if user/password/host/port is legal.
import NodeInsert from "../../07-develop/03-insert-data/_js_sql.mdx";
import NodeInfluxLine from "../../07-develop/03-insert-data/_js_line.mdx";
import NodeOpenTSDBTelnet from "../../07-develop/03-insert-data/_js_opts_telnet.mdx";
import NodeOpenTSDBJson from "../../07-develop/03-insert-data/_js_opts_json.mdx";
import NodeQuery from "../../07-develop/04-query-data/_js.mdx";
`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.
`@tdengine/client` and `@tdengine/rest` are the official Node.js connectors. Node.js developers can develop applications to access TDengine instance data. Note: The connectors for TDengine 3.0 are different than those for TDengine 2.x. The new connectors do not support TDengine 2.x.
`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.
`@tdengine/client` 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. `@tdengine/rest` is the **REST connection**, which 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).
The source code for the Node.js connectors is located on [GitHub](https://github.com/taosdata/taos-connector-node/tree/3.0).
## Supported Platforms
## Supported platforms
The platforms supported by the native connector are the same as those supported by the TDengine client driver.
The REST connector supports all platforms that can run Node.js.
...
...
@@ -34,22 +34,22 @@ Please refer to [version support list](/reference/connector#version-support)
### Native connectors
1. connection management
2. general query
3. continuous query
4. parameter binding
5. subscription function
1. Connection Management
2. General Query
3. Continuous Query
4. Parameter Binding
5. Subscription
6. Schemaless
### REST Connector
1. connection management
2. general queries
3. Continuous query
1. Connection Management
2. General Query
3. Continuous Query
## Installation steps
## Installation Steps
### Pre-installation
### Pre-installation preparation
- 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.
...
...
@@ -58,7 +58,7 @@ Please refer to [version support list](/reference/connector#version-support)
<TabItem value="Linux" label="Linux system installation dependencies">
- `python` (recommended for `v2.7` , `v3.x.x` currently not supported)
- `td2.0-connector` 2.0.6 supports Node.js LTS v10.9.0 or later, Node.js LTS v12.8.0 or later; 2.0.5 and earlier support Node.js LTS v10.x versions. Other versions may have package compatibility issues
- `@tdengine/client` 3.0.0 supports Node.js LTS v10.9.0 or later and Node.js LTS v12.8.0 or later. Older versions may be incompatible.
- `make`
- C compiler, [GCC](https://gcc.gnu.org) v4.8.5 or higher
...
...
@@ -90,32 +90,32 @@ If using ARM64 Node.js on Windows 10 ARM, you must add "Visual C++ compilers and
After installing the TDengine client, use the `nodejsChecker.js` program to verify that the current environment supports Node.js access to TDengine.
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. to the work directory.
- Create an installation test folder such as `~/tdengine-test`. Download the [nodejsChecker.js source code](https://github.com/taosdata/taos-connector-node/blob/3.0/nodejs/examples/nodejsChecker.js) to your local machine.
- Execute the following command from the command-line.
| [connection](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/cursorClose.js) | Example of establishing a connection. |
| [stmtBindBatch](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/stmtBindParamBatchSample.js) | Example of binding a multi-line parameter Example of inserting. |
| [stmtBind](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/stmtBindParamSample.js) | Example of a line-by-line bind parameter insertion. |
| [stmtBindSingleParamBatch](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/) stmtBindSingleParamBatchSample.js) | Example of binding parameters by column. |
| [stmtUseResult](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/stmtUseResultSample.js) | Example of a bound parameter query. |
| [json tag](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/testJsonTag.js) | Example of using Json tag. |
| [Nanosecond](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/testNanoseconds.js) | An example of using timestamps with nanosecond precision. |
| [Microsecond](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/testMicroseconds.js) | Example of using microsecond timestamp. |
| [schemless insert](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/testSchemalessInsert.js) | schemless Example of a schemless insert. |
| [subscribe](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/testSubscribe.js) | Example of using subscribe. |
| [asyncQuery](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/tset.js) | An example of using asynchronous queries. |
| [REST](https://github.com/taosdata/taos-connector-node/blob/develop/typescript-rest/example/example.ts) | An example of using TypeScript with REST connections. |
| [basicUse](https://github.com/taosdata/taos-connector-node/blob/3.0/nodejs/examples/queryExample.js) | Basic operations such as establishing connections and running SQl commands. |
| [TMQ](https://github.com/taosdata/taos-connector-node/blob/3.0/nodejs/examples/tmq.js) | Using data subscription |
| [asyncQuery](https://github.com/taosdata/taos-connector-node/blob/3.0/nodejs/examples/asyncQueryExample.js) | Using asynchronous queries |
| [REST](https://github.com/taosdata/taos-connector-node/blob/3.0/typescript-rest/example/example.ts) | Using TypeScript with the REST connector |
## Usage limitations
`@tdengine/client` 3.0.0 supports Node.js LTS v12.8.0 to 12.9.1 and 10.9.0 to 10.20.0.
## Usage restrictions
Node.js Connector >= v2.0.6 currently supports node versions >=v12.8.0 <= v12.9.1 || >=v10.20.0 <= v10.9.0; v10.x versions are supported in 2.0.5 and earlier, other versions may have package compatibility issues.
## Other notes
See [video tutorial](https://www.taosdata.com/blog/2020/11/11/1957.html) for the Node.js connector usage.
## Frequently Asked Questions
...
...
@@ -223,25 +220,33 @@ See [video tutorial](https://www.taosdata.com/blog/2020/11/11/1957.html) for the
sudo systemctl start taosadapter
```
2. "Unable to establish connection", "Unable to resolve FQDN"
2. Node.js versions
`@tdengine/client` supports Node.js v10.9.0 to 10.20.0 and 12.8.0 to 12.9.1.
3. "Unable to establish connection", "Unable to resolve FQDN"
Usually, the root cause is an incorrect FQDN configuration. You can refer to this section in the [FAQ](https://docs.tdengine.com/2.4/train-faq/faq/#2-how-to-handle-unable-to-establish-connection) to troubleshoot.
| td2.0-connector | 2.0.10 | 2.4.x；2.5.x；2.6.x | Supports connection management, standard queries, connection queries, system information, and data subscription |
@@ -8,14 +8,14 @@ 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 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.
`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 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 direct connection to the server 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).
## Supported Platforms
## Supported platforms
- The [supported platforms](/reference/connector/#supported-platforms) for the native connection are the same as the ones supported by the TDengine client.
- REST connections are supported on all platforms that can run Python.
...
...
@@ -35,7 +35,6 @@ We recommend using the latest version of `taospy`, regardless of the version of
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 documentation](https://pip.pypa.io/en/stable/installation/) to install it.
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.
- `cursor.execute`: Used to execute arbitrary SQL statements.
- `cursor.execute`: Used to execute arbitrary SQL statements.
- `cursor.rowcount` : For write operations, returns the number of successful rows written. For query operations, returns the number of rows in the result set.
- `cursor.description` : Returns the description of the field. Please refer to [TaosRestCursor](https://docs.taosdata.com/api/taospy/taosrest/cursor.html) for the specific format of the description information.
...
...
@@ -274,6 +274,8 @@ The `RestClient` class is a direct wrapper for the [REST API](/reference/rest-ap
For a more detailed description of the `sql()` method, please refer to [RestClient](https://docs.taosdata.com/api/taospy/taosrest/restclient.html).
</TabItem>
</Tabs>
...
...
@@ -304,8 +306,7 @@ For a more detailed description of the `sql()` method, please refer to [RestClie
Rust connector 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 **Websocket connection**, which connects to TDengine instances via taosAdapter service.
`taos` is the official Rust connector for TDengine. Rust developers can develop applications to access the TDengine instance data.
The source code is hosted on [taosdata/taos-connector-rust](https://github.com/taosdata/taos-connector-rust).
`taos` 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 the **WebSocket connection**, which connects to TDengine instances via the WebSocket interface provided by taosAdapter. You can specify a connection type with Cargo features. By default, both types are supported. The Websocket connection can be used on any platform. The native connection can be used on any platform that the TDengine Client supports.
The source code for the Rust connectors is located on [GitHub](https://github.com/taosdata/taos-connector-rust).
## Supported platforms
The platforms supported by native connections are the same as those supported by the TDengine client driver.
REST connections are supported on all platforms that can run Rust.
Native connections are supported on the same platforms as the TDengine client driver.
Websocket connections are supported on all platforms that can run Go.
## 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. We recommend using TDengine version 3.0 or higher to avoid known issues.
## Installation
### Pre-installation
### Pre-installation preparation
* 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)
### Add dependencies
# Add taos dependency
Add the dependency to the [Rust](https://rust-lang.org) project as follows, depending on the connection method selected.
Depending on the connection method, add the [taos][taos] dependency in your Rust project as follows:
In `cargo.toml`, add [taos][taos] and enable the native feature:
```toml
[dependencies]
...
...
@@ -65,7 +68,7 @@ taos = { version = "*", default-features = false, features = ["native"] }
</TabItem>
<TabItem value="rest" label="Websocket only">
Add [taos] to the `Cargo.toml` file and enable the `ws` feature.
In `cargo.toml`, add [taos][taos] and enable the ws feature:
```toml
[dependencies]
...
...
@@ -75,15 +78,15 @@ taos = { version = "*", default-features = false, features = ["ws"] }
</TabItem>
</Tabs>
## Create a connection
## Establishing a connection
In rust connector, we use a DSN connection string as a connection builder. For example,
[TaosBuilder] creates a connection constructor through the DSN connection description string.
```rust
let builder = TaosBuilder::from_dsn("taos://")?;
```
You can now use connection client to create the connection.
You can now use this object to create the connection.
```rust
let conn = builder.build()?;
...
...
@@ -96,9 +99,7 @@ let conn1 = builder.build()?;
let conn2 = builder.build()?;
```
DSN is short for **D**ata **S**ource **N**ame string - [a data structure used to describe a connection to a data source](https://en.wikipedia.org/wiki/Data_source_name).
A common DSN is basically constructed as this:
The structure of the DSN description string is as follows:
- **Driver**: the main entrypoint to a processer. **Required**. In Rust connector, the supported driver names are listed here:
- **taos**: the legacy TDengine connection data source.
- **tmq**: subscription data source from TDengine.
- **http/ws**: use websocket protocol via `ws://` scheme.
- **https/wss**: use websocket protocol via `wss://` scheme.
- **Protocol**: the additional information appended to driver, which can be be used to support different kind of data sources. By default, leave it empty for native driver(only under feature "native"), and `ws/wss` for websocket driver (only under feature "ws"). **Optional**.
- **Username**: as its definition, is the username to the connection. **Optional**.
- **Password**: the password of the username. **Optional**.
- **Host**: address host to the datasource. **Optional**.
- **Port**: address port to the datasource. **Optional**.
- **Database**: database name or collection name in the datasource. **Optional**.
- **Params**: a key-value map for any other informations to the datasource. **Optional**.
Here is a simple DSN connection string example:
The parameters are described as follows:
- **driver**: Specify a driver name so that the connector can choose which method to use to establish the connection. Supported driver names are as follows:
- **taos**: Table names use the TDengine connector driver.
- **tmq**: Use the TMQ to subscribe to data.
- **http/ws**: Use Websocket to establish connections.
- **https/wss**: Use Websocket to establish connections, and enable SSL/TLS.
- **protocol**: Specify which connection method to use. For example, `taos+ws://localhost:6041` uses Websocket to establish connections.
- **username/password**: Username and password used to create connections.
- **host/port**: Specifies the server and port to establish a connection. If you do not specify a hostname or port, native connections default to `localhost:6030` and Websocket connections default to `localhost:6041`.
- **database**: Specify the default database to connect to.
- **params**：Optional parameters.
A sample DSN description string is as follows:
```text
taos+ws://localhost:6041/test
```
which means connect `localhost` with port `6041` via `ws` protocol, and make `test` as the default database.
This indicates that the Websocket connection method is used on port 6041 to connect to the server localhost and use the database `test` by default.
So that you can use DSN to specify connection protocol at runtime:
You can create DSNs to connect to servers in your environment.
```rust
use taos::*; // use it like a `prelude` mod, we need some traits at next.
use taos::*;
// use native protocol.
let builder = TaosBuilder::from_dsn("taos://localhost:6030")?;
...
...
@@ -140,7 +141,7 @@ let conn1 = builder.build();
let conn2 = TaosBuilder::from_dsn("taos+ws://localhost:6041")?;
```
After connected, you can perform the following operations on the database.
After the connection is established, you can perform operations on your database.
Rust connector provides two kinds of ways to fetch data:
There are two ways to query data: Using built-in types or the [serde](https://serde.rs) deserialization framework.
```rust
// Query option 1, use rows stream.
...
...
@@ -225,41 +226,41 @@ Rust connector provides two kinds of ways to fetch data:
<RustInsert />
#### Stmt bind
#### STMT Write
<RustBind />
### Query data
<RustQuery />|
<RustQuery />
## API Reference
### Connector builder
### Connector Constructor
Use DSN to directly construct a TaosBuilder object.
You create a connector constructor by using a DSN.
```rust
let builder = TaosBuilder::from_dsn("")? ;
let cfg = TaosBuilder::default().build()?;
```
Use `builder` to create many connections:
You use the builder object to create multiple connections.
```rust
let conn: Taos = cfg.build();
```
### Connection pool
### Connection pooling
In complex applications, we recommend enabling connection pools. Connection pool for [taos] is implemented using [r2d2] by enabling "r2d2" feature.
In complex applications, we recommend enabling connection pools. [taos] implements connection pools based on [r2d2].
Basically, a connection pool with default parameters can be generated as:
As follows, a connection pool with default parameters can be generated.
```rust
let pool = TaosBuilder::from_dsn(dsn)?.pool()?;
```
You can set the connection pool parameters using the `PoolBuilder`.
You can set the same connection pool parameters using the connection pool's constructor.
```rust
let dsn = "taos://localhost:6030";
...
...
@@ -273,23 +274,23 @@ let opts = PoolBuilder::new()
let pool = TaosBuilder::from_dsn(dsn)?.with_pool_builder(opts)?;
```
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()?;
let taos = pool.get()?;
```
### Connection methods
# Connectors
The [Taos] connection struct provides several APIs for convenient use.
The [Taos][struct.Taos] object provides an API to perform operations on multiple databases.
1. `exec`: Execute some non-query SQL statements, such as `CREATE`, `ALTER`, `INSERT` etc. and return affected rows (only meaningful to `INSERT`).
1. `exec`: Execute some non-query SQL statements, such as `CREATE`, `ALTER`, `INSERT`, etc.
```rust
let affected_rows = taos.exec("INSERT INTO tb1 VALUES(now, NULL)").await?;
```
2. `exec_many`: You can execute many SQL statements in order with `exec_many` method.
2. `exec_many`: Run multiple SQL statements simultaneously or in order.
```rust
taos.exec_many([
...
...
@@ -299,15 +300,15 @@ The [Taos] connection struct provides several APIs for convenient use.
]).await?;
```
3. `query`: Execute the query statement and return the [ResultSet] object.
3. `query`: Run a query statement and return a [ResultSet] object.
```rust
let mut q = taos.query("select * from log.logs").await?
let mut q = taos.query("select * from log.logs").await?;
```
The [ResultSet] object stores the query result data and basic information about the returned columns (column name, type, length).
The [ResultSet] object stores query result data and the names, types, and lengths of returned columns
Get filed information with `fields` method.
You can obtain column information by using [.fields()].
```rust
let cols = q.fields();
...
...
@@ -316,7 +317,7 @@ The [Taos] connection struct provides several APIs for convenient use.
}
```
Users could fetch data by rows.
It fetches data line by line.
```rust
let mut rows = result.rows();
...
...
@@ -332,7 +333,7 @@ The [Taos] connection struct provides several APIs for convenient use.
}
```
Or use it with [serde](https://serde.rs) deserialization.
Or use the [serde](https://serde.rs) deserialization framework.
```rust
#[derive(Debug, Deserialize)]
...
...
@@ -359,15 +360,17 @@ The [Taos] connection struct provides several APIs for convenient use.
Note that Rust asynchronous functions and an asynchronous runtime are required.
[Taos] provides a few Rust methods that encapsulate SQL to reduce the frequency of `format!` code blocks.
[Taos][struct.Taos] provides Rust methods for some SQL statements to reduce the number of `format!`s.
- `.describe(table: &str)`: Executes `DESCRIBE` and returns a Rust data structure.
- `.create_database(database: &str)`: Executes the `CREATE DATABASE` statement.
- `.use_database(database: &str)`: Executes the `USE` statement.
### Bind API
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.
### Bind Interface
Similar to the C interface, Rust provides the bind interface's wrapping. First, create a bind object [Stmt] for a SQL command with the [Taos] object.
Similar to the C interface, Rust provides the bind interface's wrapping. First, the [Taos][struct.taos] object creates a parameter binding object [Stmt] for an SQL statement.
```rust
let mut stmt = Stmt::init(&taos).await?;
...
...
@@ -387,17 +390,17 @@ stmt.set_tbname("d0")?;
#### `.set_tags(&[tag])`
Bind tag values when the SQL statement uses a super table.
Bind sub-table table names and tag values when the SQL statement uses a super table.
```rust
let mut stmt = taos.stmt("insert into ? using stb0 tags(?) values(? ,?)")?;
Bind value types. Use the [ColumnView] structure to construct the desired type and bind.
Bind value types. Use the [ColumnView] structure to create and bind the required types.
```rust
let params = vec![
...
...
@@ -421,42 +424,42 @@ let rows = stmt.bind(¶ms)?.add_batch()?.execute()?;
#### `.execute()`
Execute to insert all bind records. [Stmt] objects can be reused, re-bind, and executed after execution. Remember to call `add_batch` before `execute`.
Execute SQL. [Stmt] objects can be reused, re-binded, and executed after execution. Before execution, ensure that all data has been added to the queue with `.add_batch`.
```rust
stmt.add_batch()?.execute()?;
stmt.execute()?;
// next bind cycle.
// stmt.set_tbname()? ;
//stmt.bind()?;
//stmt.add_batch().execute()? ;
//stmt.set_tbname()?;
//stmt.bind()?;
//stmt.execute()?;
```
A runnable example for bind can be found [here](https://github.com/taosdata/taos-connector-rust/blob/main/examples/bind.rs).
For a working example, see [GitHub](https://github.com/taosdata/taos-connector-rust/blob/main/examples/bind.rs).
### Subscription API
### Subscriptions
Users can subscribe a [TOPIC](../../../taos-sql/tmq/) with TMQ(the TDengine Message Queue) API.
TDengine starts subscriptions through [TMQ](../../../taos-sql/tmq/).
Start from a TMQ builder:
You create a TMQ connector by using a DSN.
```rust
let tmq = TmqBuilder::from_dsn("taos://localhost:6030/?group.id=test")?;
```
Build a consumer:
Create a consumer:
```rust
let mut consumer = tmq.build()?;
```
Subscribe a topic:
A single consumer can subscribe to one or more topics.
```rust
consumer.subscribe(["tmq_meters"]).await?;
```
Consume messages, and commit the offset for each message.
The TMQ is of [futures::Stream](https://docs.rs/futures/latest/futures/stream/index.html) type. You can use the corresponding API to consume each message in the queue and then use `.commit` to mark them as consumed.
```rust
{
...
...
@@ -495,22 +498,21 @@ Unsubscribe:
consumer.unsubscribe().await;
```
In TMQ DSN, you must choose to subscribe with a group id. Also, there's several options could be set:
The following parameters can be configured for the TMQ DSN. Only `group.id` is mandatory.
- `group.id`: **Required**, a group id is any visible string you set.
- `client.id`: a optional client description string.
- `auto.offset.reset`: choose to subscribe from *earliest* or *latest*, default is *none* which means 'earliest'.
- `enable.auto.commit`: automatically commit with specified time interval. By default - in the recommended way _ you must use `commit` to ensure that you've consumed the messages correctly, otherwise, consumers will received repeated messages when re-subscribe.
- `auto.commit.interval.ms`: the auto commit interval in milliseconds.
- `group.id`: Within a consumer group, load balancing is implemented by consuming messages on an at-least-once basis.
- `client.id`: Subscriber client ID.
- `auto.offset.reset`: Initial point of subscription. *earliest* subscribes from the beginning, and *latest* subscribes from the newest message. The default is earliest. Note: This parameter is set per consumer group.
- `enable.auto.commit`: Automatically commits. This can be enabled when data consistency is not essential.
- `auto.commit.interval.ms`: Interval for automatic commits.
Check the whole subscription example at [GitHub](https://github.com/taosdata/taos-connector-rust/blob/main/examples/subscribe.rs).
For more information, see [GitHub sample file](https://github.com/taosdata/taos-connector-rust/blob/main/examples/subscribe.rs).
Please move to the Rust documentation hosting page for other related structure API usage instructions: <https://docs.rs/taos>.
For information about other structure APIs, see the [Rust documentation](https://docs.rs/taos).
