Google Code offered in: English - Español - 日本語 - 한국어 - Português - Pусский - 中文(简体) - 中文(繁體)
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.
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.
The constructor of the GqlQuery class is defined as follows:
A query object using the App Engine query language GQL.
Arguments:
A GqlQuery instance has the following methods:
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:
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:
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.
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.
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:
Note: The query has performance characteristics that correspond linearly with the offset amount plus the limit amount.
Arguments:
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
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.
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:
The return value is a list of model instances, possibly an empty list.
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: