Apache IoTDB C++ 原生接口完整指南：依赖安装、编译与接口实战

Apache IoTDB C++ 原生接口完整指南：依赖安装、编译与接口实战

1. 依赖

IoTDB C++ 客户端编译与运行依赖如下基础环境：

• Java 8+
• Flex
• Bison 2.7+
• Boost 1.56+
• OpenSSL 1.0+
• GCC 4.8.5+

2. 安装

2.1 安装相关依赖

Mac

# 安装 Bison
brew install bison
# 安装 Boost
brew install boost

OpenSSL 默认路径：/usr/local/opt/openssl/include，编译报错可指定 -Dopenssl.include.dir=""

Ubuntu 16.04+ / Debian

sudo apt-get update
sudo apt-get install gcc g++ bison flex libboost-all-dev libssl-dev

CentOS 7.7+ / Fedora / Rocky Linux

sudo yum update
sudo yum install gcc gcc-c++ boost-devel bison flex openssl-devel

Windows

2.2 执行编译

git clone https://github.com/apache/iotdb.git
# 切换版本（示例：2.0.6）
git checkout rc/2.0.6

注意：请勿使用高版本客户端连接低版本服务。

• Mac / Linux glibc ≥ 2.32

./mvnw clean package -pl example/client-cpp-example -am -DskipTests -P with-cpp

• Linux glibc ≥ 2.31

./mvnw clean package -pl example/client-cpp-example -am -DskipTests -P with-cpp -Diotdb-tools-thrift.version=0.14.1.1-old-glibc-SNAPSHOT

• Linux glibc ≥ 2.23

./mvnw clean package -pl example/client-cpp-example -am -DskipTests -P with-cpp -Diotdb-tools-thrift.version=0.14.1.1-glibc223-SNAPSHOT

• Linux glibc ≥ 2.17

./mvnw clean package -pl example/client-cpp-example -am -DskipTests -P with-cpp -Diotdb-tools-thrift.version=0.14.1.1-gcc4-SNAPSHOT

• Windows VS 2022

.\\mvnw.cmd clean package -pl example/client-cpp-example -am -DskipTests -P with-cpp

• Windows VS 2019

.\\mvnw.cmd clean package -pl example/client-cpp-example -am -DskipTests -P with-cpp -Dcmake.generator="Visual Studio 16 2019" -Diotdb-tools-thrift.version=0.14.1.1-msvc142-SNAPSHOT

编译产物路径：

• 库文件：iotdb-client/client-cpp/target
• 示例程序：example/client-cpp-example/target

2.3 编译 Q&A

• Linux 环境要求
  • x86_64：glibc ≥ 2.17、GCC ≥ 5.5
  • ARM：glibc ≥ 2.31、GCC ≥ 10.2 不满足可自行编译 Thrift 再重新编译客户端。
• undefined reference to ‘_libc_sinle_thread’ 编译命令添加对应低 glibc 版本参数。
• Windows 使用 VS 2017 及更早版本 自行编译 Thrift 后，指定 VS 2017 编译器编译。

3. 基本接口说明

3.1 初始化

// 开启 Session
void open();
// 开启 Session 并设置 RPC 压缩
void open(bool enableRPCCompression);
// 关闭 Session
void close();

注意：客户端与服务端 RPC 压缩状态必须一致。

3.2 数据定义接口（DDL）

数据库（存储组）管理

• 设置存储组：setStorageGroup
• 删除存储组：deleteStorageGroup/deleteStorageGroups

时间序列管理

• 创建单条/多条时序：createTimeseries/createMultiTimeseries
• 创建对齐时序：createAlignedTimeseries
• 删除时序：deleteTimeseries
• 检查时序是否存在：checkTimeseriesExists

元数据模板

• 创建/挂载/卸载模板：createSchemaTemplate、setSchemaTemplate、unsetSchemaTemplate
• 增删模板物理量：addAlignedMeasurementsInTemplate、addUnalignedMeasurementsInTemplate、deleteNodeInTemplate
• 查询模板信息：countMeasurementsInTemplate、isMeasurementInTemplate、showMeasurementsInTemplate

3.3 数据操作接口（DML）

数据写入

• Tablet 批量写入（推荐，性能更高）：insertTablet、insertTablets
• Record 单行/批量写入：insertRecord、insertRecords、insertRecordsOfOneDevice
• 对齐时序专属写入：insertAlignedRecord、insertAlignedTablet 等

数据删除

void deleteData(const std::string &path, int64_t endTime);
void deleteData(const std::vector<std::string> &paths, int64_t startTime, int64_t endTime);

3.4 IoTDB-SQL 接口

• 执行查询：executeQueryStatement，返回 SessionDataSet 用于遍历结果
• 执行非查询 SQL：executeNonQueryStatement

4. 示例代码

示例源码路径：

• example/client-cpp-example/src/SessionExample.cpp
• example/client-cpp-example/src/AlignedTimeseriesSessionExample.cpp（对齐时序）

5. FAQ

5.1 Thrift 编译相关问题

• Mac：Xcode commandline 版本 12 报错可降级至 11.5
• Windows：清理 .m2\\repository\\.cache 或在插件中配置 <skipCache>true</skipCache>

文章总结

本文全面介绍 Apache IoTDB C++ 原生接口的使用流程，先明确依赖环境，再给出 Mac、Linux、Windows 三大平台的依赖安装与 Maven 编译命令，并针对常见编译异常提供解决方案。接着详细讲解 Session 初始化、DDL 元数据管理、DML 数据读写、SQL 执行等核心接口用法，说明 Tablet 批量写入的性能优势与对齐时序专用接口。最后提供官方示例代码与 Thrift 编译问题处理方案，帮助 C++ 开发者快速完成 IoTDB 时序数据库的接入、编译、开发与调试，降低跨平台集成门槛。

🌐 附：IoTDB的各大版本

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

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

联系博主

    xcLeigh 博主，全栈领域优质创作者，博客专家，目前，活跃在CSDN、微信公众号、小红书、知乎、掘金、快手、思否、微博、51CTO、B站、腾讯云开发者社区、阿里云开发者社区等平台，全网拥有几十万的粉丝，全网统一IP为 xcLeigh。希望通过我的分享，让大家能在喜悦的情况下收获到有用的知识。主要分享编程、开发工具、算法、技术学习心得等内容。很多读者评价他的文章简洁易懂，尤其对于一些复杂的技术话题，他能通过通俗的语言来解释，帮助初学者更好地理解。博客通常也会涉及一些实践经验，项目分享以及解决实际开发中遇到的问题。如果你是开发领域的初学者，或者在学习一些新的编程语言或框架，关注他的文章对你有很大帮助。

    亲爱的朋友，无论前路如何漫长与崎岖，都请怀揣梦想的火种，因为在生活的广袤星空中，总有一颗属于你的璀璨星辰在熠熠生辉，静候你抵达。

     愿你在这纷繁世间，能时常收获微小而确定的幸福，如春日微风轻拂面庞，所有的疲惫与烦恼都能被温柔以待，内心永远充盈着安宁与慰藉。

    至此，文章已至尾声，而您的故事仍在续写，不知您对文中所叙有何独特见解？期待您在心中与我对话，开启思想的新交流。

     💞 关注博主 🌀 带你实现畅游前后端！

     🏰 大屏可视化 🌀 带你体验酷炫大屏！

     💯 神秘个人简介 🌀 带你体验不一样得介绍！

     🥇 从零到一学习Python 🌀 带你玩转Python技术流！

     🏆 前沿应用深度测评 🌀 前沿AI产品热门应用在线等你来发掘！

     💦 注：本文撰写于CSDN平台,作者：xcLeigh（所有权归作者所有） ，https://xcleigh.blog.csdn.net/，如果相关下载没有跳转，请查看这个地址，相关链接没有跳转，皆是抄袭本文，转载请备注本文原地址。

     📣 亲，码字不易，动动小手，欢迎 点赞 ➕ 收藏，如 🈶 问题请留言（或者关注下方公众号，看见后第一时间回复，还有海量编程资料等你来领！），博主看见后一定及时给您答复 💌💌💌