cpp.mdx

---
sidebar_position: 1
sidebar_label: C/C++
title: C/C++ Connector
---

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 <taos.h>
```

After TDengine server or client installation, `taos.h` is located at

- Linux: `/usr/local/taos/include`
- Windows: `C:\TDengine\include`

The dynamic libraries for the TDengine client driver are located in.

- Linux: `/usr/local/taos/driver/libtaos.so`
- Windows: `C:\TDengine\taos.dll`

## Supported platforms

Please refer to [list of supported platforms](/reference/connector#supported platforms)

## 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 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

Please refer to the [Installation Guide](/reference/connector#installation steps) for TDengine client driver installation

## Establishing a connection

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.

```c
  TAOS *taos = taos_connect("localhost:6030", "root", "taosdata", NULL, 0);
  if (taos == NULL) {
    printf("failed to connect to server, reason:%s\n", "null taos" /*taos_errstr(taos)*/);
    exit(1);
  }

  /* put your code here for query and writing */

  taos_close(taos);
  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.

:::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.

:::

## Example program

This section shows sample code for standard access methods to TDengine clusters using the client driver.

### Synchronous query example

<details>
<summary>Synchronous query</summary>

```c
{{#include examples/c/demo.c}}
```

</details>

### Asynchronous query example

<details>
<summary>Asynchronous queries</summary>

```c
{{#include examples/c/asyncdemo.c}}
```

</details>

### Parameter binding example

<details>
<summary>Parameter Binding</summary>

```c
{{#include examples/c/prepare.c}}
```

</details>

### Pattern-free writing example

<details>
<summary>Mode free write</summary>

```c
{{#include examples/c/schemaless.c}}
```

</details>

### Subscription and consumption example

<details>
<summary>Subscribe and consume</summary>

```c
{{#include examples/c/subscribe.c}}
```

</details>

:::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 the x64/x86 hardware platforms.

:::

## API reference

The following describes the basic API, synchronous API, asynchronous API, subscription API, and schemaless write API of TDengine client driver, respectively.

### Basic API

The base API is used to do things like create database connections and provide a runtime environment for the execution of other APIs.

- `void taos_init()`

  Initializes the runtime environment. If the API is not actively called, the driver will automatically call the API when `taos_connect()` is called, so the program generally does not need to call it manually.

- `void taos_cleanup()`

  Clean up the runtime environment and should be called before the application exits.

- ` int taos_options(TSDB_OPTION option, const void * arg, ...) `

  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()`

  Get client version information.

- `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:

  - host: FQDN of any node in the TDengine cluster
  - user: user name
  - pass: password
  - 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

  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

  :::

- `char *taos_get_server_info(TAOS *taos)`

  Get server-side version information.

- ` int taos_select_db(TAOS *taos, const char *db)`

  Set the current default database to `db`.

- `void taos_close(TAOS *taos)`

  Closes the connection, where `taos` is the handle returned by `taos_connect()`.

### Synchronous query APIs

The APIs described in this subsection are all synchronous interfaces. After being called by the application, it blocks and waits for a response until it gets a return result or an error message.

- `TAOS_RES* taos_query(TAOS *taos, const char *sql)`

  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)`

  Returns the precision of the result set timestamp field, `0` for milliseconds, `1` for microseconds, and `2` for nanoseconds.

- `TAOS_ROW taos_fetch_row(TAOS_RES *res)`

  Fetch the data in the query result set by row.

- ` int taos_fetch_block(TAOS_RES *res, TAOS_ROW *rows)`

  Batch fetches the data in the query result set. The return value is the number of rows of the fetched data.

- `int taos_num_fields(TAOS_RES *res)` and `int taos_field_count(TAOS_RES *res)`

  These two APIs are equivalent and are used to get the number of columns in the query result set.

- `int* taos_fetch_lengths(TAOS_RES *res)`

  Gets the lengths of each field in the result set. The return value is an array whose length is the number of columns in the result set.

- `int taos_affected_rows(TAOS_RES *res)`

  Get the number of rows affected by the executed SQL statement.

- ` 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_fileds()` to parse a tuple (one row) of data returned by `taos_fetch_row()`. The structure of `TAOS_FIELD` is as follows.

```c
typedef struct taosField {
  char name[65]; // column name
  uint8_t type; // data type
  int16_t bytes; // length, in bytes
} TAOS_FIELD;
```

- `void taos_stop_query(TAOS_RES *res)`

  Stops the execution of the current query.

- ` 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. Otherwise, it 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.

- `char *taos_errstr(TAOS_RES *res)`

  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)`

  Get the reason for the last API call failure. The return value is the error code.

:::note
TDengine version 2.0 and above recommends that each thread of a database application create a separate connection or a connection pool based on threads. It is not recommended to pass the connection (TAOS\*) structure to different threads for shared use in the application. Queries, writes, etc., issued based on TAOS structures are multi-thread safe, but state quantities such as "USE statement" may interfere between threads. In addition, the C connector can dynamically create new database-oriented connections on demand (this procedure is not visible to the user), and it is recommended that `taos_close()` be called only at the final exit of the program to close the connection.

:::

### Asynchronous query API

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 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 command asynchronously.

  - taos: the database connection returned by calling `taos_connect()`
  - sql: the SQL statement to be executed
  - fp: user-defined callback function whose third parameter `code` is used to indicate whether the operation was successful or not, `0` means success, a negative number means failure (call `taos_errstr()` to get the reason for failure). When defining the callback function, the application mainly handles the second parameter `TAOS_RES *`, which is the result set returned by the query
  - param: the application provides a parameter for the callback

- `void taos_fetch_rows_a(TAOS_RES *res, void (*fp)(void *param, TAOS_RES *, int numOfRows), void *param);`

  Batch get the result set of an asynchronous query, which can only be used with `taos_query_a()`. The parameters are:

  - 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).

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 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 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.
3. call `taos_stmt_set_tbname()` to set the table name if it is reserved in the INSERT statement but not the TAGS.
4. call `taos_stmt_set_tbname_tags()` to set the table name and TAGS values if the table name and TAGS are reserved in the INSERT statement (for example, if the INSERT statement takes an automatic table build).
5. call `taos_stmt_bind_param_batch()` to set the value of VALUES in multiple columns, or call `taos_stmt_bind_param()` to set the value of VALUES in a single row.
6. call `taos_stmt_add_batch()` to add the currently bound parameters to the batch.
7. you can repeat steps 3 to 6 to add more rows of data to the batch.
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 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)

- `TAOS_STMT* taos_stmt_init(TAOS *taos)`

  Creates a TAOS_STMT object for subsequent calls.

- ` 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.

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

  Not as efficient as `taos_stmt_bind_param_batch()`, but can support non-INSERT type SQL statements.
  To bind parameters, bind points to an array (representing the row of data to be bound), making sure that the number and order of the elements in this array are the same as the parameters in the SQL statement. taos_bind is used similarly to MYSQL_BIND in MySQL, as defined below.

  ```c
  typedef struct TAOS_BIND {
    int            buffer_type;
    void *         buffer;
    uintptr_t      buffer_length;  // not in use
    uintptr_t *    length;
    int *          is_null;
    int            is_unsigned;    // not in use
    int *          error;          // not in use
  } TAOS_BIND;
  ```

- `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 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 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)`

  (new in version 2.1.1.0, only supported for replacing parameter values in INSERT statements)
  To pass the data to be bound in a multi-column manner, it is necessary to ensure that the order of the data columns and the number of columns given here are the same as the VALUES parameter in the SQL statement. The specific definition of TAOS_MULTI_BIND is as follows.

  ```c
  typedef struct TAOS_MULTI_BIND {
    int buffer_type;
    void * buffer;
    uintptr_t buffer_length;
    uintptr_t * length;
    char * is_null;
    int num; // the number of columns
  } TAOS_MULTI_BIND;
  ```

- ` 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.

- `int taos_stmt_execute(TAOS_STMT *stmt)`

  Execute the prepared statement. Currently, a statement can only be executed once.

- ` TAOS_RES* taos_stmt_use_result(TAOS_STMT *stmt)`

  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.

- `int taos_stmt_close(TAOS_STMT *stmt)`

  Finish execution and release all resources.

- ` char * taos_stmt_errstr(TAOS_STMT *stmt)`

  (new in version 2.1.3.0)
  Used to get error information if other STMT APIs return errors (return error codes or null pointers).

### 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 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)`

  **Function description**
  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.

  **return value**
  TAOS_RES structure, application can get error message by using `taos_errstr()` and also error code by using `taos_errno()`.
  In some cases, the returned TAOS_RES is `NULL`, and it is still possible to call `taos_errno()` to safely get the error code information.
  The returned TAOS_RES needs to be freed by the caller. Otherwise, a memory leak will occur.

  **Description**
  The protocol type is enumerated and contains the following three formats.

  - TSDB_SML_LINE_PROTOCOL: InfluxDB line protocol (Line Protocol)
  - TSDB_SML_TELNET_PROTOCOL: OpenTSDB Telnet Text Line Protocol
  - TSDB_SML_JSON_PROTOCOL: OpenTSDB Json protocol format

  The timestamp resolution definitions are in the taos.h file, as follows

  - TSDB_SML_TIMESTAMP_NOT_CONFIGURED = 0,
  - TSDB_SML_TIMESTAMP_HOURS,
  - TSDB_SML_TIMESTAMP_MINUTES,
  - TSDB_SML_TIMESTAMP_SECONDS,
  - TSDB_SML_TIMESTAMP_MILLI_SECONDS,
  - TSDB_SML_TIMESTAMP_MICRO_SECONDS,
  - TSDB_SML_TIMESTAMP_NANO_SECONDS

  Note that the timestamp resolution parameter only takes effect when the protocol type is `SML_LINE_PROTOCOL`.
  For OpenTSDB's text protocol, timestamp resolution follows its official resolution rules - time precision is confirmed by the number of characters contained in the timestamp.

  **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, this statement can only be `select` statement, only the original data should be queried, only the data can be queried in time order
  - fp: the callback function when the query result is received (the function prototype will be introduced later), only used when called asynchronously. This parameter should be passed `NULL` when called synchronously
  - param: additional parameter when calling the callback function, the system API will pass it to the callback function as it is, without any processing
  - interval: polling period in milliseconds. The callback function will be called periodically according to this parameter when called asynchronously. not recommended to set this parameter 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.

- ` typedef void (*TAOS_SUBSCRIBE_CALLBACK)(TAOS_SUB* tsub, TAOS_RES *res, void* param, int code)`

  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.