TDengine Node.js Connector

TDengine Node.js Connector

@tdengine/client 和 @tdengine/rest 是 TDengine 的官方 Node.js 语言连接器。 Node.js 开发人员可以通过它开发可以存取 TDengine 集群数据的应用软件。注意：从 TDengine 3.0 开始 Node.js 原生连接器的包名由 td2.0-connector 改名为 @tdengine/client 而 rest 连接器的包名由 td2.0-rest-connector 改为 @tdengine/rest。并且不与 TDengine 2.x 兼容。

@tdengine/client 是原生连接器，它通过 TDengine 客户端驱动程序（taosc）连接 TDengine 运行实例，支持数据写入、查询、订阅、schemaless 接口和参数绑定接口等功能。@tdengine/rest 是 REST 连接器，它通过 taosAdapter 提供的 REST 接口连接 TDengine 的运行实例。REST 连接器可以在任何平台运行，但性能略为下降，接口实现的功能特性集合和原生接口有少量不同。

Node.js 连接器源码托管在 GitHub。

支持的平台

原生连接器支持的平台和 TDengine 客户端驱动支持的平台一致。 REST 连接器支持所有能运行 Node.js 的平台。

版本支持

请参考版本支持列表

支持的功能特性

原生连接器
REST 连接器

连接管理
普通查询
连续查询
参数绑定
订阅功能
Schemaless
连接管理
普通查询
连续查询

安装步骤

安装前准备

安装 Node.js 开发环境
如果使用 REST 连接器，跳过此步。但如果使用原生连接器，请安装 TDengine 客户端驱动，具体步骤请参考安装客户端驱动。我们使用 node-gyp 和 TDengine 实例进行交互，还需要根据具体操作系统来安装下文提到的一些依赖工具。
Linux 系统安装依赖工具
macOS 系统安装依赖工具
Windows 系统安装依赖工具
python (建议v2.7 , v3.x.x 目前还不支持)
@tdengine/client 3.0.0 支持 Node.js LTS v10.9.0 或更高版本, Node.js LTS v12.8.0 或更高版本；其他版本可能存在包兼容性的问题
make
C 语言编译器，GCC v4.8.5 或更高版本
python (建议v2.7 , v3.x.x 目前还不支持)
@tdengine/client 3.0.0 目前是只支持 Node.js v12.22.12 或 v12 的更高版本；其他版本可能存在包兼容性的问题
make
C 语言编译器，GCC v4.8.5 或更高版本
安装方法 1

使用微软的windows-build-tools在cmd 命令行界面执行npm install --global --production windows-build-tools 即可安装所有的必备工具。

安装方法 2

手动安装以下工具：

安装 Visual Studio 相关：Visual Studio Build 工具或者 Visual Studio 2017 Community
安装 Python 2.7(v3.x.x 暂不支持) 并执行 npm config set python python2.7
进入cmd命令行界面，npm config set msvs_version 2017

参考微软的 Node.js 用户手册Microsoft’s Node.js Guidelines for Windows。

如果在 Windows 10 ARM 上使用 ARM64 Node.js，还需添加 “Visual C++ compilers and libraries for ARM64” 和 “Visual C++ ATL for ARM64”。

使用 npm 安装

安装原生连接器
安装 REST 连接器

npm install @tdengine/client

npm install @tdengine/rest

安装验证

原生连接器
REST 连接器

在安装好 TDengine 客户端后，使用 nodejsChecker.js 程序能够验证当前环境是否支持 Node.js 方式访问 TDengine。

验证方法：

新建安装验证目录，例如：~/tdengine-test，下载 GitHub 上 nodejsChecker.js 源代码到本地。
在命令行中执行以下命令。

npm init -y
npm install @tdengine/client
node nodejsChecker.js host=localhost

执行以上步骤后，在命令行会输出 nodejsChecker.js 连接 TDengine 实例，并执行简单插入和查询的结果。

在安装好 TDengine 客户端后，使用 nodejsChecker.js 程序能够验证当前环境是否支持 Node.js 方式访问 TDengine。

验证方法：

新建安装验证目录，例如：~/tdengine-test，下载 GitHub 上 restChecker.js 源代码到本地。
在命令行中执行以下命令。

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

执行以上步骤后，在命令行会输出 restChecker.js 连接 TDengine 实例，并执行简单插入和查询的结果。

建立连接

请选择使用一种连接器。

原生连接
REST 连接

安装并引用 @tdengine/client 包。

//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();

安装并引用 @tdengine/rest 包。

//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();

使用示例

写入数据

SQL 写入

原生连接
REST 连接

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

查看源码

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

查看源码

InfluxDB 行协议写入

原生连接

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

查看源码

OpenTSDB Telnet 行协议写入

原生连接

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

查看源码

OpenTSDB JSON 行协议写入

原生连接

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

查看源码

查询数据

原生连接
REST 连接

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                     |

查看源码

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

查看源码

示例程序	示例程序描述
basicUse	基本的使用如如建立连接，执行 SQL 等操作。
stmtBindBatch	绑定多行参数插入的示例。
stmtBindSingleParamBatch	按列绑定参数插入的示例。
stmtQuery	绑定参数查询的示例。
schemless insert	schemless 插入的示例。
TMQ	订阅的使用示例。
asyncQuery	异步查询的使用示例。
REST	使用 REST 连接的 TypeScript 使用示例。

使用限制

native 连接器（@tdengine/client） >= v3.0.0 目前支持 node 的版本为：支持 >=v12.8.0 <= v12.9.1 || >=v10.20.0 <= v10.9.0 ；2.0.5 及更早版本支持 v10.x 版本，其他版本可能存在包兼容性的问题。

其他说明

Node.js 连接器的使用参见视频教程。

常见问题

使用 REST 连接需要启动 taosadapter。
```
sudo systemctl start taosadapter
```
Node.js 版本

原生连接器 @tdengine/client 目前兼容的 Node.js 版本为：>=v10.20.0 <= v10.9.0 || >=v12.8.0 <= v12.9.1
“Unable to establish connection”，”Unable to resolve FQDN”

一般都是因为配置 FQDN 不正确。可以参考如何彻底搞懂 TDengine 的 FQDN 。

重要更新记录

原生连接器

package name	version	TDengine version	说明
@tdengine/client	3.0.0	3.0.0	支持TDengine 3.0 且不与2.x 兼容。
td2.0-connector	2.0.12	2.4.x；2.5.x；2.6.x	修复 cursor.close() 报错的 bug。
td2.0-connector	2.0.11	2.4.x；2.5.x；2.6.x	支持绑定参数、json tag、schemaless 接口等功能。
td2.0-connector	2.0.10	2.4.x；2.5.x；2.6.x	支持连接管理，普通查询、连续查询、获取系统信息、订阅功能等功能。

REST 连接器

package name	version	TDengine version	说明
@tdengine/rest	3.0.0	3.0.0	支持 TDegnine 3.0，且不与2.x 兼容。
td2.0-rest-connector	1.0.7	2.4.x；2.5.x；2.6.x	移除默认端口 6041。
td2.0-rest-connector	1.0.6	2.4.x；2.5.x；2.6.x	修复create，insert，update，alter 等SQL 执行返回的 affectRows 错误的bug。
td2.0-rest-connector	1.0.5	2.4.x；2.5.x；2.6.x	支持云服务 cloud Token；
td2.0-rest-connector	1.0.3	2.4.x；2.5.x；2.6.x	支持连接管理、普通查询、获取系统信息、错误信息、连续查询等功能。

Node.js

TDengine Node.js Connector

支持的平台

版本支持

支持的功能特性

安装步骤

安装前准备

使用 npm 安装

安装验证

建立连接

使用示例

写入数据

SQL 写入

InfluxDB 行协议写入

OpenTSDB Telnet 行协议写入

OpenTSDB JSON 行协议写入

查询数据

更多示例程序

使用限制

其他说明

常见问题

重要更新记录

原生连接器

REST 连接器

API 参考