Cosmos查询OrderItems子集合时，Continuation Token与MaxItems的使用疑问

核心思路 #

要实现按OrderItems而非Order文档分页，关键是先将嵌套的OrderItems数组展开为独立条目，再对这些条目应用分页逻辑。Cosmos DB支持通过SQL的JOIN语法或Linq的SelectMany完成数组展开，之后MaxItemCount和续令牌（continuationToken）就会作用在展开后的OrderItems上。

方法一：使用SQL查询（推荐，直观可控） #

1. 编写展开OrderItems的SQL语句 #

通过JOIN oi IN o.OrderItems将每个Order的OrderItems拆分为单独行，再过滤目标agentId：

SELECT o.agentId, oi.OrderItemId, oi.ProductId, oi.Qty
FROM Orders o
JOIN oi IN o.OrderItems
WHERE o.agentId = @agentId

2. C#代码实现分页查询 #

先定义DTO类接收展开后的结果：

public class OrderItemDto
{
    public string AgentId { get; set; }
    public string OrderItemId { get; set; }
    public int ProductId { get; set; }
    public int Qty { get; set; }
}

再通过GetItemQueryIterator执行查询并处理分页：

// 参数说明：agentId为目标代理ID，continuationToken为客户端传入的续令牌，paginationNumber为每页返回的OrderItems数量
var queryDefinition = new QueryDefinition(
        @"SELECT o.agentId, oi.OrderItemId, oi.ProductId, oi.Qty
          FROM Orders o
          JOIN oi IN o.OrderItems
          WHERE o.agentId = @agentId")
    .WithParameter("@agentId", agentId);

var queryOptions = new QueryRequestOptions
{
    // 替换为容器实际分区键值，若分区键是agentId则直接传入agentId，提升查询效率
    PartitionKey = new PartitionKey("your-partition-key-value"),
    MaxItemCount = paginationNumber
};

var feedIterator = container.GetItemQueryIterator<OrderItemDto>(
    queryDefinition,
    continuationToken: continuationToken,
    requestOptions: queryOptions);

var orderItems = new List<OrderItemDto>();
FeedResponse<OrderItemDto> response;
do
{
    response = await feedIterator.ReadNextAsync();
    orderItems.AddRange(response.Resource);
    // 更新续令牌，返回给客户端用于下一页查询
    continuationToken = response.ContinuationToken;
} while (!string.IsNullOrEmpty(continuationToken));

// 返回结果和新的续令牌给客户端
return (orderItems, continuationToken);

方法二：使用Linq查询 #

通过SelectMany展开OrderItems数组并投影为DTO，再按标准流程处理分页：

// DTO定义同上
var queryable = container.GetItemLinqQueryable<Order>(
        continuationToken: continuationToken,
        requestOptions: new QueryRequestOptions
        {
            PartitionKey = new PartitionKey("your-partition-key-value"),
            MaxItemCount = paginationNumber
        })
    .Where(o => o.agentId == agentId)
    .SelectMany(o => o.OrderItems, (order, item) => new OrderItemDto
    {
        AgentId = order.agentId,
        OrderItemId = item.OrderItemId,
        ProductId = item.ProductId,
        Qty = item.Qty
    });

var feedIterator = queryable.ToFeedIterator();
var orderItems = new List<OrderItemDto>();
FeedResponse<OrderItemDto> response;
do
{
    response = await feedIterator.ReadNextAsync();
    orderItems.AddRange(response.Resource);
    continuationToken = response.ContinuationToken;
} while (!string.IsNullOrEmpty(continuationToken));

return (orderItems, continuationToken);

关键注意事项 #

• 分区键优化：如果容器分区键不是agentId，该查询会是跨分区查询，性能会下降。若业务允许，建议将分区键设置为agentId，实现单分区高效查询。
• 续令牌传递：每次查询后必须将response.ContinuationToken返回给客户端，下次请求时传入该令牌，才能从上次中断的位置继续获取OrderItems。
• 字段投影：只查询需要的字段，减少数据传输量，提升查询性能。

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