La clase GqlQuery es una interfaz de consulta de almacén de datos que utiliza el lenguaje de consulta GQL de App Engine.
La clase GqlQuery se proporciona a través del módulo google.appengine.ext.db.
GQL es un lenguaje de consulta parecido a SQL que se puede utilizar para realizar consultas al almacén de datos de App Engine. Para obtener información completa sobre la sintaxis y las funciones del lenguaje GQL, consulta la referencia de GQL.
El constructor de GqlQuery utiliza como argumento una instrucción de GQL completa que comienza por SELECT * FROM model-name. Los valores contenidos en las cláusulas WHERE pueden ser valores literales de número o cadena o valores de enlaces de parámetros. Los parámetros enlazados se pueden vincular inicialmente al constructor con argumentos posicionales o de palabra clave.
| 
query = GqlQuery("SELECT * FROM Song WHERE composer = 'Lennon, John'")
query = GqlQuery("SELECT * FROM Song WHERE composer = :1", "Lennon, John")
query = GqlQuery("SELECT * FROM Song WHERE composer = :composer", composer="Lennon, John")
Para comodidad del usuario, las clases Model y Expando disponen de un método gql() que devuelve una instancia de GqlQuery. Este método utiliza una cadena de consulta de lenguaje GQL sin el nombre de modelo (SELECT * FROM model-name), que está implícito.
query = Song.gql("WHERE composer = 'Lennon, John'")
Al igual que ocurre con la clase Query, la aplicación ejecuta la consulta y accede a los resultados ejecutando el método fetch() o tratando el objeto GqlQuery como un elemento iterable. Para obtener más información, consulta la documentación de la clase Query.
Existe una diferencia en el modo de acceso de Query y GqlQuery a los resultados: si la consulta de lenguaje GQL incluye una cláusula LIMIT o una cláusula OFFSET, los resultados se recuperan al igual que con el método fetch() equivalente, aunque la interfaz del iterador se utilice para acceder a los resultados. Cuando se utiliza como elemento iterable una clase GqlQuery cuyo lenguaje GQL contiene LIMIT o OFFSET, se realiza una llamada al almacén de datos para extraer todos los resultados y el iterador devuelve todos los resultados de la memoria.
for song in q: print song.title
Consulta también la clase de consulta Query, que utiliza objetos y métodos para preparar consultas en lugar del lenguaje GQL.
Nota: los algoritmos y las estructuras de datos basados en índices que ejecutan las consultas del almacén de datos no admiten determinados tipos de consultas. Para obtener más información, ve a Consultas e índices: Restricciones aplicadas a las consultas.
El constructor de la clase GqlQuery se define del siguiente modo:
Un objeto de consulta que utiliza el lenguaje GQL de consulta de App Engine.
Argumentos:
SELECT * FROM model-name.Una instancia GqlQuery incluye los siguientes métodos:
Vuelve a enlazar parámetros para la consulta. La nueva consulta se ejecuta la primera vez que se accede a los resultados una vez que los parámetros se han vuelto a enlazar.
Reutilizar el objeto GqlQuery con parámetros nuevos resulta más rápido que crear un objeto GqlQuery nuevo, ya que para volver a enlazar los parámetros no es necesario volver a procesar la cadena de consulta.
Argumentos:
Ejecuta la consulta y, a continuación, devuelve el primer resultado, o None si la consulta no devolvió ningún resultado.
El argumento get() implica un "límite" de 1 y sobrescribe la cláusula LIMIT de la consulta de GQL, si hay alguna. Se extrae como máximo un resultado del almacén de datos.
Ejecuta la consulta y, a continuación, devuelve los resultados.
Los argumentos limit y offset controlan el número de resultados que se extraen del almacén de datos y el número de resultados que devuelve el método fetch():
Nota: el método fetch() devuelve un máximo de 1.000 resultados. Si hay más de 1.000 entidades que coinciden con la consulta y no se ha especificado ningún límite o se utiliza un límite superior a 1.000, el método fetch() sólo devolverá los primeros 1.000 resultados.
Argumentos:
El número de resultados que se van a devolver. Este valor sobrescribe la cláusula LIMIT en la instrucción de consulta de GQL, si hay alguna. Es posible que se devuelva un número de resultados inferior al límite si no hay suficientes resultados disponibles que cumplan los criterios.
El argumento limit es obligatorio. Para obtener todos los resultados de una consulta cuando no se conoce el número de resultados, utiliza el objeto GqlQuery como elemento iterable en lugar de utilizar el método fetch().
OFFSET (o la desviación en una cláusula LIMIT) en la instrucción de consulta de GQL, si hay alguna.El valor de retorno es una lista de instancias de modelo, posiblemente una lista vacía.
Devuelve el número de resultados que extrae esta consulta.
El método count() resulta algo más rápido que la recuperación de todos los datos por un factor constante, pero el tiempo de ejecución sigue creciendo con el tamaño del conjunto de resultados. Se recomienda utilizar sólo el método count() en los casos en que se espere un recuento reducido o especificar un límite.
Nota: el método count() devuelve un valor máximo de 1.000. Si el número real de entidades que coinciden con los criterios de consulta supera el máximo, el método count() devuelve 1.000.
Argumentos:
El número máximo de resultados que se van a contar. Este valor sobrescribe la cláusula LIMIT en la instrucción de consulta de GQL, si hay alguna.