TDengine Node.js Client Library

@tdengine/client and @tdengine/rest are the official Node.js client libraries. Node.js developers can develop applications to access TDengine instance data. Note: The client libraries for TDengine 3.0 are different than those for TDengine 2.x. The new client libraries do not support TDengine 2.x.

@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 client library 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 source code for the Node.js client libraries is located on GitHub.

Supported platforms

The platforms supported by the native client library are the same as those supported by the TDengine client driver. The REST client library supports all platforms that can run Node.js.

Version support

Please refer to version support list

Supported features

Native connection
REST connection

Connection Management
General Query
Continuous Query
Parameter Binding
Subscription
Schemaless

Installation Steps

Pre-installation preparation

Install the Node.js development environment
If you are using the REST client library, skip this step. However, if you use the native client library, please install the TDengine client driver. Please refer to Install Client Driver for more details. We use node-gyp to interact with TDengine instances and also need to install some dependencies mentioned below depending on the specific OS.

Linux system installation dependencies
macOS installation dependencies
Windows system installation dependencies

python (recommended for v2.7 , v3.x.x currently not supported)
@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 v4.8.5 or later.

python (recommended for v2.7 , v3.x.x currently not supported)
@tdengine/client 3.0.0 currently supports Node.js from v12.22.12, but only later versions of v12. Other versions may be incompatible.
make
C compiler, GCC v4.8.5 or later.

Installation method 1

Use Microsoft's 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 or Visual Studio 2017 Community
Install Python 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.

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

Install via npm

Install native clieny library
Install REST client library

npm install @tdengine/client

npm install @tdengine/rest

Verify

Native client library
REST client library

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 an installation test folder such as ~/tdengine-test. Download the nodejsChecker.js source code to your local machine.
Execute the following command from the command-line.

npm init -y
npm install @tdengine/client
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 installing the TDengine client, use the restChecker.js program to verify that the current environment supports Node.js access to TDengine.

Verification in details:

Create an installation test folder such as ~/tdengine-test. Download the restChecker.js source code to your local.
Execute the following command from the command-line.

npm init -y
npm install @tdengine/rest
node restChecker.js

After executing the above steps, the command-line will output the result of restChecker.js connecting to the TDengine instance and performing a simple insert and query.

Establishing a connection

Please choose to use one of the client libraries.

native connection
REST connection

Install and import the @tdengine/client package.

//A cursor also needs to be initialized in order to interact with TDengine from Node.js.
const taos = require("@tdengine/client");
var conn = taos.connect({
  host: "127.0.0.1",
  user: "root",
  password: "taosdata",
  config: "/etc/taos",
  port: 0,
});
var cursor = conn.cursor(); // Initializing a new cursor

//Close a connection
conn.close();

Install and import the @tdengine/rest package.

//A cursor also needs to be initialized in order to interact with TDengine from Node.js.
import { options, connect } from "@tdengine/rest";
options.path = "/rest/sql";
// set host
options.host = "localhost";
// set other options like user/passwd

let conn = connect(options);
let cursor = conn.cursor();

Usage examples

Write data

SQL Write

native connection
REST connection

const taos = require("@tdengine/client");

const conn = taos.connect({
  host: "localhost",
});

const cursor = conn.cursor();
try {
  cursor.execute("CREATE DATABASE power");
  cursor.execute("USE power");
  cursor.execute(
    "CREATE STABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)"
  );
  var sql = `INSERT INTO power.d1001 USING power.meters TAGS('California.SanFrancisco', 2) VALUES ('2018-10-03 14:38:05.000', 10.30000, 219, 0.31000) ('2018-10-03 14:38:15.000', 12.60000, 218, 0.33000) ('2018-10-03 14:38:16.800', 12.30000, 221, 0.31000)
power.d1002 USING power.meters TAGS('California.SanFrancisco', 3) VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000)
power.d1003 USING power.meters TAGS('California.LosAngeles', 2) VALUES ('2018-10-03 14:38:05.500', 11.80000, 221, 0.28000) ('2018-10-03 14:38:16.600', 13.40000, 223, 0.29000)
power.d1004 USING power.meters TAGS('California.LosAngeles', 3) VALUES ('2018-10-03 14:38:05.000', 10.80000, 223, 0.29000) ('2018-10-03 14:38:06.500', 11.50000, 221, 0.35000)`;
  cursor.execute(sql,{'quiet':false});
} finally {
  cursor.close();
  conn.close();
}

// run with: node insert_example.js
// output:
// Successfully connected to TDengine
// Query OK, 0 row(s) affected (0.00509570s)
// Query OK, 0 row(s) affected (0.00130880s)
// Query OK, 0 row(s) affected (0.00467900s)
// Query OK, 8 row(s) affected (0.04043550s)
// Connection is closed

view source code

const { options, connect } = require("@tdengine/rest");

async function sqlInsert() {
    options.path = "/rest/sql";
    options.host = "localhost";
    options.port = 6041;
    let conn = connect(options);
    let cursor = conn.cursor();
    try {
        let res = await cursor.query('CREATE DATABASE power');
        res = await cursor.query('CREATE STABLE power.meters (ts timestamp, current float, voltage int, phase float) TAGS (location binary(64), groupId int)');
        res = await cursor.query('INSERT INTO power.d1001 USING power.meters TAGS ("California.SanFrancisco", 2) VALUES (NOW, 10.2, 219, 0.32)');
        console.log("res.getResult()", res.getResult());
    } catch (err) {
        console.log(err);
    }
}
sqlInsert();

view source code

InfluxDB line protocol write

native connection

const taos = require("@tdengine/client");

const conn = taos.connect({
  host: "localhost",
});

const cursor = conn.cursor();

function createDatabase() {
  cursor.execute("CREATE DATABASE test");
  cursor.execute("USE test");
}

function insertData() {
  const lines = [
    "meters,location=California.LosAngeles,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249",
    "meters,location=California.LosAngeles,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611250",
    "meters,location=California.LosAngeles,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249",
    "meters,location=California.LosAngeles,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611250",
  ];
  cursor.schemalessInsert(
    lines,
    taos.SCHEMALESS_PROTOCOL.TSDB_SML_LINE_PROTOCOL,
    taos.SCHEMALESS_PRECISION.TSDB_SML_TIMESTAMP_MILLI_SECONDS
  );
}

try {
  createDatabase();
  insertData();
} finally {
  cursor.close(); 
  conn.close();
}

view source code

OpenTSDB Telnet line protocol write

native connection

const taos = require("@tdengine/client");

const conn = taos.connect({
  host: "localhost",
});

const cursor = conn.cursor();

function createDatabase() {
  cursor.execute("CREATE DATABASE test");
  cursor.execute("USE test");
}

function insertData() {
  const lines = [
    "meters.current 1648432611249 10.3 location=California.SanFrancisco groupid=2",
    "meters.current 1648432611250 12.6 location=California.SanFrancisco groupid=2",
    "meters.current 1648432611249 10.8 location=California.LosAngeles groupid=3",
    "meters.current 1648432611250 11.3 location=California.LosAngeles groupid=3",
    "meters.voltage 1648432611249 219 location=California.SanFrancisco groupid=2",
    "meters.voltage 1648432611250 218 location=California.SanFrancisco groupid=2",
    "meters.voltage 1648432611249 221 location=California.LosAngeles groupid=3",
    "meters.voltage 1648432611250 217 location=California.LosAngeles groupid=3",
  ];
  cursor.schemalessInsert(
    lines,
    taos.SCHEMALESS_PROTOCOL.TSDB_SML_TELNET_PROTOCOL,
    taos.SCHEMALESS_PRECISION.TSDB_SML_TIMESTAMP_NOT_CONFIGURED
  );
}

try {
  createDatabase();
  insertData();
} finally {
  cursor.close();
  conn.close();
}

view source code

OpenTSDB JSON line protocol write

native connection

const taos = require("@tdengine/client");

const conn = taos.connect({
  host: "localhost",
});

const cursor = conn.cursor();

function createDatabase() {
  cursor.execute("CREATE DATABASE test");
  cursor.execute("USE test");
}

function insertData() {
  const lines = [
    {
      metric: "meters.current",
      timestamp: 1648432611249,
      value: 10.3,
      tags: { location: "California.SanFrancisco", groupid: 2 },
    },
    {
      metric: "meters.voltage",
      timestamp: 1648432611249,
      value: 219,
      tags: { location: "California.LosAngeles", groupid: 1 },
    },
    {
      metric: "meters.current",
      timestamp: 1648432611250,
      value: 12.6,
      tags: { location: "California.SanFrancisco", groupid: 2 },
    },
    {
      metric: "meters.voltage",
      timestamp: 1648432611250,
      value: 221,
      tags: { location: "California.LosAngeles", groupid: 1 },
    },
  ];

  cursor.schemalessInsert(
    [JSON.stringify(lines)],
    taos.SCHEMALESS_PROTOCOL.TSDB_SML_JSON_PROTOCOL,
    taos.SCHEMALESS_PRECISION.TSDB_SML_TIMESTAMP_NOT_CONFIGURED
  );
}

try {
  createDatabase();
  insertData();
} finally {
  cursor.close(); 
  conn.close();
}

view source code

Querying data

native connection
REST connection

const taos = require("@tdengine/client");

const conn = taos.connect({ host: "localhost", database: "power" });
const cursor = conn.cursor();
const query = cursor.query("SELECT ts, current FROM meters LIMIT 2");
query.execute().then(function (result) {
  result.pretty();
});

// output:
// Successfully connected to TDengine
//            ts             |         current          |
// =======================================================
// 2018-10-03 14:38:05.000   | 10.3                     |
// 2018-10-03 14:38:15.000   | 12.6                     |

view source code

const { options, connect } = require("@tdengine/rest");

async function query() {
    options.path = "/rest/sql";
    options.host = "localhost";
    options.port = 6041;
    let conn = connect(options);
    let cursor = conn.cursor();
    try {
        let res = await cursor.query('select * from power.meters');
        console.log("res.getResult()", res.getResult());
    } catch (err) {
        console.log(err);
    }
}
query();

view source code

More sample programs

| Sample Programs | Sample Program Description | | --------------------------------------------------------------------------------------------------------------------------------- --------- | -------------------------------------- | | basicUse | Basic operations such as establishing connections and running SQl commands. | | stmtBindBatch | Binding multi-line parameter insertion. | | | stmtBindSingleParamBatch | Columnar binding parameter insertion | | stmtQuery | Binding parameter query | | schemless insert | Schemaless insert | | TMQ | Using data subscription | | asyncQuery | Using asynchronous queries | | REST | Using TypeScript with the REST client library |

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.

Frequently Asked Questions

Using REST connections requires starting taosadapter.
```
sudo systemctl start taosadapter
```
Node.js versions

@tdengine/client supports Node.js v10.9.0 to 10.20.0 and 12.8.0 to 12.9.1.
"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 to troubleshoot.

Important update records

Native client library

package name	version	TDengine version	Description
@tdengine/client	3.0.0	3.0.0	Supports TDengine 3.0. Not compatible with TDengine 2.x.
td2.0-connector	2.0.12	2.4.x; 2.5.x; 2.6.x	Fixed cursor.close() bug.
td2.0-connector	2.0.11	2.4.x; 2.5.x; 2.6.x	Supports parameter binding, JSON tags and schemaless interface
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

REST client library

package name	version	TDengine version	Description
@tdengine/rest	3.0.0	3.0.0	Supports TDengine 3.0. Not compatible with TDengine 2.x.
td2.0-rest-connector	1.0.7	2.4.x; 2.5.x; 2.6.x	Removed default port 6041
td2.0-rest-connector	1.0.6	2.4.x; 2.5.x; 2.6.x	Fixed affectRows bug with create, insert, update, and alter.
td2.0-rest-connector	1.0.5	2.4.x; 2.5.x; 2.6.x	Support cloud token
td2.0-rest-connector	1.0.3	2.4.x; 2.5.x; 2.6.x	Supports connection management, standard queries, system information, error information, and continuous queries

Supported platforms​

Version support​

Supported features​

Installation Steps​

Pre-installation preparation​

Install via npm​

Verify​

Establishing a connection​

Usage examples​

Write data​

SQL Write​

InfluxDB line protocol write​

OpenTSDB Telnet line protocol write​

OpenTSDB JSON line protocol write​

Querying data​

More sample programs​

Usage limitations​

Frequently Asked Questions​

Important update records​

Native client library​

REST client library​

Support and Feedback

Supported platforms

Version support

Supported features

Installation Steps

Pre-installation preparation

Install via npm

Verify

Establishing a connection

Usage examples

Write data

SQL Write

InfluxDB line protocol write

OpenTSDB Telnet line protocol write

OpenTSDB JSON line protocol write

Querying data

More sample programs

Usage limitations

Frequently Asked Questions

Important update records

Native client library

REST client library