Query 类

Query 类是一个数据存储区查询接口，可以使用对象和方法来准备查询。

Query 由 google.appengine.ext.db 模块提供。

• 简介
• Query()
• 实例方法：
  • filter()
  • order()
  • ancestor()
  • get()
  • fetch()
  • count()

简介

应用程序可通过调用具有 Model 类（其实体为 Query 对象）的构造函数或调用该类的 all() 类方法来创建 Query 对象。

class Song(db.Model):
  title = db.StringProperty()
  composer = db.StringProperty()
  date = db.DateTimeProperty()

query = db.Query(Song)

query = Song.all()

如果未作修改，该对象表示对指定类型的所有实体的查询。方法调用会使用属性条件 (filter())、祖先条件 (ancestor()) 和排序 (order()) 自定义查询。为了方便起见，这些方法会返回 self，这样就可将它们串联成一个语句。

query.filter('title =', 'Imagine')
query.order('-date')
query.ancestor(key)

query.filter('title =', 'Imagine').order('-date').ancestor(key)

应用程序使用以下两种方法之一执行该查询：

• 通过调用 fetch() 的方法。此方法可执行对数据存储区的单次调用以抓取结果，结果不能超过指定数量。Query 对象不对结果进行缓存，因此，再次调用 fetch() 会重新执行该查询。

  results = query.fetch(limit=5)
  for song in results:
    print song.title
  

• 通过将 Query 对象视为可迭代对象的方法。迭代程序可以从数据存储区中小批量地检索结果，从而允许应用程序停止迭代结果，避免抓取超出所需数量的结果。当检索出与该查询相匹配的所有结果时，迭代会停止。正如调用 fetch() 一样，迭代程序接口不对结果进行缓存，因此，从 Query 对象中创建新迭代程序会重新执行该查询。

  for song in query:
    print song.title
  

另请参阅 GqlQuery，这是使用一种类似 SQL 查询语言的 Query 类。

注意：基于索引的数据结构以及支持数据存储区查询的算法不支持某些类型的查询。有关详细信息，请参阅查询和索引：对查询的限制。

构造函数

Query 类的构造函数的定义如下：

class Query(model_class)

使用对象和方法准备查询的数据存储区查询接口。

由构造函数返回的 Query 实例表示对该类型的所有实体的查询。实例方法 filter()、order() 和 ancestor() 将标准应用到该查询以对结果进行过滤或排序。

参数：

model_class

代表查询的数据存储区实体类型的 Model（或 Expando）类

实例方法

Query 类具有以下几种实例方法：

filter(property_operator, value)

将属性条件过滤器添加至该查询。该查询只会返回具备满足所有条件的属性的实体。

参数：

property_operator

包含属性名称和可选比较运算符的字符串。名称和运算符必须用空格隔开，如 age >。支持以下比较运算符：< <= = >= > != IN。如果运算符从字符串中省略（参数正是属性名称），则过滤条件使用 = 运算符。

value

比较过程中所用的位于表达式右侧的值。其类型应当为被比较属性的值数据类型。请参阅类型和 Property 类。

query.filter('height >', 42).filter('city = ', 'Seattle')

query.filter('user = ', users.get_current_user())

order(property)

为结果添加排序。结果将根据首先添加的顺序进行排列。

参数：

property

一个字符串，要为其排序的属性的名称。要将排列顺序指定为降序，请在名称前加一个连字符 (-)。不加连字符，排列顺序将为升序。

# Order by last name, alphabetical:
query.order('last_name')

# Order tallest to shortest:
query.order('-height')

ancestor(ancestor)

将祖先条件过滤器添加至该查询。该查询只会返回以指定实体作为祖先（在其路径中的任何位置）的那些实体。

参数：

ancestor

代表该祖先的 Model 实例或 Key 实例。

get()

执行该查询，然后返回第一个结果，如果该查询未返回任何结果，则返回 None。

get() 暗含“限制”为 1。最多从数据存储区中抓取 1 个结果。

fetch(limit, offset=0)

执行查询，然后返回结果。

limit 和 offset 参数控制从数据存储区抓取的结果数量，以及通过 fetch() 方法返回的结果数量：

• 数据存储区会为应用程序抓取 offset + limit 个结果到应用程序。数据存储区本身不会跳过第一个 offset 结果。
• fetch() 方法则会跳过前 offset 个结果，然后返回剩余结果（limit 个结果）。
• 该查询具有与 offset 加 limit 数量之和成线性对应关系的性能特征。

注意：fetch() 返回最多 1000 个结果。如果有超过 1000 个实体与查询相匹配，且并未指定任何限制或使用了大于 1000 的限制，则 fetch() 仅返回前 1000 个结果。

参数：

limit

要返回的结果的数量。如果满足条件的结果数量不足，则返回的结果可能要少于 limit 个。

limit 是必需的参数。要在结果数量未知时获取查询的每个结果，可将 Query 对象用作可迭代对象，而不要使用 fetch() 方法。

offset

要跳过的结果的数量。

返回值是一个 Model 实例列表，可能是一个空列表。

count(limit)

返回该查询抓取的结果的数量。

count() 比通过常量系数检索所有数据要快一些，但是运行时间仍随结果集大小而增加。如果预期的数量很少，或指定了一个 limit，那么，最好只使用 count()。

注意：count() 返回的最大值为 1000。如果与查询条件相匹配的实体的实际数量超出了最大值，count() 会只返回 1000 个结果。

参数：

limit

要计数的结果的最大数量。