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_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(filter1filter2)
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, page_size)
提取结果“页面”。这是专用于对界面进行分页的方法。

参数

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 对象必须实现的协议的默认实现和说明。同一模块的替代方案包括QueueFutureSerialQueueFutureReducingFuture

返回所有回调结果列表。 (但请参阅上面的“可选merge_future”。)它在查询运行完毕且所有回调均返回时返回。

map_async(callback, pass_batch_into_callback=None, merge_future=None, **q_options)
将回调函数或 tasklet 异步映射到查询结果。 这是 map() 的异步版本。