NDB Query 类

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 搜索的终点（请参阅查询游标）。
deadlineint 根据 Context 替换 RPC 截止时间（如果在创建 Context 时未替换该截止时间，则系统默认为 5 秒）
read_policyndb.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)) 相同，但更加高效。

参数

limit
要计算的结果数上限
**q_options
支持所有查询选项关键字参数和上下文选项。
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_future merge_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() 的异步版本。