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()`
  - `count()`
  - `cursor()`
  - `fetch()`
  - `get()`
  - `with_cursor()`

## 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 containing `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 query:
        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.
count(limit=1000, config=None)

  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.

  Arguments:

  limit

    The maximum number of results to count, with a default of 1,000. The default value does not override the `LIMIT` clause in the GQL query statement: If `limit` is not specified in `count()`, but the GQL does specify a limit, then `count()` counts up to the GQL limit.

    If `limit` is specified, then `count()` counts up to that limit.

    If `limit` is specified as `None`, then `count()` continues until it finishes counting or times out.

  config
    A configuration object for the API call.
cursor()

  Returns an encoded cursor that represents the location in the result set after the last result fetched. A future invocation of the same query can provide this cursor using with_cursor() to start fetching results from this location.

  You must fetch results (using either fetch() or the iterator interface) before you can get a cursor.

  The cursor is a base64-encoded string. It is safe to use in HTTP GET and POST parameters, and can also be stored in the datastore or memcache.

  Note: Not all queries are compatible with cursors. See Query Cursors for more information.

fetch(limit, offset=0, config=None)

  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.
  - The first offset results are skipped by the datastore and not sent to the application.
  - The fetch() method then returns the rest (limit results).

  Note: The query has performance characteristics that correspond linearly with the offset amount plus the limit amount.

  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.
  config
    A configuration object for the API call.

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

get(config=None)

  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.

  Argument:

  config
    A configuration object for the API call.

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

with_cursor(start_cursor, end_cursor=None)

  Tells the datastore to start returning results from the location associated with the given encoded start cursor. If present, stops returning results at the end cursor. An app gets the cursor for a location in a list of results by calling cursor() after fetching results.

  The query must be identical to the query that generated the cursor, including the kind, property filters, ancestor filters, and sort orders.

  The app must call this method before fetching any results (i.e. before executing the query).

  Arguments:

  start_cursor

    The base64-encoded cursor returned by the cursor() method in a previous invocation of the query. Indicates where to start the query.

  end_cursor

    The base64-encoded cursor returned by the cursor() method in a previous invocation of the query. Indicates where to end the query.