Query 对象表示 NDB 查询，这是对经过过滤和排序的实体列表的请求。
此页面包含参考文档。如需查看有关 NDB 查询的常规讨论，请参阅查询。
查询选项
许多查询方法都会使用一组标准附加选项，要么是以关键字参数的形式（如 keys_only=True），要么是以随 options=QueryOptions(...) 一起传递的 QueryOptions 对象的形式。
查询支持各种配置选项。
这些由 Query 方法的关键字参数指定：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| keys_only | bool | False | 所有操作均返回键，而非实体。 |
| projection | 属性（或字符串）的元组（或列表） | None
| 操作返回仅设置了指定属性的实体。
projection=[Article.title, Article.date] 或 projection=['title', 'date'] 提取仅设置了这两个字段的实体。（请参阅投影查询。）
|
| offset | int | 0 | 要跳过的查询结果数。 |
| limit | int | 无限制 | 返回的查询结果数上限。 |
| batch_size | int | 20 | 批量大小。 仅影响查询效率；较大批次大小使用的内存更多，但发起的 RPC 调用更少。 |
| prefetch_size | int | None | 替换返回的第一批的批次大小。 |
| produce_cursors | bool | False
| 通过查询生成游标（请参阅查询迭代器和 查询游标）。 |
| start_cursor | Cursor | None
| 搜索的起点（请参阅查询游标）。 |
| end_cursor | Cursor | None
| 搜索的终点（请参阅查询游标）。 |
| deadline | int | 根据 Context
| 替换 RPC 截止时间（如果在创建 Context 时未替换该截止时间，则系统默认为 5 秒） |
| read_policy | ndb.EVENTUAL_CONSISTENCY
| 读取政策。设置为 ndb.EVENTUAL_CONSISTENCY 也许可以更快地获取结果，无需等待 Datastore 将待更改项应用到所有返回的记录。 |
要使用一组特定选项运行查询，请将关键字参数传递到适用方法：
qry = Employee.query().filter(...).order(...) # Create a query for acct in qry.fetch(10, offset=20): # Skip the first 20 print acct
您可能偶尔需要保留一组查询选项，并用于各个位置。您既可以将它们保存在字典中，并将此字典传递给使用 **kwds 的方法，还可以创建 QueryOptions 对象并使用选项关键字参数传递它。以下两个示例是等效的：
qo = ndb.QueryOptions(keys_only=True, offset=20) results = qry.fetch(10, options=qo) results = qry.fetch(10, keys_only=True, offset=20)
构造函数
通常，应用会通过调用 Model.query() 创建 Query。但也可以调用 ndb.Query()。
参数
- 种类
- 可选 kind 字符串。通常是实体类的名称。
- 祖先实体
- 可选祖先键。
- filters
- 可选节点，代表过滤条件表达式树。
- orders
- 可选
datastore_query.Order对象。 - 应用
- 可选应用 ID。
- namespace
- 可选命名空间。如果未指定，将使用执行查询时的默认命名空间。
- projection
- 要投影的可选属性列表或元组。
- group_by
- 要作为分组依据的可选属性列表或元组。
- default_options
- 可选
QueryOptions对象，提供执行查询时要使用的默认查询选项。
实例方法
- filter(filter1, filter2, ...)
- 返回已应用附加过滤条件的新
Query。 使用查询中所述的过滤条件参数。qry.filter(filter1).filter(filter2)等效于qry.filter(filter1, filter2) - get(**q_options)
- 如果有，则返回第一个查询结果（否则返回
None）。这类似于调用q.fetch(1)并返回结果列表的第一项。参数
- **q_options
- 支持所有查询选项关键字参数。
- order(order1, order2, ...)
- 返回已应用其他排列顺序的新
Query。 使用一个或多个表示属性或“否定”属性的参数。 例如，要按年龄对用户进行排序，按名称“决定顺序”，您可以使用qry.order(-Account.birthday, Account.name) - bind(...values...)
- 此函数与使用参数绑定（
:1、:2等）或命名绑定（:foo、:bar等）的 GQL 查询一起使用。该函数会将传递的值绑定到相应参数。如要绑定参数，您可以调用类似
qry.bind("USA", 49)的内容。如要绑定命名参数，您可以调用类似qry.bind(region = "USA", threshold = 49)的内容。返回已绑定参数值的新
Query对象。 - count(limit=None, **q_options)
- 返回查询结果数，最多达到上限。
这返回的结果与
len(q.fetch(limit))相同，但更加高效。参数
- count_async(limit, **q_options)
- 异步计算查询结果数量，达到限值该方法会返回一个结果为数字的
Future。这是 count() 的异步版本。 - fetch(limit, **q_options)
- 提取查询结果列表，最多达到上限。
参数
- limit
- 要计算的结果数上限
- **q_options
- 支持所有查询选项关键字参数。
- fetch_async(limit, **q_options)
- 异步提取查询结果列表，最多达到上限。
返回一个结果为结果列表的
Future。这是 fetch() 的异步版本。 - fetch_page(page_size, **q_options)
- 提取结果“页面”。这是专用于对界面进行分页的方法。
参数
- page_size
- 最多可返回这么多结果。
- **q_options
- 支持所有查询选项关键字参数。
(results, cursor, more)：- results：查询结果列表
- cursor：指向“下一批”结果的查询游标。如果没有更多结果，则可能为
None。 - more
bool：表示这一批结果后是否（可能）有更多结果。如果为False，则没有其他结果；如果为True，则可能有更多结果。
要提取下一页结果，请使用
start_cursor=cursor将一个调用返回的游标传递到下一个调用。常见的用法是用cursor.urlsafe()将游标传递到客户端，并使用Cursor(urlsafe=string)在后续请求中重建该游标。 - fetch_page_async(page_size, **q_options)
- 异步提取结果“页面”。这是 fetch_page() 的异步版本。
- get_async(**q_options)
- 如果有，则以异步方式返回第一个查询结果（否则返回
None）。这是 get() 的一步版本。 - iter(**q_options)
- 通过查询构造并返回迭代器。
参数
- **q_options
- 支持所有查询选项关键字参数。
返回 QueryIterator 对象。
- map(callback, pass_batch_into_callback=None, merge_future=None, **q_options)
- 将回调函数或 tasklet 映射到查询结果。也就是说，将该函数（或 tasklet）应用到查询结果中的每个实体。
参数
- callback
- 要应用到每个结果的函数或 tasklet。
- pass_batch_into_callback
- 如果为
True，则使用批处理信息参数调用回调，如下所述。 - merge_future
- 可选的
Future子类；请参见下文。 - **q_options
- 支持所有查询选项关键字参数。
回调签名：通常以参数形式使用实体来调用回调。但是，如果指定了
keys_only=True，则使用键调用它。如果指定了pass_batch_into_callback=True，则使用以下三个参数调用回调：当前批次、批次中的索引，以及该索引下的实体或Key。回调可返回所需的任何内容。 如果回调为None，则默认这是极其简单的回调函数，并仅返回传入的实体或键。可选
merge_futuremerge_future是高级参数，可用于替换将回调函数结果合并为一个总的map()返回值的方法。默认情况下，系统会生成回调函数返回值列表。通过替换少量专用替代选项中的其中一项，您可以安排其他操作。请参阅tasklets.MultiFuture的源代码，了解merge_future对象必须实现的协议的默认实现和说明。同一模块的替代方案包括QueueFuture、SerialQueueFuture和ReducingFuture。返回所有回调结果列表。 （但请参阅上面的“可选
merge_future”。）它在查询运行完毕且所有回调均返回时返回。 - map_async(callback, pass_batch_into_callback=None, merge_future=None, **q_options)
- 将回调函数或 tasklet 异步映射到查询结果。 这是 map() 的异步版本。