English
Skip to page content Skip to main navigation

e.g. "templates" or "datastore"

# 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 __key__ 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.
  *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.