TDengine Excel 集成实战：通过 ODBC 连接器将时序数据零代码导入 Excel 制作报表

TDengine Excel 集成实战：通过 ODBC 连接器将时序数据零代码导入 Excel 制作报表

【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine

通过 ODBC 连接器，Excel 可以快速访问 TDengine 中的数据：无需编写任何代码，即可将标签数据、原始时序数据或按时间聚合后的时序数据从 TDengine 导入 Excel，直接用于制作报表和数据透视分析。本文以 与 Excel 集成 官方文档为主线，完整覆盖前置环境准备、ODBC 数据源配置、Excel 端五步操作流程和数据分析实操，并结合 TDengine ODBC 参考手册 补充数据源参数、连接方式选择和数据类型映射等底层细节，帮助你在 Windows 办公环境中快速搭建“TDengine → Excel”的免代码报表链路。

一、方案概览：ODBC 是 Excel 访问 TDengine 的桥梁

Excel 本身不具备直接连接时序数据库的能力，它依赖ODBC（Open Database Connectivity）标准接口访问数据源。TDengine 为 Windows 系统提供了 ODBC 驱动程序，支持 Excel、PowerBI 等 Windows 应用以及用户自定义开发的应用程序通过 ODBC 标准接口访问本地、远程和云服务的 TDengine 数据库。

整个集成涉及三个组件，各自的角色如下：

1. TDengine 集群（v3.3.5.8 以上版本）：存储时序数据的后端，企业版与社区版均可。
2. taosAdapter：TDengine 的配套适配器组件，是 TDengine 集群和应用程序之间的桥梁。根据 taosAdapter 参考手册 的说明，TDengine 的各语言连接器（以及 ODBC 的 WebSocket 连接方式）通过 WebSocket 接口与 taosAdapter 通信，因此该组件必须安装且处于正常运行状态。
3. TDengine ODBC 驱动：安装在 Excel 所在 Windows 机器上的客户端驱动，由 TDengine Windows 客户端安装包提供。ODBC 驱动提供两种连接方式：
   • WebSocket 连接（推荐）：通过 taosAdapter 的 WebSocket 接口访问服务端，兼容性更好，一般无需随服务端升级而更新客户端，且支持云服务和 32 位应用程序；
   • 原生连接（Native）：直接调用 TDengine 客户端驱动（taosnative库）通过私有协议与服务端通信，通常性能更好，但要求客户端驱动版本与服务端版本一致，且不支持云服务和 32 位应用程序。官方文档已明确提示：ODBC 的原生连接将于 2027-01-01 下线，请迁移到 WebSocket 连接。

注意：原生连接（Native）和 WebSocket 连接在同一进程中不支持混合使用，也不允许在运行时切换。一个进程只能使用其中一种连接方式，需要在创建数据源时就确定所需的连接类型。

二、前置条件

按照官方文档，开始配置前需要准备以下环境：

• TDenginev3.3.5.8以上版本集群已部署并正常运行（企业及社区版均可）；
• taosAdapter 能够正常运行，详细参考 taosAdapter 参考手册；
• Excel 已安装并运行，如未安装，请下载并安装，具体操作请参考 Microsoft 官方文档；
• 从 TDengine 官网下载最新的 Windows 操作系统 X64 客户端驱动程序并安装（其中包含 TDengine 的 ODBC 64 位驱动；v3.3.3.0及以上版本还包含 ODBC 32 位驱动），详细参考 安装 ODBC 驱动。

关于 ODBC 驱动安装的两个补充事实（来自 ODBC 参考手册）：

• 仅支持 Windows 平台。Windows 上需要先安装 VC 运行时库，如果已经安装 VS 开发工具可忽略；
• 版本要求：v3.2.1.0及以上版本包含 ODBC 64 位驱动；v3.3.3.0及以上版本包含 ODBC 32/64 位驱动。

驱动管理器与 DSN 的架构匹配问题也需要注意：确保使用与应用程序架构匹配的 ODBC 驱动管理器——32 位应用程序需要使用 32 位 ODBC 驱动管理器，64 位应用程序需要使用 64 位 ODBC 驱动管理器。32 位和 64 位 ODBC 驱动管理器都可以看到所有 DSN，用户 DSN 标签页下的 DSN 如果名字相同会共用，因此需要在 DSN 名称上加以区分。

三、配置 ODBC 数据源

在 Excel 端操作之前，需要先在 Windows 上把 DSN（Data Source Name）配置好。

第 1 步，在 Windows 操作系统的开始菜单中搜索并打开【ODBC 数据源（64 位）】管理工具进行配置，详细步骤参考 配置 ODBC 数据源。

具体填写要点（以推荐的 WebSocket 连接为例，来自 ODBC 参考手册）：

1. 在【用户 DSN】标签页通过【添加 (D)】按钮进入“创建数据源”界面，选择【TDengine】并点击完成；
2. 在配置页面填写必要信息：
   • 【DSN】：必填，为新添加的 ODBC 数据源命名（例如MyTDengine，后续在 Excel 中要能在下拉列表里看到这个名字）；
   • 【连接类型】：必选，推荐选择【WebSocket】；
   • 【URL】：必填，ODBC 数据源 URL，本机示例：http://localhost:6041；云服务示例：https://gw.cloud.taosdata.com?token=your_token（注意 6041 端口即 taosAdapter 的 WebSocket 服务端口）；
   • 【数据库】：选填，需要连接的默认数据库；
   • 【用户名】/【密码】：选填，用于“测试连接”，如果不填，TDengine 默认为root/taosdata；
   • 【兼容软件】：支持对 ADO 和工业软件（KingSCADA、Kepware 等）的兼容性适配，通常选择默认值General即可；
   • 【启用传输压缩】：仅 WebSocket 连接可用。勾选后等价于设置COMPRESSION=1，不勾选等价于COMPRESSION=0，用于控制 WebSocket 传输是否启用压缩；
3. 点击【测试连接】，成功时提示“成功连接到 URL”；
4. 点击【确定】保存配置并退出。

如果使用Native 原生连接，则【服务器】字段必填（示例：localhost:6030，即 taosd 私有协议端口），且不支持云服务与 32 位应用程序，也不支持压缩参数。考虑到官方已宣布原生连接将于 2027-01-01 下线，建议新数据源一律选择 WebSocket 方式。

四、在 Excel 中获取数据（五步操作）

数据源配置完成后，即可在 Excel 中加载 TDengine 数据。

第 2 步，在 Windows 系统环境下启动 Excel，选择【数据】->【获取数据】->【自其他源】->【从 ODBC】：

第 3 步，在弹出窗口的【数据源名称 (DSN)】下拉列表中选择需要连接的数据源（即上一步配置的 DSN 名称），点击【确定】按钮：

第 4 步，在“ODBC 驱动程序”认证窗口输入 TDengine 的用户名和密码（对应左侧“数据库”节点），点击【连接】：

第 5 步，在弹出的【导航器】对话框中，左侧树形结构会列出可访问的库表（例如示例环境中的example_all_type_stm0、meter、power_connect等），选中要加载的库表，点击【加载】完成数据加载。右侧预览区会显示该表的实际数据内容，如ts（时间戳）、current、voltage、phase等列：

加载完成后，TDengine 中的时序数据即作为一张表格出现在 Excel 工作表中，可以直接参与筛选、公式计算和图表制作。

五、数据分析：用导入的数据制作图表

数据导入 Excel 后，就可以利用 Excel 自身的分析能力了。以官方文档的示例流程为例：

1. 选中导入的数据区域；
2. 在【插入】选项卡中选择柱状图；
3. 在右侧的【数据透视图字段】面板中配置数据字段——例如将ts与tname放到轴/图例，将phase、voltage、current等度量字段以“求和”聚合放到“值”区域，即可得到按时间戳和表名分组的度量趋势柱状图。

这里体现了时序数据在 Excel 中的典型用法：导入的每张表本质上是一个“时间 + 标签 + 指标”的二维结构，时间列（ts）天然适合作为图表横轴，指标列（如voltage、current）作为度量值，表名或标签列（如tname、location）用于系列分组，无需任何 SQL 即可得到可读性很强的运营/质检报表。

六、底层原理与细节补充

6.1 数据是如何流动的

从组件结构看，完整调用链为：Excel → 64 位 ODBC 驱动管理器 → TDengine ODBC 驱动 →（WebSocket 方式）taosAdapter 6041 端口 → TDengine 集群。ODBC 驱动在SQLConnect/SQLDriverConnect建立连接后，Excel 的导航器通过SQLTables/SQLColumns等元数据 API 枚举库表，点击【加载】后驱动执行查询并将结果集通过SQLFetch/SQLGetData逐行填充到 Excel 表格中。这些 API 的支持情况在 ODBC API 参考 中有完整列表，其中SQLTables、SQLColumns、SQLDescribeCol、SQLFetch等导航器依赖的关键接口均已支持。

6.2 数据类型在 ODBC 侧的映射

导入 Excel 后各列显示的数据格式，由 ODBC 驱动的数据类型映射决定。根据 ODBC 参考手册 的映射表，常用类型对应关系如下：

TDengine Type	SQL Type	C Type
TIMESTAMP	SQL_TYPE_TIMESTAMP	SQL_C_TIMESTAMP
INT	SQL_INTEGER	SQL_C_SLONG
BIGINT	SQL_BIGINT	SQL_C_SBIGINT
FLOAT	SQL_REAL	SQL_C_FLOAT
DOUBLE	SQL_DOUBLE	SQL_C_DOUBLE
BINARY	SQL_BINARY	SQL_C_BINARY
VARCHAR	SQL_VARCHAR	SQL_C_CHAR
BOOL	SQL_BIT	SQL_C_BIT
JSON	SQL_WVARCHAR	SQL_C_WCHAR
GEOMETRY	SQL_VARBINARY	SQL_C_BINARY

也就是说，TIMESTAMP 列会以时间戳类型进入 Excel（可参与日期函数与时间轴排序），数值列保持数值语义（可直接求和、求平均），字符串列（BINARY/VARCHAR）以文本呈现。这保证了导入后的数据在 Excel 中“开箱即用”，不需要再做格式转换。

6.3 导入哪些数据：原始数据与聚合数据

官方文档明确说明，可以导入标签数据、原始时序数据或按时间聚合后的时序数据三类内容。由于 ODBC 支持执行完整 SQL（包括INTERVAL等时序函数），实践中常见的做法是：

• 直接加载表（如上文导航器示例中的meter表），获得原始时序明细；
• 通过 DSN 中指定的默认数据库或连接后切换数据库，加载show tables、系统表等元数据视图，获取表/标签信息；
• 若数据量很大，建议先在 TDengine 中用select ... from table interval(...)之类的聚合查询得到压缩后的结果集再导入 Excel，以避免工作表超出 Excel 行数/列数限制。

6.4 ODBC 版本历史（了解驱动能力演进）

按 版本历史 一节，taos_odbc的关键演进为：v1.0.1起支持 DSN 的 BI 模式（BI 模式下不返回系统数据库和超级表子表信息）、字符集转换模块重构、配置对话框默认连接方式改为 WebSocket、增加“测试连接”控件；v1.0.2支持 CP1252 字符编码；v1.1.0支持视图功能、VARBINARY/GEOMETRY 数据类型、ODBC 32 位 WebSocket 连接（仅企业版）以及对 KingSCADA、Kepware 等工业软件的兼容适配选项；v1.1.1起支持 ADO 访问 ODBC 32/64 接口。对 Excel 报表场景而言，BI 模式（v1.0.1引入）尤其相关——它在 BI 模式下不返回系统数据库和超级表子表信息，可以让导航器的库表树更加聚焦于业务表。

七、常见问题排查

结合 ODBC 参考手册 的说明，Excel 集成时容易遇到的问题及排查方向：

1. Excel 的【从 ODBC】下拉列表中看不到 TDengine 数据源：通常是架构不匹配——64 位 Excel 需要 64 位驱动管理器下注册的 DSN；请确认在【ODBC 数据源（64 位）】中创建了 DSN，且驱动为 64 位版本。
2. 测试连接失败：检查 URL 是否正确（WebSocket 方式应为http://<host>:6041），taosAdapter 是否运行（该端口由 taosAdapter 提供），用户名密码是否为有效 TDengine 账号。
3. 连接超时或乱码：确认客户端 VC 运行时库已安装；中文/英文界面与字符编码问题可参考v1.0.1起重构的字符集转换模块与v1.0.2的 CP1252 编码支持，必要时升级 Windows 客户端驱动版本。
4. 性能不满意：若使用 Native 连接要求客户端与服务端版本严格一致；若计划长期维护，建议直接使用 WebSocket 连接，性能差别不大且兼容性更好。
5. 原生连接迁移：如果你的环境仍在使用 Native 数据源，请注意官方计划于 2027-01-01 下线原生连接，应提前按 连接方式说明 迁移到 WebSocket 连接。

八、小结

环节	关键动作	参考文档
环境准备	部署 v3.3.5.8+ 集群、保证 taosAdapter 运行、安装 Excel 与 Windows X64 客户端驱动	与 Excel 集成
ODBC 数据源	64 位驱动管理器中创建 DSN，推荐 WebSocket 连接（URLhttp://localhost:6041）	配置 ODBC 数据源
Excel 导入	数据 → 获取数据 → 自其他源 → 从 ODBC → 选 DSN → 输账号 → 导航器选表 → 加载	与 Excel 集成
数据分析	选中数据 → 插入柱状图 → 数据透视图字段配置维度与聚合	与 Excel 集成

通过上述流程，Windows 办公环境下的用户不需要编写任何代码，就能把 TDengine 中的标签数据、原始时序数据或聚合时序数据导入 Excel 并制作图表报表；而理解了 ODBC 驱动的 WebSocket 连接机制、类型映射和 BI 模式等细节后，也能在实际使用中更快定位连接、认证与数据呈现层面的问题。

【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine