Key-Value Map-Reduce SEO

GQL is a SQL-like language for retrieving entities or keys from the App Engine scalable datastore. While GQL’s features are different from those of a query language for a traditional relational database, the GQL syntax is similar to that of SQL.

The GQL syntax can be summarized as follows:

  SELECT [* | __key__] 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>

As with SQL, GQL keywords are case insensitive. Kind and property names are case sensitive.

A GQL query returns zero or more entities or Keys of the requested kind. Every GQL query always begins with either

or

, followed by the name of the kind. (A GQL query cannot perform a SQL-like “join” query.)

Tip:

queries are faster and cost less CPU than

queries.

The optional

clause filters the result set to those entities that meet one or more conditions. Each condition compares a property of the entity with a value using a comparison operator. If multiple conditions are given with the

keyword, then an entity must meet all of the conditions to be returned by the query. GQL does not have an

operator. However, it does have an

operator, which provides a limited form of

.

The

operator compares value of a property to each item in a list. The

operator is equivalent to many

queries, one for each value, that are ORed together. An entity whose value for the given property equals any of the values in the list can be returned for the query.

Note: The

and

operators use multiple queries behind the scenes. For example, the

operator executes a separate underlying datastore query for every item in the list. The entities returned are a result of the cross-product of all the underlying datastore queries and are de-duplicated. A maximum of 30 datastore queries are allowed for any single GQL query.

A condition can also test whether an entity has a given entity as an ancestor, using the

operator. The value is a model instance or Key for the ancestor entity. For more information on ancestors, see Keys and Entity Groups.

The left-hand side of a comparison is always a property name. The right-hand side can be one of the following (as appropriate for the property’s data type):

• a
  str

  literal, as a single-quoted string. Single-quote characters in the string must be escaped as

  ''

  . For example:

  'Joe''s Diner'
• an integer or floating point number literal. For example:
  42.7
• a Boolean literal, as
  TRUE

  or

  FALSE

  .

• the
  NULL

  literal, which represents the null value (

  None

  in Python).

• a datetime, date, or time literal, with either numeric values or a string representation, in the following forms:
  • DATETIME(<em>year</em>, <em>month</em>, <em>day</em>, <em>hour</em>, <em>minute</em>, <em>second</em>)
  • DATETIME('<em>YYYY-MM-DD HH:MM:SS</em>')
  • DATE(<em>year</em>, <em>month</em>, <em>day</em>)
  • DATE('<em>YYYY-MM-DD</em>')
  • TIME(<em>hour</em>, <em>minute</em>, <em>second</em>)
  • TIME('<em>HH:MM:SS</em>')
• an entity key literal, with either a string-encoded key or a complete path of kinds and key names/IDs:
  • KEY('<em>encoded key</em>')
  • KEY('<em>kind</em>', <em>'name'/ID</em> [, '<em>kind</em>', <em>'name'/ID</em>...])
• a User object literal, with the user’s email address:
  USER('<em>email-address</em>')
• a GeoPt literal, with the latitude and longitude as floating point values:
  GEOPT(<em>lat</em>, <em>long</em>)
• a bound parameter value. In the query string, positional parameters are referenced by number:
  title = :1

  Keyword parameters are referenced by name:

  title = :mytitle

Note: conditions of the form

(which are equivalent) check to see whether a null value is explicitly stored in the datastore for that property. This is not the same as checking to see if the entity lacks any value for the property! Datastore queries which refer to a property never return entities which don’t have some value for that property.

Bound parameters can be bound as positional arguments or keyword arguments passed to the GqlQuery constructor or a Model class’s gql() method. Property data types that do not have corresponding value literal syntax must be specified using parameter binding, including the list data type. Parameter bindings can be re-bound with new values during the lifetime of the GqlQuery instance (such as to efficiently reuse a query) using the bind() method.

The optional

clause indicates that results should be returned sorted by the given properties, in either ascending (

) or descending (

) order. If the direction is not specified, it defaults to

. The

clause can specify multiple sort orders as a comma-delimited list, evaluated from left to right.

An optional

clause causes the query to stop returning results after the first

entities. The

can also include an

to skip that many results to find the first result to return. An optional

clause can specify an

if no

clause is present.

Note: A

clause has a maximum of 1000. If a limit larger than the maximum is specified, the maximum is used. This same maximum applies to the fetch() method of the GqlQuery class.

Note: Like the

parameter for the fetch() method, an

in a GQL query string does not reduce the number of entities fetched from the datastore. It only affects which results are returned by the fetch() method. A query with an offset has performance characteristics that correspond linearly with the offset size.

For information on executing GQL queries, binding parameters, and accessing results, see the GqlQuery class, and the Model.gql() class method.