TDengine Node.js Connector

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.

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.

The Node.js connector source code is hosted 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 function
6. Schemaless

REST Connector

1. connection management
2. general queries
3. Continuous query

Installation steps

Pre-installation

• 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

• 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
• make
• C compiler, GCC v4.8.5 or higher

Windows system installation dependencies

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

npm install td2.0-connector

Install REST connector

npm i td2.0-rest-connector

Installation verification

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 from GitHub. to the work directory.

• Execute the following command from the command-line.

npm init -y
npm install td2.0-connector
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

Install and refer to td2.0-connector package:

//A cursor also needs to be initialized in order to interact with TDengine from Node.js.
const taos = require("td2.0-connector");
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();

REST connection

Install and refer to td2.0-rest-connectorpackage:

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

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

Usage examples

Write data

SQL Writing

const taos = require("td2.0-connector");

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);
} 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

InfluxDB line protocol writing

const taos = require("td2.0-connector");

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 writing

const taos = require("td2.0-connector");

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 writing

const taos = require("td2.0-connector");

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

Query data

const taos = require("td2.0-connector");

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
// Query OK, 2 row(s) in set (0.00317767s)

//            ts             |         current          |
// =======================================================
// 2018-10-03 14:38:05.000   | 10.3                     |
// 2018-10-03 14:38:15.000   | 12.6                     |

view source code

More Sample Programs

| Sample Programs | Sample Program Description | | --------------------------------------------------------------------------------------------------------------------------------- --------- | -------------------------------------- | | connection | Example of establishing a connection. | | stmtBindBatch | Example of binding a multi-line parameter Example of inserting. | | stmtBind | Example of a line-by-line bind parameter insertion. | | stmtBindSingleParamBatch stmtBindSingleParamBatchSample.js) | Example of binding parameters by column. | | stmtUseResult | Example of a bound parameter query. | | json tag | Example of using Json tag. | | Nanosecond | An example of using timestamps with nanosecond precision. | | Microsecond | Example of using microsecond timestamp. | | schemless insert | schemless Example of a schemless insert. | | subscribe | Example of using subscribe. | | asyncQuery | An example of using asynchronous queries. | | REST | An example of using TypeScript with REST connections. |

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.

Frequently Asked Questions

1. Using REST connections requires starting taosadapter.

   sudo systemctl start taosadapter

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

Native connectors

td2.0-connector version	description
2.0.12	Fix bug with cursor.close() error.
2.0.11	Support for binding parameters, json tag, schemaless interface, etc.
2.0.10	Support connection management, general query, continuous query, get system information, subscribe function, etc.

REST Connector

td2.0-rest-connector version	Description
1.0.3	Support connection management, general query, get system information, error message, continuous query, etc.

API Reference

API Reference