Azure Cosmos DB Bulk Executor返回导入数与实际不一致问题咨询

Q1：是导入异常还是返回值统计不准确？ #

从你描述的现象来看，大概率是BulkExecutor的返回值统计逻辑存在遗漏，而非导入过程异常。核心依据是最终Cosmos集合中的文档数完全符合预期（1237278个），说明所有文档都成功完成了写入操作。

出现返回值NumberOfDocumentsImported偏少的情况，通常和BulkExecutor的重试机制相关：

• 当导入过程中遇到Cosmos DB的限流（429错误）时，BulkExecutor会自动重试整个批次的请求（这也是我们将客户端重试设为0的原因，把控制权完全交给它）。
• 部分场景下，重试成功的文档数可能没有被正确累加到返回的统计值中，导致最终返回的成功数比实际写入数少。
• 另外，BulkExecutor在处理批量请求的响应时，若遇到部分成功的批次（比如某个批次里少数文档写入失败，但重试后成功），也可能出现统计值的短暂偏差，但最终所有文档都能写入成功。

Q2：如何获取可能有问题的文档日志？ #

虽然BulkExecutor本身没有内置的详细文档级日志功能，但可以通过以下几种方式排查：

1. 启用Cosmos DB的诊断日志
   在Azure门户中，找到你的Cosmos DB账号，开启诊断设置，选择记录DataPlaneRequests类别。这些日志会包含所有写入请求的详细信息：请求状态码、耗时、分区键、文档id等。你可以通过筛选状态码为429的请求，查看哪些批次被重试，甚至定位到具体的文档。

2. 拆分批量导入并自定义统计
   把120万+文档拆分成更小的批次（比如每1000个文档为一批），逐个调用BulkImportAsync，并记录每一批的返回结果。如果某一批的返回成功数和发送数不一致，就可以锁定这一批文档，进一步检查它们的格式、id或分区键是否存在异常。示例代码思路：

   var batchSize = 1000;
   for (int i = 0; i < documents.Count; i += batchSize)
   {
       var batch = documents.Skip(i).Take(batchSize).ToList();
       var response = await bulkExecutor.BulkImportAsync(batch, true);
       // 记录当前批次的导入结果，包括批次起始索引、成功数等
       Console.WriteLine($"Batch {i/batchSize}: Sent {batch.Count}, Imported {response.NumberOfDocumentsImported}");
       if (response.NumberOfDocumentsImported != batch.Count)
       {
           // 保存该批次文档到本地文件，后续排查
           File.WriteAllText($"Batch_{i/batchSize}_check.json", JsonConvert.SerializeObject(batch));
       }
   }
   

3. 启用Cosmos客户端的详细日志
   可以通过配置ILogger来捕获Cosmos客户端的所有请求日志，包括BulkExecutor发起的请求。比如在.NET Core中，在appsettings.json里添加日志配置：

   "Logging": {
       "LogLevel": {
           "Microsoft.Azure.Cosmos": "Debug",
           "Microsoft.Azure.CosmosDB.BulkExecutor": "Debug"
       }
   }
   

   这些日志会包含每个请求的详细信息，帮助你追踪哪些文档被重试或出现异常。

另外补充一点：虽然BadInputDocuments始终为null，但也可以快速检查是否存在文档格式不符合要求的情况（比如id字段为空、分区键缺失），不过从最终文档数正确来看，这种可能性很低。

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