企业官网建设流程全解析

TDengine 零代码接入 MongoDB：通过 taosExplorer 配置数据同步任务实战指南

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

MongoDB 作为介于关系型与非关系型之间的文档数据库，广泛应用于内容管理系统、移动应用与物联网场景，其数据往往需要与 TDengine 的时序能力结合使用。本文基于 TDengine 企业版 3.3.3.0 起的 taosExplorer 数据写入功能，完整讲解如何以零代码方式创建 MongoDB 到 TDengine 的数据接入任务，覆盖连接配置、认证、查询模板、数据映射与异常处理全流程。读完本文，你将能够独立完成 MongoDB 历史数据迁移与实时数据同步任务的创建、调优与排障。

功能概述

MongoDB 是一个介于关系型数据库与非关系型数据库之间的产品，被广泛应用于内容管理系统、移动应用与物联网等众多领域。很多业务系统会先使用 MongoDB 承载设备上报数据，但随着设备量增长与实时性要求提高，需要将数据迁移到专门为时序数据优化的 TDengine 中进行存储与分析。

从TDengine 企业版 3.3.3.0开始，TDengine 可以高效地从 MongoDB 读取数据并将其写入 TDengine，以实现历史数据迁移或实时数据同步，解决业务面临的技术痛点。根据 零代码数据写入总览 中的数据源支持列表，MongoDB 支持版本为3.6+。

该能力由 taosExplorer 图形界面与 taosX 数据接入服务共同承载：写入过程中可对数据执行提取、过滤和转换，以统一命名空间并提升数据质量，从而减少额外 ETL 组件。若 taosX 无法直连数据源，可参考 安装 taosX-Agent 在数据源侧部署代理。

前置条件

在创建 MongoDB 数据写入任务前，请确认以下条件：

1. taosExplorer 已可访问，且目标 TDengine 集群运行正常。
2. 目标数据库已存在，或准备在任务创建页面直接创建。
3. 源 MongoDB 数据库可连通，且用于认证的用户具备读取权限。
4. 如需通过代理接入，确保 taosX-Agent 已安装并在线（详见 安装 taosX-Agent）。

创建任务

新增数据源

登录 taosExplorer 后，在左侧导航栏点击“数据写入”进入任务列表页面，点击+新增数据源按钮进入新增数据源页面，如下图所示：

进入新增数据源页面

配置基本信息

在名称字段中输入任务名称，例如test_mongodb_01。

选择类型下拉框中的MongoDB，选择完成后页面中的字段会随数据源类型发生变化，如下图所示：

选择数据源类型为 MongoDB

其余基本信息说明如下：

• 代理：非必填项。如有需要，可以在下拉框中选择指定的代理，也可以先点击右侧的+创建新的代理按钮创建一个新的代理。
• 目标数据库：必填项。可以在下拉框中选择指定的数据库，也可以先点击右侧的+创建数据库按钮创建一个新的数据库。

配置连接信息

在连接配置区域填写源 MongoDB 数据库的连接信息，包括源 MongoDB 服务的地址、端口等，如下图所示：

填写源 MongoDB 数据库的连接信息

配置认证信息

配置认证信息

配置连接选项

• 应用名称：设置应用程序名称，用于标识连接的应用程序。
• SSL 证书：设置是否使用加密连接，默认关闭。如果开启，需要上传以下两个文件：
  1. CA 文件：上传 SSL 加密的证书授权文件；
  2. 证书文件：上传 SSL 加密的证书文件。

配置连接选项

配置完成后，点击检查连通性按钮，可以检查上方填写的信息是否可以正常获取源 MongoDB 数据库的数据；若检查失败，请根据页面返回的具体错误提示修正配置。

配置数据查询

数据查询部分决定了“读什么、按什么顺序读、分几段读”，是 MongoDB 任务的核心配置区域。

配置数据查询

数据库与集合（支持动态占位符）

• 数据库：MongoDB 中的源数据库，可以使用占位符进行动态配置，例如database_${Y}。
• 集合：MongoDB 中的集合，可以使用占位符进行动态配置，例如collection_${md}。

可用占位符列表如下：

子表字段

子表字段用于拆分子表的字段，通常与 transform 中的 tag 相对应，多个字段使用英文逗号分隔，例如col_name1,col_name2。

此项配置主要为了解决数据迁移乱序问题，需要结合查询模板共同使用，否则不能达到预期效果。使用示例如下：

1. 配置两个子表字段col_name1,col_name2；
2. 在查询模板中添加子表字段占位符，例如{"ddate":{"$gte":${start_datetime},"$lt":${end_datetime}}, ${col_name1}, ${col_name2}}。运行时${col_name1}、${col_name2}会展开为 JSON 字段过滤条件（如"col_name1":"deviceA"），而不是裸字段名；
3. 在transform中配置col_name1与col_name2两个 tag 映射。

通过这种方式，查询会按子表维度分段进行，避免跨子表乱序写入导致的数据错乱。

查询模板

查询模板是用于查询数据的查询语句，JSON 格式。语句中必须包含时间范围条件，且开始时间和结束时间必须成对出现。模板中定义的时间范围由源数据库中的某个代表时间的列和下方定义的占位符组成。

使用不同的占位符表示不同的时间格式要求，具体有以下占位符格式：

1. ${start_datetime}、${end_datetime}：对应后端 datetime 类型字段的筛选。例如：{"ddate":{"$gte":${start_datetime},"$lt":${end_datetime}}}将被转换为：{"ddate":{"$gte":{"$date":"2024-06-01T00:00:00+00:00"},"$lt":{"$date":"2024-07-01T00:00:00+00:00"}}}
2. ${start_timestamp}、${end_timestamp}：对应后端 timestamp 类型字段的筛选。例如：{"ttime":{"$gte":${start_timestamp},"$lt":${end_timestamp}}}将被转换为：{"ttime":{"$gte":{"$timestamp":{"t":123,"i":456}},"$lt":{"$timestamp":{"t":123,"i":456}}}}

查询排序

查询排序是执行查询时的排序条件，JSON 格式，它必须符合 MongoDB 排序条件的格式规范。使用示例如下：

1. {"createtime":1}：MongoDB 查询结果按 createtime 正序返回；
2. {"createdate":1, "createtime":1}：MongoDB 查询结果按 createdate 正序、createtime 正序返回。

建议为迁移任务配置按时间列正序排序，与 MySQL 接入 文档中“解决迁移数据乱序应在查询语句中添加排序条件”的思路一致，可进一步规避乱序问题。

时间范围与分段查询

• 起始时间：迁移数据的起始时间，此项为必填字段。
• 结束时间：迁移数据的结束时间，可留空。如果设置，则迁移任务执行到结束时间后，任务完成自动停止；如果留空，则持续同步实时数据，任务不会自动停止。
• 查询间隔：分段查询数据的时间间隔，默认1 天。为了避免查询数据量过大，一次数据同步子任务会使用查询间隔分时间段查询数据。
• 延迟时长：与查询间隔配合使用。在实时同步数据场景中，为了避免延迟写入的数据丢失，每次同步任务会在“时间间隔 + 延迟时长”的时间点触发查询。例如：时间间隔为 3600s，延迟时长为 60 秒，那么查询任务会在 09:01 时触发查询源数据库中 08:00 - 09:00 时间段的数据。

配置数据映射

在Payload 转换区域填写数据映射相关的配置参数，通过内置 ETL 能力完成从原始 MongoDB 文档到 TDengine 表结构的转换。关于 ETL 各环节的完整规则说明可参见 零代码数据写入总览 中的“数据提取、过滤和转换”章节。

1. 点击从服务器检索按钮，从 MongoDB 服务器获取示例数据。
2. 在解析中选择 JSON / Regex / UDT 三种规则解析原始消息体，配置完成后点击右侧的预览按钮可以查看解析的结果。
3. 在从列中提取或拆分中填写从消息体中提取或拆分的字段。例如：将 vValue 字段拆分成vValue_0和vValue_1这 2 个字段，选择 split 提取器，separator 填写分割符,，number 填写 2，配置完成后点击右侧的预览按钮可以查看转换的结果。拆分后的字段命名规则为{原字段名}_{顺序号}。
4. 在过滤中填写过滤条件。例如：填写Value > 0，则只有 Value 大于 0 的数据才会被写入 TDengine，配置完成后点击右侧的预览按钮可以查看过滤的结果。过滤条件表达式的计算结果必须是 boolean 类型，支持>、>=、<=、<、==、!=等比较操作符以及&&、||、!逻辑组合。
5. 在映射中，选择要映射到 TDengine 的超级表，以及映射到超级表的列（tag 与 column），配置完成后点击右侧的预览按钮可以查看映射的结果。支持的映射规则包括：直接映射（mapping）、常量（value）、时间戳生成器（generator）、字符串连接（join）、字符串格式化（format）、求和（sum）以及数值运算表达式（expr），子表名也可以通过 format 表达式动态生成。

配置高级选项

高级选项区域默认折叠，点击右侧>可展开（不同数据源展示的字段可能略有差异）。常见配置项如下：

• 最大读取并发数：限制数据源连接数或读取线程数。默认0表示由采集器自动配置；数据源响应较慢时可适当增大。
• 批次大小：单次发送的最大消息数或行数。默认值因数据源而异（常见为1000或10000）。
• 写入并发数量：同时写入 TDengine 的并发任务数（部分数据源提供）。
• 健康监测相关选项（健康监测时段、Busy 状态阈值、写入队列长度、写入错误阈值等）的含义见 零代码数据写入总览中的健康状态。

完整字段说明可查看 高级选项配置。

异常处理策略

异常处理策略区域默认折叠，点击右侧>可展开，用于对写入过程中的各类异常配置处置策略。通用策略说明如下：

• 归档：将异常数据写入归档文件（默认路径为${data_dir}/tasks/_id/.datetime），不写入目标库；
• 丢弃：将异常数据忽略，不写入目标库；
• 报错：任务报错。

各异常项及其可选处理策略如下（详见 异常处理策略配置）：

创建完成

点击提交按钮，完成创建 MongoDB 到 TDengine 的数据同步任务，回到数据源列表页面可查看任务执行情况。任务提交后，可在任务列表页面对任务进行启动、停止、查看、删除、复制等操作，并可查看写入记录条数、流量等运行指标。

任务断点恢复

从 零代码数据写入总览 可知，MongoDB 数据源支持断点恢复：taosX 会持久化记录上次查询的时间戳，在任务重新启动后，从记录的时间戳开始继续查询，从而保证历史迁移或实时同步任务在重启后不丢数据、不重复消费。与之类似的机制也应用于 TDengine 查询、MySQL、PostgreSQL、Oracle、Microsoft SQL Server 等数据源。

对于任务运行中的异常，可结合任务列表的健康状态（Ready、Idle、Active、Pending、Busy、Bounce、SourceError、SinkError、Fatal）与活动日志快速定位问题，例如 MongoDB 源库异常时任务会进入 SourceError 状态并尝试重连数据源。

总结

通过 taosExplorer 的零代码数据写入能力，MongoDB 用户可以在一套图形界面中完成从数据源接入、连接与认证配置、查询模板设计、数据提取与映射，到异常处理与断点恢复的完整数据同步闭环，无需编写任何代码即可实现：

• 存量 MongoDB 数据到 TDengine 的历史迁移（设置结束时间，任务完成后自动停止）；
• 增量数据的持续实时同步（结束时间留空，配合查询间隔与延迟时长避免数据丢失）；
• 借助动态占位符（${Y}、${m}、${d}等）实现按库/按集合分片的数据接入；
• 借助查询模板占位符（${start_datetime}、${start_timestamp}等）与子表字段、排序条件解决迁移乱序问题。

相关配置细节可继续查阅 MongoDB 官方文档 及 零代码数据写入总览，并结合 高级选项 与 异常处理策略 对任务进行调优。

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