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, 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
对象必须实现的协议的默认实现和说明。同一模块的替代方案包括QueueFuture
、SerialQueueFuture
和ReducingFuture
。返回所有回调结果列表。 (但请参阅上面的“可选
merge_future
”。)它在查询运行完毕且所有回调均返回时返回。 - map_async(callback, pass_batch_into_callback=None, merge_future=None, **q_options)
- 将回调函数或 tasklet 异步映射到查询结果。 这是 map() 的异步版本。