Cosmos DB: Subscriptions到UserSubscriptions迁移及结构转换实现咨询

首先明确两个容器的文档结构映射规则，这是所有迁移操作的核心依据：

• 复用源文档的原生id字段，不重新生成主键值
• 提取源文档distributionUserIds数组的元素，映射为目标文档的UUID字段（若单条源文档对应多个关联用户，可按需拆分生成多条目标文档）
• 目标文档的Type字段固定赋值为Accounts
• 将源文档的PayerNumber、AccountNumber按结构嵌套到Payers数组中：每个PayerNumber对应一个对象，同对象下的Accounts字段为AccountNumber组成的数组
• Cosmos DB自动生成的_rid/_self/_etag/_attachments/_ts属于系统内置字段，写入目标容器时会自动重新生成，无需手动迁移

可选实现路径 #

零代码内置工具迁移 #

两个容器位于同一数据库下，无需跨账户、跨网络传输，可直接使用Cosmos内置的数据迁移能力完成操作：

• 配置导出源容器Subscriptions文档时，通过内置的自定义映射规则实现上述字段转换逻辑，不需要手动批量修改原始文档
• 写入目标容器UserSubscriptions时，关闭系统字段强制写入开关，避免触发Cosmos的文档校验报错
• 针对distributionUserIds多元素的场景，可配置数组拆分规则，按关联用户数生成对应数量的目标文档
• 适用场景：结构转换逻辑简单，不需要复杂的多文档聚合、合并
• 优势：开发量为零，支持断点续传，迁移速度快

自定义轻量脚本迁移 #

如果内置工具无法适配复杂转换规则，可基于Cosmos DB SDK编写简单脚本完成迁移：

• 通过SDK对源容器做分页拉取，单批次拉取量控制在100-200条，避免触发请求单元限流
• 在内存层完成文档结构转换，额外适配业务自定义逻辑：比如多个源文档对应同一用户、同一Payer的场景，可按维度聚合将分散的账号合并到同一个Accounts数组中；同步源文档的isActive状态到目标文档的对应字段
• 转换完成后通过SDK批量写入接口写入目标容器，开启内置自动重试机制处理429类限流错误
• 适用场景：转换逻辑复杂，需要自定义校验、聚合规则
• 优势：转换灵活度完全可控，可在迁移过程中加入数据合法性校验

存量+增量的低停机迁移 #

如果业务正在运行，无法停服做全量迁移，可采用分段迁移的模式：

• 先执行一次性全量迁移，记录迁移完成时的最后一个文档_ts时间戳，作为增量同步的起点
• 开启Cosmos变更Feed监听，从记录的时间点开始实时捕获源容器的新增、更新、删除操作，执行相同的结构转换逻辑后同步到目标容器
• 定期对比源、目标容器的文档数、核心字段值，直到数据完全一致后再切流量到新容器
• 注意点：提前确认目标容器的分片键配置——如果UserSubscriptions的分片键为UUID，需确认该分片键的分布是否符合业务查询场景，避免出现分片热点

迁移校验必做项 #

• 对比两个容器的总文档数，排查漏迁移、重复迁移的问题
• 随机抽取10%的样本文档逐字段核对，重点校验嵌套Payers数组的内容准确性
• 检查目标容器的索引策略，确保覆盖UUID、PayerNumber等核心查询字段，避免迁移后查询性能下降
• 统计目标容器各分片的存储分布，确认没有出现单分片数据量过大的问题

内容的提问来源于stack exchange，提问作者Rakesh Kumar