# MongoDB Source 组件使用说明
# 组件说明
MongoDB 用于一次性或周期性全量同步数据。
# 配置项说明
| 配置名称 | 数据类型 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|---|
| 节点名称 | String | 是 | MongoDB | 当前创建的节点名称，由用户自定义且不可为空。命名可包含字母、数字、下划线。确保唯一性。 |
| 节点编码 | String | 是 | 自动生成 | 当前创建的节点编码，以此标识此组件，由用户自定义且不可为空。命名可包含字母、数字、下划线。确保唯一性。 |
| 选择数据源 | String | 是 | - | 从下拉选项中选择列出的当前项目已经关联的数据源。 |
| 选择库 | String | 是 | - | 从下拉列表中选择数据库。 |
| 集合名称 | String | 是 | - | MongoDB 中的集合（Collection）是一组文档的容器，类似于关系型数据库中的表。 |
| Schema | String | 是 | - | MongoDB的BSON和SeaTunnel数据结构映射。可以自动获取，也可以手动编写。 |
| 匹配查询 | String | 否 | 在MongoDB中，用于过滤文档以进行查询操作的匹配条件 | |
| 投影查询 | String | 否 | - | 在MongoDB中，投影查询是一种查询操作，用于选择性地返回文档中的字段。通过使用投影操作符，我们可以指定需要返回的字段，以及是否要排除特定的字段 |
| 分片键 | String | 否 | _id | 分片键（用于并行读取）。 |
| 分片大小 | Int | 否 | 64 | 每个分片（Split）的大小（字节）。 |
| 每批次获取文档数 | Int | 否 | 2048 | 每个批处理从服务器获取的文档数量。设置合适的批处理大小可以提高查询性能，避免一次获取大量数据带来的内存压力。 |
| 查询最长执行时间 | Int | 否 | 600 | 该参数是MongoDB的查询选项，用于限制查询操作的最大执行时间。maxTimeMin的取值以分钟为单位。如果查询的执行时间超过了设置的时间限制，MongoDB将终止操作并返回错误。 |
| 空闲游标不超时 | Boolean | 否 | 是 | MongoDB服务器通常在一段时间（10分钟）不活动后会对空闲游标进行超时处理，以防止内存过度使用。将此选项设置为true以防止这种情况发生。但是，如果应用程序处理当前批文档的时间超过30分钟，则会话被标记为过期并关闭。 |
| 字符串映射 | Boolean | 否 | 否 | 将整条文档映射为单个 String 字段。 |
| 可选参数 | 否 | - | 其他参数，用户可以根据需求进行配置。 |
# 数据类型映射
| MongoDB BSON类型 | SeaTunnel类型 | 说明 |
|---|---|---|
| ObjectId | STRING | 自动转为24位十六进制字符串 |
| String | STRING | |
| Boolean | BOOLEAN | |
| Binary | BINARY | |
| Int32 | INTEGER | |
| Int64 | BIGINT | |
| Double | DOUBLE | |
| Decimal128 | DECIMAL | 精度不超过decimal(34,18) |
| Date | DATE | |
| Timestamp | TIMESTAMP | |
| Object | ROW | 嵌套结构 |
| Array | ARRAY |
特殊类型（映射为STRING）：Symbol、RegularExpression、JavaScript、DbPointer 使用Extended JSON格式存储。
# 性能优化与最佳实践
| 场景 | 推荐配置 | 原理 |
|---|---|---|
| 大集合全量 | split-key=_id, split-size=32-64MB | 并行扫描，避免单线程瓶颈 |
| 网络延迟高 | fetch.size=512 | 减少单次传输数据量 |
| 内存受限 | fetch.size=1024, 减小split-size | 控制批处理压力 |
| 仅需部分字段 | match.projection | 大幅减少网络IO |
| 嵌套文档复杂 | flat.sync-string=true + 下游解析 | 避免深度Schema定义 |
并行度建议：execution.parallelism 设置为 MongoDB 分片数的 1.5 倍左右。
# 常见错误与解决方案
| 错误现象 | 可能原因 | 解决方案 |
|---|---|---|
| Caused by: com.mongodb.MongoCommandException: ... not authorized | 权限不足 | 创建专用role，授予changeStream权限 |
| Change Stream自动终止 | 长时间无变更，token过期 | 设置heartbeat.interval.ms，推荐30000 |
| 大文档同步OOM | Split大小超过文档大小 | 减小split-size，增加JVM内存 |
# FAQ
Q：MongoDB输入组件无法获取元信息；抛异常：Command failed with error 13 (Unauthorized): 'not authorized on admin to execute command {listDatabases: 1, nameOnly: true }'on server 192.168.16.80:27017. The full response is {"ok: 0.0errmsg"not authorized on admin to execute command { listDatabases: 1, nameOnly: true }code":13,"codeName":"Unauthorized"}'
A：MongoDB数据源配置的用户角色权限不够，没有读取数据库的权限。详见MongoDB官方手册：https://www.mongodb.com/zh-cn/docs/manual/reference/built-in-roles/ (opens new window)