Apache IoTDB Node.js 原生接口完整指南：Thrift 编译 + 接口使用

IoTDB 基于 Thrift 实现跨语言 RPC 通信，Node.js 可以通过编译 Thrift 文件生成原生接口，直接与 IoTDB 服务端交互。本文详细讲解依赖环境、Thrift 编译配置、接口生成与项目引入流程，并整理全部支持的 RPC 接口，帮你快速用 Node.js 对接 IoTDB。

一、依赖环境

在开始编译与开发前，需要先配置好以下环境：

JDK ≥ 1.8

Node.js ≥ 16.0.0

Thrift ≥ 0.14.1（必须安装，用于编译生成代码）

系统支持：Linux/Mac/Windows（WSL/cygwin/Git Bash）

说明：Thrift 是核心依赖，必须安装并配置到环境变量，才能把 .thrift 定义文件编译成可直接调用的 Node.js 代码。

二、编译 Thrift 生成 Node.js 原生接口

IoTDB 本身提供  Java 版本的 Thrift 编译配置，我们只需要在 pom.xml 中追加 Node.js 编译配置，即可自动生成 JS 接口。

1. 修改 pom.xml 配置

打开 IoTDB 源码根目录下的 pom.xml，找到 Java 版本的 Thrift 执行配置，新增一段 Node.js 编译配置：

<execution>    <id>generate-thrift-sources-nodejs</id>    <phase>generate-sources</phase>    <goals>        <goal>compile</goal>    </goals>    <configuration>        <generator>js:node</generator>        <thriftExecutable>${thrift.exec.absolute.path}</thriftExecutable>        <thriftSourceRoot>${basedir}/src/main/thrift</thriftSourceRoot>        <includes>**/common.thrift,**/client.thrift</includes>        <outputDirectory>${project.build.directory}/generated-sources-nodejs</outputDirectory>    </configuration> </execution>

2. 执行编译命令

在 IoTDB 源码根目录运行  Maven 命令：

mvn clean generate-sources

3. 编译说明

执行后会自动清理并重新生成：

iotdb/iotdb-protocol/thrift/target

iotdb/iotdb-protocol/thrift-commons/target

重要提醒：生成的 target 目录属于临时构建产物，绝对不要提交到 Git 仓库。

三、在项目中使用 Node.js 原生接口

编译完成后，只需要把生成的代码复制到你的 Node.js 项目即可使用：

复制以下两个目录的所有文件到项目：

iotdb/iotdb-protocol/thrift/target/generated-sources-nodejs/

iotdb/iotdb-protocol/thrift-commons/target/generated-sources-nodejs/

在项目中引入文件，即可调用 RPC 接口与 IoTDB 交互。

四、Node.js 支持的全部 RPC 接口

生成的接口覆盖会话管理、SQL 执行、数据写入、元数据操作、数据删除等完整能力，以下是完整接口清单：

1. 会话管理

openSession：打开会话

closeSession：关闭会话

getTimeZone：获取时区

setTimeZone：设置时区

getProperties：获取服务端配置

2. SQL 执行接口

executeStatement：执行单条 SQL

executeBatchStatement：批量执行 SQL

executeQueryStatement：执行查询 SQL

executeUpdateStatement：执行插入/删除类更新语句

fetchResults：获取下一批查询结果

fetchMetadata：获取元数据

cancelOperation：取消查询

closeOperation：关闭查询并释放资源

3. 元数据操作

setStorageGroup：设置存储组

deleteStorageGroups：删除存储组

createTimeseries：创建单条时间序列

createMultiTimeseries：批量创建时间序列

deleteTimeseries：删除时间序列

4. 数据写入接口

insertRecord/insertRecords：按行插入/批量插入

insertStringRecord/insertStringRecords：字符串格式按行插入

insertRecordsOfOneDevice：同一设备批量插入

insertTablet/insertTablets：按列批量插入（高性能）

各类 testInsertXXX：测试写入性能（不真实落库）

5. 数据删除与查询

deleteData：按条件删除数据

executeRawDataQuery：原始数据查询

requestStatementId：申请查询语句 ID

文章总结

本文完整介绍了 Apache IoTDB Node.js 原生接口的生成与使用流程。先明确 JDK、Node.js、Thrift 等依赖要求，再讲解如何修改 Maven 配置、执行编译命令自动生成 Node.js 接口，说明文件复制与项目引入方法。最后整理会话、SQL、元数据、数据写入/删除等全量 RPC 接口，覆盖 IoTDB 所有核心操作。按照本文步骤，即可快速完成 Node.js 项目与 IoTDB 的原生对接，满足时序数据开发需求。

附：IoTDB的各大版本

Apache IoTDB 是一款工业物联网时序数据库管理系统，采用端边云协同的轻量化架构，支持一体化的物联网时序数据收集、存储、管理与分析 ，具有多协议兼容、超高压缩比、高通量读写、工业级稳定、极简运维等特点。

✨ 目前最新版本为2.0.7，去获取：https://archive.apache.org/dist/iotdb/