====== GQL 参考 ======


GQL 是一种类似于 SQL 的语言，用于从 App Engine 可扩展数据存储区检索数据实体。虽然 GQL 的功能与用于传统关系数据库的查询语言的功能不同，但 GQL 语法类似 SQL 的语法。

GQL 语法可以总结如下：
<code>
  SELECT * FROM <kind>
    [WHERE <condition> [AND <condition> ...]]
    [ORDER BY <property> [ASC | DESC] [, <property> [ASC | DESC] ...]]
    [LIMIT [<offset>,]<count>]
    [OFFSET <offset>]

  <condition> := <property> {< | <= | > | >= | = | != } <value>
  <condition> := <property> IN <list>
  <condition> := ANCESTOR IS <entity or key>
</code>

与使用 SQL 一样，GQL 关键字不区分大小写。类型和属性名称区分大小写。

GQL 查询返回零个或更多请求的类型的数据实体，如同类型的 Model 类实例。结果始终是完整的实体，所以每个 GQL 查询始终以 SELECT * FROM 开头，后面带有类型的名称。（类似于 SQL 的字段指定符始终是 *。保留了 SQL 语法便于用户熟悉。）GQL 查询无法执行类似 SQL 的“join”查询。

可选 WHERE 子句对结果集进行过滤以得出符合一个或多个条件的实体。每个条件都使用比较运算符将实体的属性与值进行比较。如果用 AND 关键字指定了多个条件，则实体必须符合所有条件才能由查询返回。GQL 没有 OR 运算符。但是，它具有 IN 运算符，该运算符可提供一种受限形式的 OR。

IN 运算符将属性的值与列表中的每一项进行比较。IN 运算符等同于许多 = 查询（每个值一个）一起进行 OR 运算。查询可以返回指定属性的值等于列表中的任何值的实体。

注意：IN 和 != 运算符在后台使用多个查询。例如，IN 运算符对于列表中的每一项都执行单独的基层数据存储区查询。返回的实体是所有基层数据存储区查询的交叉产物的结果，并且消除了重复项。对于任一 GQL 查询，最多允许 30 个数据存储区查询。

条件还可以使用 ANCESTOR IS 操作符测试实体是否采用指定的实体作为祖先。值为祖先实体的 Model 实例或 Key。有关祖先的详细信息，请参阅键和实体组。

属性名称始终位于比较的左侧。右侧可以是以下内容之一（对应于属性的数据类型）：

str 常量，形式为单引号括起的字符串。字符串中的单引号字符必须转义为 ''。例如：'Joe''s Diner'

整数或浮点数常量。例如：42.7

布尔常量，如 TRUE 或 FALSE。

日期时间、日期或时间字符串（数值或字符串表示），形式如下：
<code>
    DATETIME(year, month, day, hour, minute, second)
    DATETIME('YYYY-MM-DD HH:MM:SS')
    DATE(year, month, day)
    DATE('YYYY-MM-DD')
    TIME(hour, minute, second)
    TIME('HH:MM:SS')
</code>
实体键字符串，带有一个字符串编码键，或类型和键名/ID 的完整路径：
<code>
    KEY('encoded key')
    KEY(kind, name/ID [, kind, name/ID...])
</code>
用户对象字符串，带有用户电子邮件地址：
<code>
USER(email-address)
</code>
GeoPt 字符串，带有浮点值形式的纬度和经度：
<code>
GEOPT(lat, long)
</code>
绑定参数值。在查询字符串中，位置参数按数字引用：title = :1 关键字参数按名称引用：title = :mytitle


绑定参数可以绑定为传递到 GqlQuery 构造函数或 Model 类的 gql() 方法的位置参数或关键字参数。必须使用参数绑定来指定没有对应值常量语法的属性数据类型，包括列表数据类型。可以在 GqlQuery 实例的生命周期中使用 bind() 方法用新值重新绑定参数绑定（例如为了有效地重复使用查询）。

可选的 ORDER BY 子句指示应按照指定属性进行排序，以升序 (ASC) 或降序 (DESC) 返回结果。如果未指定方向，其默认为 ASC。ORDER BY 子句可以用逗号分隔列表的形式指定多个排序顺序，从左到右进行评估。

可选的 LIMIT 子句使查询在前 count 个实体后停止返回结果。LIMIT 还可以包括 offset 以跳过许多结果以便找到要返回的第一个结果。如果不使用 LIMIT 子句，可选的 OFFSET 子句可以指定 offset。

注意：LIMIT 子句最大为 1000。如果指定了大于最大值的限制，则将使用最大值。该最大值也适用于 GqlQuery 类的 fetch() 方法。

注意：与 fetch() 方法的 offset 参数类似，GQL 查询字符串中的 OFFSET 不会减少从数据存储区抓取的实体数。它仅影响 fetch() 方法返回哪些结果。具有偏移的查询具有与偏移大小成线性关系的执行特性。

有关执行 GQL 查询、绑定参数和访问结果的信息，请参阅 GqlQuery 类和 Model.gql() 类方法。