TDengine Concepts: Client Libraries

Ensuring that applications can easily write to and read from the data historian is essential for any data platform. TDengine makes it easy to get data in and out by providing a variety of client libraries that you can use to interact with its time-series database (TSDB). When you create your applications, you can use these client libraries — including sample code that you can copy into your application — to establish a connection to your TDengine cluster and perform query and insert operations as needed.

TDengine provides a REST API and a set of native libraries for specific programming languages. These client libraries are discussed in depth in this article.

REST API

The REST API is easiest to use, requiring only network connectivity to the TDengine cluster and that the development language of the application support HTTP. With the REST API, it is not necessary to install TDengine or any TDengine libraries on the machine running your application. However, ensure that the taosAdapter component is running on your TDengine Server.

The first step to using the REST API is to obtain an authorization token. To do so, send a request to taosAdapter as follows, filling in the FQDN of the TDengine Server, the port on which taosAdapter is running (6041 by default), and valid user credentials for the TDengine cluster.

curl <server-fqdn>:<taosadapter-port>/rest/login/<username>/<password>

With the authorization token, you can begin to perform operations on your databases over the REST API. Note that you must always specify the database on which you want to perform operations (for example, <databasename>.<tablename>); the USE command is not operational in this scenario. Unlike similar APIs in other products, the TDengine REST API allows you to perform database operations by inserting SQL commands in the body of an HTTP POST request, for example:

curl -L -H "Authorization: Taosd <token>" -d "SELECT * FROM test.d100" <server-fqdn>:<taosadapter-port>/rest/sql

This request returns all records from the d100 table in the test database. In this way, the REST API is a simple and lightweight but powerful method for connecting your application to a TDengine time-series database.

For more information about the REST API, see the official documentation.

TDengine Client Libraries

In addition to the REST API, TDengine provides client libraries for C, C++, Java, Go, Rust, Python, Node.js, and C#. These libraries enable native connections in addition to HTTP interfaces (REST or WebSocket). With native connections, your application can access the full performance and complete feature set of TDengine. Note that to use a native connection, you must install the TDengine Client on the machine that runs your application.

Each client library includes appropriate packages for the programming language for which it is designed. For example, to use the Python client library, you install the taospy package, which includes the taos module for native connections and the taosrest module for RESTful connections.

After importing a module, you can use the APIs it includes to connect to and perform operations on a TDengine cluster. For example, the following code uses the Python client library to establish a native connection to a TDengine cluster and then prints the version information for the TDengine Server and the local TDengine Client:

import taos

conn: taos.TaosConnection = taos.connect(host="localhost",
                                         user="root",
                                         password="taosdata",
                                         database="test",
                                         port=6030,
                                         config="/etc/taos"
                                         timezone="Asia/Shanghai")

server_version = conn.server_info
print("server_version", server_version)
client_version = conn.client_info
print("client_version", client_version)

conn.close()

To use this code, simply replace the values with the information for your cluster.

Once you have established a connection, you can use the execute() method to run SQL statements on the cluster, for example:

conn.execute("CREATE DATABASE test")

The libraries for other programming languages operate in a similar manner. TDengine client libraries make it easy to develop applications that make use of the time-series data stored in TDengine and offer the flexibility that you need to deal with various protocols and usage scenarios. In addition, a wealth of sample code and programs are provided in our official documentation that you can use with minor modifications for your own projects.

For detailed descriptions of each client library and related code, see the official documentation.