GQL es un lenguaje parecido a SQL que se utiliza para recuperar entidades de datos del almacén de datos escalable de App Engine. Aunque las funciones de GQL son distintas de las de un lenguaje de consulta de una base de datos relacional tradicional, la sintaxis de GQL es parecida a la de SQL.
La sintaxis de GQL se puede resumir del siguiente modo:
| 
SELECT * FROM <kind>
[WHERE <condition> [AND <condition> ...]]
[ORDER BY <property> [ASC | DESC] [, <property> [ASC | DESC] ...]]
[LIMIT [<offset>,]<count>]
[OFFSET <offset>]
<condition> := <property> {< | <= | > | >= | = | != } <value>
<condition> := <property> IN <list>
<condition> := ANCESTOR IS <entity or key>
Al igual que sucede con SQL, en las palabras clave de GQL no se distingue entre mayúsculas y minúsculas. En los nombres de propiedad y tipo se distingue entre mayúsculas y minúsculas.
Una consulta GQL devuelve cero o más entidades de datos del tipo solicitado como instancias de la clase de modelo del tipo. Un resultado siempre es una entidad completa, por lo que todas las consultas de GQL comienzan por SELECT * FROM seguido del nombre del tipo. (El especificador del campo parecido a SQL siempre es *. La sintaxis de SQL se conserva por familiaridad). Una consulta GQL no puede realizar una consulta "join" parecida a SQL.
La cláusula WHERE opcional limita el conjunto de resultados a aquellas entidades que cumplen una o varias condiciones. Cada condición compara una propiedad de la entidad con un valor mediante un operador de comparación. Si se definen varias condiciones con la palabra clave AND, las entidades deberán cumplir todas las condiciones para poder ser devueltas por la consulta. GQL no dispone de un operador OR. Sin embargo, dispone de un operador IN, que proporciona una función limitada del operador OR.
El operador IN compara el valor de una propiedad con cada elemento de una lista. El operador IN es equivalente a varias consultas =, una por cada valor, vinculadas mediante el operador OR. Se puede devolver como resultado de la consulta una entidad cuyo valor para la propiedad dada sea idéntico a cualquiera de los valores incluidos en la lista.
Nota: los operadores IN y != utilizan varias consultas en segundo plano. Por ejemplo, el operador IN ejecuta una consulta de almacén de datos subyacente independiente por cada elemento de la lista. A las entidades que se devuelven, que son el resultado del producto vectorial de todas las consultas de almacén de datos subyacentes, se les han eliminado los duplicados. Se permite un máximo de 30 consultas de almacén de datos para una única consulta GQL.
Una condición también puede probar con el operador ANCESTOR IS si una entidad tiene una determinada entidad como ancestro. El valor es una instancia de modelo o una clave de la entidad ancestro. Para obtener más información sobre los ancestros, consulta Claves y grupos de entidades.
La parte izquierda de una comparación siempre se compone de un nombre de propiedad. La parte derecha puede ser uno de los siguientes elementos (según corresponda para el tipo de datos de la propiedad):
str literal, como una cadena entre comillas simples. A los caracteres entre comillas simples de la cadena se les debe aplicar el formato de escape con ''. Por ejemplo: 'Joe''s Diner'42.7TRUE o FALSE.DATETIME(year, month, day, hour, minute, second)DATETIME('YYYY-MM-DD HH:MM:SS')DATE(year, month, day)DATE('YYYY-MM-DD')TIME(hour, minute, second)TIME('HH:MM:SS')KEY('encoded key')KEY(kind, name/ID [, kind, name/ID...])USER(email-address)
GEOPT(lat, long)
title = :1 A los parámetros de palabra clave se hace referencia por su nombre: title = :mytitleLos parámetros enlazados se pueden enlazar como argumentos posicionales o argumentos de palabra clave transmitidos al constructor de GqlQuery o a un método gql() de clase Model. Los tipos de datos de propiedad que no presentan una sintaxis literal de valor correspondiente se deben especificar mediante enlaces de parámetros, incluido el tipo de datos de lista. Los enlaces de parámetros se pueden volver a enlazar con valores nuevos durante la vida útil de la instancia GqlQuery (como, por ejemplo, para reutilizar una consulta de forma eficaz) mediante el método bind().
La cláusula ORDER BY opcional indica que los resultados se deben devolver ordenados por las propiedades determinadas, en orden ascendente (ASC) o descendente (DESC). Si la dirección no se especifica, adopta el valor predeterminado ASC. La cláusula ORDER BY puede especificar varios criterios de ordenación como, por ejemplo, una lista delimitada por comas, evaluada de izquierda a derecha.
Una cláusula LIMIT opcional hace que la consulta deje de mostrar resultados después de las primeras entidades count. La cláusula LIMIT también puede incluir una desviación (offset), que omite esa elevada cantidad de resultados y permite encontrar el primer resultado que se va a devolver. Una cláusula OFFSET opcional puede especificar una desviación (offset) si no existe ninguna cláusula LIMIT.
Nota: una cláusula LIMIT presenta un valor máximo de 1.000. Si se especifica un límite superior al máximo, se utilizará el valor máximo. Este mismo valor máximo se aplica al método fetch() de la clase GqlQuery.
Nota: al igual que sucede con el parámetro offset del método fetch(), una cláusula OFFSET en una cadena de consulta GQL no reduce el número de entidades extraídas del almacén de datos. Solo afecta a los resultados que devuelve el método fetch(). Una consulta con una desviación presenta unas características de rendimiento que se corresponden linealmente con el tamaño de la desviación.
Para obtener información sobre la ejecución de consultas de GQL, la vinculación de parámetros y el acceso a los resultados, consulta las secciones correspondientes a la clase GqlQuery y el método de clase Model.gql().