Azure CosmosDB Python查询问题：复杂查询返回空集，全量拉取存隐患

你遇到的这个情况在Cosmos DB的使用中挺常见的，大多是几个关键细节没踩对，咱们一步步拆解解决：

1. 先搞定分区键与跨分区查询设置 #

如果你的Cosmos DB集合是分区集合（现在默认创建的都是这类），没开启跨分区查询的话，查询只会在单个分区内执行——要是你的数据分散在不同分区，自然会返回空集。

在Python代码里，一定要在查询选项里加上enable_cross_partition_query=True，给你个示例：

from azure.cosmos import CosmosClient

# 初始化客户端
client = CosmosClient("<你的Cosmos DB端点>", "<你的密钥>")
database = client.get_database_client("<数据库名>")
container = database.get_container_client("<容器名>")

# 示例：查询未同步的记录（开启跨分区）
query = "SELECT * FROM c WHERE c.isSynced = false"
items = list(container.query_items(
    query=query,
    enable_cross_partition_query=True,  # 这行是关键！
    max_item_count=100  # 不建议用-1全量拉，分批更稳妥
))

如果你明确知道分区键值，也可以直接指定分区查询，性能会更好：

items = list(container.query_items(
    query=query,
    partition_key="你的分区键值"
))

2. 排查查询语法的大小写与路径问题 #

Cosmos DB的查询是大小写敏感的！比如文档里字段是lastSyncTimestamp，你写成lastsynctimestamp绝对查不到。另外嵌套字段的路径要写对，比如文档里是{"metadata": {"syncStatus": "pending"}}，查询就得写c.metadata.syncStatus = "pending"，层级不能错。

3. 优化未同步记录的查询逻辑 #

要拉取未同步的记录，建议给文档加个专门的同步标记字段，比如lastSyncedAt（默认设为null）或者isSynced（布尔值），这样查询能精准筛选：

# 示例：筛选从未同步或上次同步时间之后的记录
query = """
SELECT * FROM c 
WHERE c.lastSyncedAt IS NULL 
OR c.lastSyncedAt < '2024-05-20T00:00:00Z'
"""
items = list(container.query_items(
    query=query,
    enable_cross_partition_query=True
))

4. 替代全量拉取的更优方案 #

你担心全量拉取会出问题，这里推荐用continuation token分页查询，分批获取数据，避免内存过载，也符合Cosmos DB的最佳实践：

continuation_token = None
all_items = []
while True:
    batch_items = list(container.query_items(
        query=query,
        enable_cross_partition_query=True,
        continuation_token=continuation_token,
        max_item_count=100  # 每次拉100条，可按需调整
    ))
    if not batch_items:
        break
    all_items.extend(batch_items)
    # 获取下一页的token
    continuation_token = container.client_connection.last_response_headers.get('x-ms-continuation')
    if not continuation_token:
        break

另外，如果是做长期的增量同步，Cosmos DB的变更Feed是更好的选择——它能实时捕获集合里新增、修改的文档，不用每次都全量扫表，适合你这种数据持续增长的场景，用Python SDK的ChangeFeedProcessor就能实现。

最后再检查几个小细节 #

• 确认查询没有语法错误，比如括号不匹配、字符串引号没闭合；
• 检查客户端的权限，确保有容器的读取权限；
• 如果自定义了索引策略，要确认查询的字段被包含在索引里（默认是全字段索引，但自定义后可能会遗漏）。

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