仅知PartitionKey时如何读取Azure Cosmos DB文档？

常规读取方式 #

读取Azure Cosmos DB文档的常规方式有两种：

• Id查询：通过文档唯一Id读取单个文档
• Id + PartitionKey查询：同时指定Id和分区键读取，这是性能最优的单文档读取方式

问题场景 #

当仅拥有PartitionKey而不知道文档Id时，该如何读取对应的数据？

示例代码（原问题中的尝试） #

以下是原问题中尝试仅用PartitionKey读取文档的代码：

using Microsoft.Azure.Cosmos;
        
public class CosmosDbService : ICosmosDbService
{
    private Container _container;
    
    public CosmosDbService(
            CosmosClient cosmosDbClient,
            string databaseName,
            string containerName)
    {
        _container = cosmosDbClient.GetContainer(databaseName, containerName);
    }
    
    public async Task<Error> GetItemAsync(string partitionKey)
    {
        // 仅通过PartitionKey读取 - 无法生效
        var response = await _container.ReadItemAsync<Error>(partitionKey, new PartitionKey(partitionKey));
        return response.Resource;

        // 以下代码生效：传入了CosmosDB自动生成的文档Id
        var id = "2e4e5727-86ff-4c67-84a6-184b4716d744";
        var response = await _container.ReadItemAsync<Error>(id, new PartitionKey(partitionKey));
        return response.Resource;
    }
}

解答 #

ReadItemAsync的设计目标是读取单个已知Id的特定文档，因此必须同时传入Id和PartitionKey，仅传PartitionKey无法生效。

要实现仅通过PartitionKey读取对应文档，需要使用查询API，以下是两种常用实现方式：

方式1：SQL查询 #

public async Task<List<Error>> GetItemsByPartitionKeyAsync(string partitionKey)
{
    // 构造SQL查询，指定分区键匹配条件
    var queryDefinition = new QueryDefinition("SELECT * FROM c WHERE c.partitionKey = @pk")
        .WithParameter("@pk", partitionKey);

    // 指定查询仅针对目标分区，避免跨分区查询（提升性能、降低成本）
    var queryOptions = new QueryRequestOptions { PartitionKey = new PartitionKey(partitionKey) };

    var queryIterator = _container.GetItemQueryIterator<Error>(queryDefinition, requestOptions: queryOptions);
    
    var results = new List<Error>();
    while (queryIterator.HasMoreResults)
    {
        var response = await queryIterator.ReadNextAsync();
        results.AddRange(response.Resource);
    }
    
    return results;
}

方式2：LINQ查询 #

如果项目中更倾向于使用LINQ语法，也可以这样实现：

public async Task<List<Error>> GetItemsByPartitionKeyLinqAsync(string partitionKey)
{
    // 构造LINQ查询，筛选匹配分区键的文档
    var queryable = _container.GetItemLinqQueryable<Error>()
        .Where(error => error.PartitionKey == partitionKey); // 假设Error类包含PartitionKey属性

    var queryIterator = queryable.ToFeedIterator();
    
    var results = new List<Error>();
    while (queryIterator.HasMoreResults)
    {
        var response = await queryIterator.ReadNextAsync();
        results.AddRange(response.Resource);
    }
    
    return results;
}

关键说明 #

• 必须指定QueryRequestOptions.PartitionKey（LINQ方式会自动推断），确保查询仅在目标分区内执行，避免不必要的跨分区查询
• 如果目标PartitionKey下仅存在单个文档，可直接从返回的列表中取第一个元素
• 不要使用ReadItemAsync实现此场景，它的定位是单文档精准读取，而非分区内批量查询

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