TDengine Node.js Connector
td2.0-connector
和 td2.0-rest-connector
是 TDengine 的官方 Node.js 语言连接器。Node.js 开发人员可以通过它开发可以存取 TDengine 集群数据的应用软件。
td2.0-connector
是原生连接器,它通过 TDengine 客户端驱动程序(taosc)连接 TDengine 运行实例,支持数据写入、查询、订阅、schemaless 接口和参数绑定接口等功能。td2.0-rest-connector
是 REST 连接器,它通过 taosAdapter 提供的 REST 接口连接 TDengine 的运行实例。REST 连接器可以在任何平台运行,但性能略为下降,接口实现的功能特性集合和原生接口有少量不同。
Node.js 连接器源码托管在 GitHub。
支持的平台
原生连接器支持的平台和 TDengine 客户端驱动支持的平台一致。 REST 连接器支持所有能运行 Node.js 的平台。
版本支持
请参考版本支持列表
支持的功能特性
原生连接器
- 连接管理
- 普通查询
- 连续查询
- 参数绑定
- 订阅功能
- Schemaless
REST 连接器
- 连接管理
- 普通查询
- 连续查询
安装步骤
安装前准备
- 安装 Node.js 开发环境
- 如果使用 REST 连接器,跳过此步。但如果使用原生连接器,请安装 TDengine 客户端驱动,具体步骤请参考安装客户端驱动。我们使用 node-gyp 和 TDengine 实例进行交互,还需要根据具体操作系统来安装下文提到的一些依赖工具。
- Linux 系统安装依赖工具
- Windows 系统安装依赖工具
python
(建议v2.7
,v3.x.x
目前还不支持)td2.0-connector
2.0.6 支持 Node.js LTS v10.9.0 或更高版本, Node.js LTS v12.8.0 或更高版本;2.0.5 及更早版本支持 Node.js LTS v10.x 版本。其他版本可能存在包兼容性的问题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 td2.0-connector
npm i td2.0-rest-connector
安装验证
在安装好 TDengine 客户端后,使用 nodejsChecker.js 程序能够验证当前环境是否支持 Node.js 方式访问 TDengine。
验证方法:
-
新建安装验证目录,例如:
~/tdengine-test
,下载 GitHub 上 nodejsChecker.js 源代码到本地。 -
在命令行中执行以下命令。
npm init -y
npm install td2.0-connector
node nodejsChecker.js host=localhost
- 执行以上步骤后,在命令行会输出 nodejsChecker.js 连接 TDengine 实例,并执行简单插入和查询的结果。
建立连接
请选择使用一种连接器。
- 原生连接
- REST 连接
安装并引用 td2.0-connector
包。
//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();
安装并引用 td2.0-rest-connector
包。
//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();
使用示例
写入数据
SQL 写入
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
InfluxDB 行协议写入
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();
}
OpenTSDB Telnet 行协议写入
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();
}
OpenTSDB JSON 行协议写入
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();
}
查询数据
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 |
更多示例程序
示例程序 | 示例程序描述 |
---|---|
connection | 建立连接的示例。 |
stmtBindBatch | 绑定多行参数插入的示例。 |
stmtBind | 一行一行绑定参数插入的示例。 |
stmtBindSingleParamBatch | 按列绑定参数插入的示例。 |
stmtUseResult | 绑定参数查询的示例。 |
json tag | Json tag 的使用示例。 |
Nanosecond | 时间戳为纳秒精度的使用的示例。 |
Microsecond | 时间戳为微秒精度的使用的示例。 |
schemless insert | schemless 插入的示例。 |
subscribe | 订阅的使用示例。 |
asyncQuery | 异步查询的使用示例。 |
REST | 使用 REST 连接的 TypeScript 使用示例。 |
使用限制
Node.js 连接器 >= v2.0.6 目前支持 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 版本
连接器 >v2.0.6 目前兼容的 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 。
重要更新记录
原生连接器
td2.0-connector 版本 | 说明 |
---|---|
2.0.12 | 修复 cursor.close() 报错的 bug。 |
2.0.11 | 支持绑定参数、json tag、schemaless 接口等功能。 |
2.0.10 | 支持连接管理,普通查询、连续查询、获取系统信息、订阅功能等功能。 |
REST 连接器
td2.0-rest-connector 版本 | 说明 |
---|---|
1.0.3 | 支持连接管理、普通查询、获取系统信息、错误信息、连续查询等功能。 |