GQL Reference | Firestore in Datastore mode | Google Cloud Documentation
Skip to main content Console English Deutsch Español – América Latina Français Português – Brasil 中文 – 简体 日本語 한국어 Sign in Firestore in Datastore mode Start free Home Documentation Databases Firestore in Datastore mode Reference GQL Reference Stay organized with collections Save and categorize content based on your preferences. With GQL, you can write SQL-like queries for Firestore in Datastore mode.
GQL maps roughly to SQL: you can think of a GQL kind as a SQL table, a GQL entity as a SQL row, and a GQL property as a SQL column. However, a SQL row-column lookup is limited to a single value, whereas in GQL a property can be a multiple value property. The following Cloud Client Libraries for Firestore in Datastore mode support GQL: C# Java PHP Ruby GQL Versions You need different versions of GQL depending on where you run queries.
There are two GQL references: GQL Reference, for the GQL grammar used in the v1 and v1beta3 versions of the Datastore API and in the Google Cloud console Datastore Viewer (use the reference on this page). GQL for the Python NDB and DB client libraries , for the GQL grammar used in the NDB and DB client libraries. Grammar The GQL grammar is summarized as follows: < aggregation_query > : = ( SELECT ( < aggregation > + , ) [ FROM < kind > ] [ WHERE < compound - condition > ] | AGGREGATE ( < aggregation > + , ) OVER "(" < query > ")" ) < aggregation > : = ( COUNT "(" "*" ")" | COUNT_UP_TO "(" < integer - literal > ")" | SUM "(" < property - name > ")" | AVG "(" < property - name > ")" ) [ AS < alias > ] < alias > : = < name > < query > : = SELECT ( "*" | < property - name > + , | DISTINCT < property - name > + , | DISTINCT ON "(" < property - name > + , ")" "*" | DISTINCT ON "(" < property - name > + , ")" < property - name > + , ) [ FROM < kind > ] [ WHERE < compound - condition > ] [ ORDER BY ( < property - name > [ ASC | DESC ] ) + , ] [ LIMIT ( < result - position > | FIRST "(" < result - position > , < result - position > ")" ) ] [ OFFSET < result - position > [ "+" < result - position > ] ] < compound - condition > := < condition > AND < compound - condition > | < condition > OR < compound - condition > | "(" < compound - condition > ")" | < condition > < condition > : = < property - name > IS NULL | < property - name > < forward - comparator > < value > | < value > < backward - comparator > < property - name > < forward - comparator > := < either - comparator > | CONTAINS | HAS ANCESTOR | IN | NOT IN < backward - comparator > := < either - comparator > | IN | HAS DESCENDANT < either - comparator > := = | < | < = | > | > = | != < result - position > := < binding - site > | < integer - literal > < value > : = < binding - site > | < synthetic - literal > | < string - literal > | < integer - literal > | < double - literal > | < boolean - literal > | < null - literal > < synthetic - literal > := KEY "(" [ "PROJECT" "(" < string - literal > ")" "," ] [ "NAMESPACE" "(" < string - literal > ")" "," ] < key - path - element > + , ")" | ARRAY "(" < value > + , ")" | BLOB "(" < string - literal > ")" | DATETIME "(" < string - literal > ")" < key - path - element > := < kind > "," ( < integer - literal > | < string - literal > ) < kind > : = < name > < property - name > := < name > + .
In the above grammar list, note that: The symbol +, after an expression indicates that it can be repeated, with repeated expressions separated by a comma. The boolean AND operator has higher precedence than the OR operator. For example, a clause like a OR b AND c parses to a OR (b AND c) , and parenthesis would need to be used to achieve (a OR b) AND c . The following are some examples that return entire entities: SELECT * FROM myKind WHERE myProp > = 100 AND myProp < 200 SELECT * FROM myKind LIMIT 50 OFFSET @startCursor SELECT * FROM myKind ORDER BY myProp DESC Every GQL query string always begins with SELECT <something> , where <something> is one of the following: * <property-list> , a comma delimited list of properties to be returned from the query. __key__ , which returns keys only.
Similar to SQL, GQL keywords are case insensitive. Kind and property names are case sensitive. A GQL query returns zero or more entity results of the requested kind, with each result consisting of an entire entity or some subset of the properties of the entity, or even just the entity key . For example, SELECT * FROM myKind SELECT __key__ FROM myKind SELECT title, year FROM Song WHERE composer = 'Lennon, John' A result list produced by SELECT * or SELECT __key__ never contains duplicates.
A result list produced by SELECT <property-list> may contain multiple results from one entity, typically when any of those properties are multiple value properties. You can also use fully-qualified property names, in the form of <kind>.<property> . This statement: SELECT Person.name FROM Person is identical to: SELECT name FROM Person If a property name begins with the name of its kind followed by a ".", you must fully qualify the property name in GQL.
For example, given a kind named Product that has a property named Product.Name , you can retrieve matching results using: SELECT Product.Product.Name FROM Product But this would not match any results: SELECT Product.Name FROM Product Only SELECT is supported by GQL, you must use a client library or the API for mutation operations. Clauses The following optional SELECT clauses are recognized: Clause Description DISTINCT Specifies that only completely unique results will be returned.
Normally used only with projection queries because non-projection queries return unique results. If you use DISTINCT in a projection query where more than one entity has the same values in the properties being projected, only the first result is returned. Note that a query string can use either DISTINCT or DISTINCT ON , but not both. DISTINCT ON Specifies that only the first result for each distinct combination of values for the specified properties will be returned.
Used only with projection queries . The properties specified in the DISTINCT ON clause must be a subset of the properties specified for the projection. DISTINCT ON allows you to specify that only part of the projection is required to be distinct. SELECT DISTINCT a, b, c is identical to SELECT DISTINCT ON (a, b, c) a, b, c Note that a query string can use either DISTINCT or DISTINCT ON , but not both. FROM Limits the result set to those entities of the given kind.
A query string without a FROM clause is called a kindless query and the only condition allowed in the WHERE clause is one that specifies a __key__ property. WHERE Limits 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 combined with the AND keyword, then an entity must meet all of the conditions to be returned by the query.
GQL does not have an OR operator. ORDER BY Causes results to be sorted by the specified properties. The ORDER BY clause can specify multiple sort orders as a comma-delimited list, evaluated from left to right. Specify ASC for ascending or DESC for descending order. Note that the order is applied to each property. If the direction is not specified, it defaults to ASC . If no ORDER BY clause is specified, the order of the results is undefined and may change over time.
LIMIT Limits query results to a count, to results preceding a cursor, or both. Often used to page through results of a query. If LIMIT has two <result-position> s, one must be a cursor and the other must be an integer. (Note that OFFSET and LIMIT are independent.) OFFSET Specifies offsets into the result set: either a cursor, or a count, or both. If OFFSET has two <result-position> s, the left one must be a cursor and the right one must be an integer.
Note that an OFFSET with an integer starts at the beginning or at the cursor, then discards the specified number of entities, and so you still i
The rest of this page is on the live site.