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

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

  • 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 td2.0-connector
  1. 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.

  1. npm init -y
  2. npm install td2.0-connector
  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 refer to td2.0-connector package:

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

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

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

Usage examples

Write data

SQL Writing

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

view source code

InfluxDB line protocol writing

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

view source code

OpenTSDB Telnet line protocol writing

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

view source code

OpenTSDB JSON line protocol writing

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

view source code

Query data

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

view source code

More Sample Programs

Sample ProgramsSample Program Description
connectionExample of establishing a connection.
stmtBindBatchExample of binding a multi-line parameter Example of inserting.
stmtBindExample of a line-by-line bind parameter insertion.
stmtBindSingleParamBatch stmtBindSingleParamBatchSample.js)Example of binding parameters by column.
stmtUseResultExample of a bound parameter query.
json tagExample of using Json tag.
NanosecondAn example of using timestamps with nanosecond precision.
MicrosecondExample of using microsecond timestamp.
schemless insertschemless Example of a schemless insert.
subscribeExample of using subscribe.
asyncQueryAn example of using asynchronous queries.
RESTAn 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.

Other notes

See video tutorial for the Node.js connector usage.

Frequently Asked Questions

  1. Using REST connections requires starting taosadapter.

    1. 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 versiondescription
2.0.12Fix bug with cursor.close() error.
2.0.11Support for binding parameters, json tag, schemaless interface, etc.
2.0.10Support connection management, general query, continuous query, get system information, subscribe function, etc.

REST Connector

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

API Reference

API Reference