TDengine Node.js Connector

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

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

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.

Version support

Please refer to version support list

Supported features

Native connectors

  1. Connection Management
  2. General Query
  3. Continuous Query
  4. Parameter Binding
  5. Subscription
  6. Schemaless

REST Connector

  1. Connection Management
  2. General Query
  3. Continuous Query

Installation Steps

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

  • 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 higher

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

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 connector
  • Install REST connector
  1. npm install @tdengine/client
  1. npm install @tdengine/rest

Verify

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.

  1. npm init -y
  2. npm install @tdengine/client
  3. 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.

Establishing a connection

Please choose to use one of the connectors.

  • native connection
  • REST connection

Install and import the @tdengine/client package.

  1. //A cursor also needs to be initialized in order to interact with TDengine from Node.js.
  2. const taos = require("@tdengine/client");
  3. var conn = taos.connect({
  4.   host: "127.0.0.1",
  5.   user: "root",
  6.   password: "taosdata",
  7.   config: "/etc/taos",
  8.   port: 0,
  9. });
  10. var cursor = conn.cursor(); // Initializing a new cursor
  12. //Close a connection
  13. conn.close();

Install and import the @tdengine/rest package.

  1. //A cursor also needs to be initialized in order to interact with TDengine from Node.js.
  2. import { options, connect } from "@tdengine/rest";
  3. options.path = "/rest/sql";
  4. // set host
  5. options.host = "localhost";
  6. // set other options like user/passwd
  8. let conn = connect(options);
  9. let cursor = conn.cursor();

Usage examples

Write data

SQL Write

  1. const taos = require("@tdengine/client");
  3. const conn = taos.connect({
  4.   host: "localhost",
  5. });
  7. const cursor = conn.cursor();
  8. try {
  9.   cursor.execute("CREATE DATABASE power");
  10.   cursor.execute("USE power");
  11.   cursor.execute(
  12.     "CREATE STABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)"
  13.   );
  14.   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)
  15. power.d1002 USING power.meters TAGS('California.SanFrancisco', 3) VALUES ('2018-10-03 14:38:16.650', 10.30000, 218, 0.25000)
  16. 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)
  17. 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)`;
  18.   cursor.execute(sql,{'quiet':false});
  19. } finally {
  20.   cursor.close();
  21.   conn.close();
  22. }
  24. // run with: node insert_example.js
  25. // output:
  26. // Successfully connected to TDengine
  27. // Query OK, 0 row(s) affected (0.00509570s)
  28. // Query OK, 0 row(s) affected (0.00130880s)
  29. // Query OK, 0 row(s) affected (0.00467900s)
  30. // Query OK, 8 row(s) affected (0.04043550s)
  31. // Connection is closed

view source code

InfluxDB line protocol write

  1. const taos = require("@tdengine/client");
  3. const conn = taos.connect({
  4.   host: "localhost",
  5. });
  7. const cursor = conn.cursor();
  9. function createDatabase() {
  10.   cursor.execute("CREATE DATABASE test");
  11.   cursor.execute("USE test");
  12. }
  14. function insertData() {
  15.   const lines = [
  16.     "meters,location=California.LosAngeles,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249",
  17.     "meters,location=California.LosAngeles,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611250",
  18.     "meters,location=California.LosAngeles,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249",
  19.     "meters,location=California.LosAngeles,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611250",
  20.   ];
  21.   cursor.schemalessInsert(
  22.     lines,
  23.     taos.SCHEMALESS_PROTOCOL.TSDB_SML_LINE_PROTOCOL,
  24.     taos.SCHEMALESS_PRECISION.TSDB_SML_TIMESTAMP_MILLI_SECONDS
  25.   );
  26. }
  28. try {
  29.   createDatabase();
  30.   insertData();
  31. } finally {
  32.   cursor.close(); 
  33.   conn.close();
  34. }

view source code

OpenTSDB Telnet line protocol write

  1. const taos = require("@tdengine/client");
  3. const conn = taos.connect({
  4.   host: "localhost",
  5. });
  7. const cursor = conn.cursor();
  9. function createDatabase() {
  10.   cursor.execute("CREATE DATABASE test");
  11.   cursor.execute("USE test");
  12. }
  14. function insertData() {
  15.   const lines = [
  16.     "meters.current 1648432611249 10.3 location=California.SanFrancisco groupid=2",
  17.     "meters.current 1648432611250 12.6 location=California.SanFrancisco groupid=2",
  18.     "meters.current 1648432611249 10.8 location=California.LosAngeles groupid=3",
  19.     "meters.current 1648432611250 11.3 location=California.LosAngeles groupid=3",
  20.     "meters.voltage 1648432611249 219 location=California.SanFrancisco groupid=2",
  21.     "meters.voltage 1648432611250 218 location=California.SanFrancisco groupid=2",
  22.     "meters.voltage 1648432611249 221 location=California.LosAngeles groupid=3",
  23.     "meters.voltage 1648432611250 217 location=California.LosAngeles groupid=3",
  24.   ];
  25.   cursor.schemalessInsert(
  26.     lines,
  27.     taos.SCHEMALESS_PROTOCOL.TSDB_SML_TELNET_PROTOCOL,
  28.     taos.SCHEMALESS_PRECISION.TSDB_SML_TIMESTAMP_NOT_CONFIGURED
  29.   );
  30. }
  32. try {
  33.   createDatabase();
  34.   insertData();
  35. } finally {
  36.   cursor.close();
  37.   conn.close();
  38. }

view source code

OpenTSDB JSON line protocol write

  1. const taos = require("@tdengine/client");
  3. const conn = taos.connect({
  4.   host: "localhost",
  5. });
  7. const cursor = conn.cursor();
  9. function createDatabase() {
  10.   cursor.execute("CREATE DATABASE test");
  11.   cursor.execute("USE test");
  12. }
  14. function insertData() {
  15.   const lines = [
  16.     {
  17.       metric: "meters.current",
  18.       timestamp: 1648432611249,
  19.       value: 10.3,
  20.       tags: { location: "California.SanFrancisco", groupid: 2 },
  21.     },
  22.     {
  23.       metric: "meters.voltage",
  24.       timestamp: 1648432611249,
  25.       value: 219,
  26.       tags: { location: "California.LosAngeles", groupid: 1 },
  27.     },
  28.     {
  29.       metric: "meters.current",
  30.       timestamp: 1648432611250,
  31.       value: 12.6,
  32.       tags: { location: "California.SanFrancisco", groupid: 2 },
  33.     },
  34.     {
  35.       metric: "meters.voltage",
  36.       timestamp: 1648432611250,
  37.       value: 221,
  38.       tags: { location: "California.LosAngeles", groupid: 1 },
  39.     },
  40.   ];
  42.   cursor.schemalessInsert(
  43.     [JSON.stringify(lines)],
  44.     taos.SCHEMALESS_PROTOCOL.TSDB_SML_JSON_PROTOCOL,
  45.     taos.SCHEMALESS_PRECISION.TSDB_SML_TIMESTAMP_NOT_CONFIGURED
  46.   );
  47. }
  49. try {
  50.   createDatabase();
  51.   insertData();
  52. } finally {
  53.   cursor.close(); 
  54.   conn.close();
  55. }

view source code

Querying data

  1. const taos = require("@tdengine/client");
  3. const conn = taos.connect({ host: "localhost", database: "power" });
  4. const cursor = conn.cursor();
  5. const query = cursor.query("SELECT ts, current FROM meters LIMIT 2");
  6. query.execute().then(function (result) {
  7.   result.pretty();
  8. });
  10. // output:
  11. // Successfully connected to TDengine
  12. //            ts             |         current          |
  13. // =======================================================
  14. // 2018-10-03 14:38:05.000   | 10.3                     |
  15. // 2018-10-03 14:38:15.000   | 12.6                     |

view source code

More sample programs

Sample ProgramsSample Program Description
basicUseBasic operations such as establishing connections and running SQl commands.
stmtBindBatchBinding multi-line parameter insertion.
stmtBindSingleParamBatchColumnar binding parameter insertion
stmtQueryBinding parameter query
schemless insertSchemaless insert
TMQUsing data subscription
asyncQueryUsing asynchronous queries
RESTUsing 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.

Frequently Asked Questions

  1. Using REST connections requires starting taosadapter.

    1. sudo systemctl start taosadapter

  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 to troubleshoot.

Important update records

Native connectors

package nameversionTDengine versionDescription
@tdengine/client3.0.03.0.0Supports TDengine 3.0. Not compatible with TDengine 2.x.
td2.0-connector2.0.122.4.x；2.5.x；2.6.xFixed cursor.close() bug.
td2.0-connector2.0.112.4.x；2.5.x；2.6.xSupports parameter binding, JSON tags and schemaless interface
td2.0-connector2.0.102.4.x；2.5.x；2.6.xSupports connection management, standard queries, connection queries, system information, and data subscription

REST Connector

package nameversionTDengine versionDescription
@tdengine/rest3.0.03.0.0Supports TDengine 3.0. Not compatible with TDengine 2.x.
td2.0-rest-connector1.0.72.4.x；2.5.x；2.6.xRemoved default port 6041。
td2.0-rest-connector1.0.62.4.x；2.5.x；2.6.xFixed affectRows bug with create, insert, update, and alter.
td2.0-rest-connector1.0.52.4.x；2.5.x；2.6.xSupport cloud token
td2.0-rest-connector1.0.32.4.x；2.5.x；2.6.xSupports connection management, standard queries, system information, error information, and continuous queries

API Reference

API Reference