The GqlQuery Class

The GqlQuery class is a datastore query interface that uses the App Engine query language GQL.

GqlQuery is provided by the google.appengine.ext.db module.

• Introduction
• GqlQuery()
• Instance methods:
  • bind()
  • get()
  • fetch()
  • count()

Introduction

GQL is a SQL-like query language suitable for querying the App Engine datastore. For a complete discussion of the GQL syntax and features, see the GQL Reference.

The GqlQuery constructor takes as an argument a complete GQL statement beginning with SELECT * FROM model-name. Values in WHERE clauses can be string or number literals, or can use parameter binding for values. Bound parameters can be bound initially using positional or keyword arguments to the constructor.

query = GqlQuery("SELECT * FROM Song WHERE composer = 'Lennon, John'")

query = GqlQuery("SELECT * FROM Song WHERE composer = :1", "Lennon, John")

query = GqlQuery("SELECT * FROM Song WHERE composer = :composer", composer="Lennon, John")

For convenience, Model and Expando classes have a gql() method that returns a GqlQuery instance. This method takes a GQL query string without the SELECT * FROM model-name, which is implied.

query = Song.gql("WHERE composer = 'Lennon, John'")

As with the Query class, the application executes the query and accesses results either by calling the fetch() method, or by treating the GqlQuery object as an iterable. See the Query documentation for more information.

There is one difference between how Query and GqlQuery access results: If the GQL query includes a LIMIT clause or an OFFSET clause, results are retrieved as with the equivalent fetch() method, even if the iterator interface is used to access the results. When a GqlQuery whose GQL contains LIMIT or OFFSET is used as an iterable, one call is made to the datastore to fetch all of the results, and the iterator returns each of the results from memory.

for song in q:
  print song.title

See also Query, a query class that uses objects and methods to prepare queries instead of GQL.

Note: The index-based data structures and algorithms that power datastore queries do not support some kinds of queries. See Queries and Indexes: Restrictions on Queries for more information.

Constructor

The constructor of the GqlQuery class is defined as follows:

class GqlQuery(query_string, *args, **kwds)

A query object using the App Engine query language GQL.

Arguments:

query_string

A complete GQL statement beginning with SELECT * FROM model-name.

*args

Positional parameter bindings.

**kwds

Keyword parameter bindings.

Instance Methods

A GqlQuery instance has the following methods:

bind(*args, **kwds)

Re-binds parameters for the query. The new query is executed the first time results are accessed after parameters have been re-bound.

Re-using the GqlQuery object with new parameters is faster than building a new GqlQuery object because re-binding does not require that the query string be parsed again.

Arguments:

*args

The new positional parameter bindings.

**kwds

The new keyword parameter bindings.

get()

Executes the query, then returns the first result, or None if the query returned no results.

get() implies a "limit" of 1, and overrides the LIMIT clause of the GQL query, if any. At most 1 result is fetched from the datastore.

fetch(limit, offset=0)

Executes the query, then returns the results.

The limit and offset arguments control how many results are fetched from the datastore, and how many are returned by the fetch() method:

• The datastore fetches offset + limit results to the application. The first offset results are not skipped by the datastore itself.
• The fetch() method skips the first offset results, then returns the rest (limit results).
• The query has performance characteristics that correspond linearly with the offset amount plus the limit.

Note: fetch() returns a maximum of 1000 results. If more than 1000 entities match the query, and either no limit is specified or a limit larger than 1000 is used, only the first 1000 results are returned by fetch().

Arguments:

limit

The number of results to return. This value overrides the LIMIT clause in the GQL query statement, if any. Fewer than limit results may be returned if not enough results are available that meet the criteria.

limit is a required argument. To get every result from a query when the number of results is unknown, use the GqlQuery object as an iterable instead of using the fetch() method.

offset

The number of results to skip. This value overrides the OFFSET clause (or the offset in a LIMIT clause) in the GQL query statement, if any.

The return value is a list of model instances, possibly an empty list.

count(limit)

Returns the number of results this query fetches.

count() is somewhat faster than retrieving all of the data by a constant factor, but the running time still grows with the size of the result set. It's best to only use count() in cases where the count is expected to be small, or specify a limit.

Note: count() returns a maximum of 1000. If the actual number of entities that match the query criteria exceeds the maximum, count() returns a count of 1000.

Arguments:

limit

The maximum number of results to count. This value overrides the LIMIT clause in the GQL query statement, if any.