如何通过SQL API变更Azure Cosmos DB中文档或文档集的结构？

针对你提到的把StudentId字段重命名为StudentEmail这类结构变更需求，我整理了单个文档和批量文档集的具体操作方法——毕竟Cosmos DB里的"migration"特指数据迁入，咱们就叫文档结构更新/字段重命名就好：

一、单个文档的结构修改 #

如果只是修改某一个特定文档，最简单的方式是用SDK的ReplaceItemAsync或者UpsertItemAsync方法：

1. 先通过ReadItemAsync读取目标文档
2. 在内存中调整文档结构（比如把旧字段StudentId的值赋值给新字段StudentEmail，再删除旧字段）
3. 调用替换/更新方法写回数据库

举个C# SDK的示例代码：

// 初始化Cosmos客户端
var cosmosClient = new CosmosClient("your-connection-string");
var container = cosmosClient.GetContainer("your-db-name", "your-container-name");

// 读取目标文档
var documentId = "some-id";
var partitionKey = new PartitionKey("your-partition-key-value");
var studentDoc = await container.ReadItemAsync<dynamic>(documentId, partitionKey);

// 修改字段：迁移StudentId的值到StudentEmail，删除旧字段
studentDoc.Resource.StudentEmail = studentDoc.Resource.StudentId;
delete studentDoc.Resource.StudentId;

// 写回文档（用Replace确保精准覆盖，Upsert也适用）
await container.ReplaceItemAsync(studentDoc.Resource, documentId, partitionKey);

二、批量修改文档集 #

如果要修改符合条件的一批文档，有两种实用方案：

1. SDK批量查询+更新 #

这种方式适合中小规模的文档集，核心是分页查询+批量提交：

• 用SQL筛选出需要修改的文档（比如SELECT * FROM c WHERE c.StudentId IS NOT NULL）
• 分页遍历结果，逐个调整字段后批量提交更新，避免一次性消耗过多RU

示例代码片段：

// 构建查询，控制每页返回数量降低RU压力
var query = container.GetItemQueryIterator<dynamic>(
    "SELECT * FROM c WHERE c.StudentId IS NOT NULL",
    requestOptions: new QueryRequestOptions { MaxItemCount = 100 }
);

// 遍历分页结果并批量更新
while (query.HasMoreResults)
{
    var batch = container.CreateTransactionalBatch(partitionKey);
    var response = await query.ReadNextAsync();
    foreach (var doc in response)
    {
        doc.StudentEmail = doc.StudentId;
        delete doc.StudentId;
        batch.ReplaceItem(doc.id, doc);
    }
    // 提交当前批次的更新
    await batch.ExecuteAsync();
}

2. 服务器端存储过程（Stored Procedure） #

如果文档量很大，推荐用存储过程在Cosmos DB服务器端执行，减少网络往返开销。下面是一个批量重命名字段的存储过程示例：

function renameStudentIdField() {
    var collection = getContext().getCollection();
    var query = 'SELECT * FROM c WHERE c.StudentId IS NOT NULL';
    var continuationToken = null;

    // 递归处理分页文档
    function processBatch(docs) {
        if (docs.length === 0) return;
        var updatePromises = [];
        docs.forEach(function(doc) {
            doc.StudentEmail = doc.StudentId;
            delete doc.StudentId;
            updatePromises.push(collection.replaceDocument(doc._self, doc));
        });
        // 完成当前批次后继续下一页
        return Promise.all(updatePromises).then(function() {
            queryNextPage();
        });
    }

    function queryNextPage() {
        var requestOptions = { continuationToken: continuationToken };
        collection.queryDocuments(collection.getSelfLink(), query, requestOptions)
            .toArray(function(err, docs, responseOptions) {
                if (err) throw err;
                continuationToken = responseOptions.continuationToken;
                if (continuationToken) {
                    processBatch(docs);
                } else {
                    getContext().getResponse().setBody('所有文档更新完成');
                }
            });
    }

    queryNextPage();
}

你可以通过SDK或者Azure Portal把这个存储过程部署到目标容器，再调用执行即可。

关键注意事项 #

• 并发冲突处理：修改时尽量依赖SDK默认的ETag机制，避免覆盖其他客户端的实时修改
• RU消耗控制：批量操作要合理设置批次大小，避免一次性占用过多RU影响业务正常访问
• 数据验证：更新完成后，建议用SQL查询抽样验证文档结构是否符合预期
• 生产环境建议：先在测试环境验证逻辑，再分批次执行更新，降低业务风险

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