MongoDB索引构建失败提示无效UTF-8，PyMongo迭代查询异常的排查与解决问询

针对你遇到的MongoDB索引构建失败（错误码28755：text contains invalid UTF-8）、PyMongo奇怪的解码错误等问题，我将分点解答你的疑问：

一、如何定位并移除导致索引失败的无效UTF-8文档 #

文本索引构建失败的核心原因是集合中存在字段包含无效UTF-8编码的内容，你可以通过以下方法精准定位这类文档：

1. 用聚合框架捕获UTF-8转换失败的文档 #

利用$tryCatch和$toString操作符，尝试将目标文本字段转为字符串，捕获转换失败的文档：

// 替换your_text_field为你要构建文本索引的字段名
db.articles.aggregate([
  {
    $addFields: {
      hasInvalidUTF8: {
        $tryCatch: [
          { $toString: "$your_text_field" },
          true // 转换失败时返回true
        ]
      }
    }
  },
  { $match: { hasInvalidUTF8: true } },
  { $project: { _id: 1, your_text_field: 1 } } // 仅返回ID和问题字段
])

找到问题文档后，你可以直接执行删除或修复操作（比如清理字段中的无效字节）。

2. 反向正则匹配无效UTF-8序列 #

如果你熟悉目标字段的合法格式，也可以用反向正则匹配不合法的UTF-8内容：

db.articles.find({
  $expr: {
    $regexMatch: {
      input: "$your_text_field",
      // 匹配所有合法UTF-8序列，反向匹配即返回不合法的文档
      regex: /[\x00-\x7F]|[\xC0-\xDF][\x80-\xBF]|[\xE0-\xEF][\x80-\xBF]{2}|[\xF0-\xF7][\x80-\xBF]{3}/,
      options: "v"
    }
  }
})

二、是否有与buildUUID相关的日志能获取问题文档ID？ #

MongoDB 4.4默认日志级别不会记录索引构建失败时的具体问题文档ID，但你可以临时调整日志级别来获取更多细节：

1. 执行命令调整索引构建模块的日志 verbosity：

db.adminCommand({
  setParameter: 1,
  "systemLog.component.storage.indexBuilds.verbosity": 2
})

2. 重新尝试构建索引，此时查看MongoDB日志，大概率会输出包含问题文档_id的详细信息。
3. 排查完成后记得调回默认级别（verbosity: 0），避免日志量过大影响性能。

三、是否存在Mongo命令直接检测无效UTF-8文档？ #

除了上述方法，你还可以用validate命令检查集合完整性，它能检测BSON结构损坏及UTF-8无效的内容：

db.runCommand({ validate: "articles", full: true })

如果输出中包含invalid UTF-8相关条目，也能辅助定位问题文档。

四、该异常是否是PyMongo驱动的bug？ #

从你描述的现象来看，大概率是PyMongo驱动的bug，理由如下：

• 直接通过_id查询文档正常，Mongo Shell迭代无异常，说明文档本身的BSON结构是合法的。
• 无限制迭代时报错位置随skip值变化，添加limit()后错误消失，符合驱动在处理大结果集的cursor批次时的解码逻辑问题（比如缓冲区残留数据、批次解码异常）。

建议你尝试以下解决方案：

1. 升级PyMongo到与MongoDB 4.4兼容的最新版本（比如3.12.x或更高），很多旧版本的cursor解码bug已经被修复。
2. 手动设置cursor的批次大小，缩小单次获取的数据量：

it_cursor = col.find().skip(skip).batch_size(100)

通过这种方式可能避开触发bug的场景。

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