Python按文档ID数组查询Firebase集合：避警告与解报错

要解决这个警告+报错的问题，核心是针对文档ID的in查询，必须传入文档引用（DocumentReference）列表而非纯字符串ID列表，同时使用SDK推荐的filter关键字参数写法。

正确代码示例 #

先把字符串ID列表转换成对应集合的文档引用，再构建查询：

from google.cloud.firestore import FieldFilter, FieldPath

# 把字符串ID转为文档引用
doc_references = [firebase_client.collection('my_collection').document(doc_id) for doc_id in list_of_ids]

# 使用filter关键字参数构建查询
query = firebase_client.collection('my_collection').where(
    filter=FieldFilter(FieldPath.document_id(), 'in', doc_references)
).stream()

也可以用更简洁的Filter.in_语法：

from google.cloud.firestore import Filter, FieldPath

doc_references = [firebase_client.collection('my_collection').document(doc_id) for doc_id in list_of_ids]
query = firebase_client.collection('my_collection').where(
    filter=Filter.in_(FieldPath.document_id(), doc_references)
).stream()

报错原因解释 #

你之前的写法触发key filter value must be a Key错误，是因为Firestore针对文档ID（文档的唯一Key）的过滤查询，要求值必须是DocumentReference对象，而不是纯字符串格式的ID。旧的位置参数写法之所以能运行，是因为SDK内部自动做了字符串到文档引用的转换，但新的filter关键字参数API要求显式传入符合类型要求的值。

为什么旧写法有警告 #

Firebase Python SDK的新版本推荐使用filter关键字参数替代传统的field_path/op_string/value位置参数，目的是统一过滤条件的写法，尤其是在构建复杂组合过滤时更清晰。

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