Aviso: En los próximos meses, reorganizaremos el sitio de documentación de App Engine para facilitar la búsqueda de contenido y alinearlo mejor con el resto de los productos de Google Cloud. El mismo contenido estará disponible, pero la navegación ahora coincidirá con el resto de los productos de Cloud.

Python 2 ya no es compatible con la comunidad. Recomendamos que migres las apps de Python 2 a Python 3.

La clase GqlQuery

Nota: Se recomienda enfáticamente a los desarrolladores que compilan aplicaciones nuevas que usen la biblioteca cliente de NDB, ya que tiene muchas ventajas en comparación con esta biblioteca cliente, como el almacenamiento en caché automático de entidades mediante la API de Memcache. Si por el momento usas la biblioteca cliente de DB anterior, lee la Guía de migración de DB a NDB.

La clase GqlQuery representa una consulta para recuperar entidades de App Engine Datastore mediante el lenguaje de búsqueda de App Engine similar a SQL, GQL. Para ver un análisis completo de la sintaxis y las funciones de GQL, consulta la Referencia de GQL, consulta también la clase Query relacionada, que usa objetos y métodos (en lugar de GQL) para preparar búsquedas.

GqlQuery se define en el módulo google.appengine.ext.db.

Nota: El mecanismo de consulta basado en índices admite un rango amplio de consultas y es apto para la mayoría de las aplicaciones. Sin embargo, no admite algunos tipos de consultas comunes en otras tecnologías de bases de datos. En particular, las uniones y consultas agregadas no son compatibles con el motor de consultas de Datastore. Consulta la página Consultas de Datastore para conocer sus limitaciones.

Introducción

Una aplicación crea un objeto de consulta GQL cuando llama directamente al constructor de GqlQuery o al método de clase gql() de la clase modelo de un grupo de similares de entidad. El constructor de GqlQuery toma como argumento una string de consulta, una declaración de GQL completa que comienza con SELECT ... FROM model-name. Los valores en las cláusulas WHERE pueden ser literales numéricos o de string, o pueden usar la vinculación de parámetros para los valores. Los parámetros se pueden vincular mediante argumentos posicionales o de palabras clave:

q = GqlQuery("SELECT * FROM Song WHERE composer = 'Lennon, John'")

q = GqlQuery("SELECT __key__ FROM Song WHERE composer = :1", "Lennon, John")

q = GqlQuery("SELECT * FROM Song WHERE composer = :composer", composer="Lennon, John")

Para mayor comodidad, las clases Model y Expando tienen un método de clase gql() que muestra una instancia GqlQuery. Este método usa una string de consulta GQL sin el prefijo SELECT ... FROM model-name, que está implícito:

q = Song.gql("WHERE composer = 'Lennon, John'")

La aplicación puede ejecutar la consulta y acceder a los resultados de cualquiera de las maneras siguientes:

Trata el objeto de consulta como un iterable para procesar las entidades que coinciden, una a la vez:
```
for song in q:
  print song.title
```
Esto llama de manera implícita al método run() de la consulta para generar las entidades que coinciden. Es entonces equivalente a
```
for song in q.run():
  print song.title
```
Puede establecer un límite en la cantidad de resultados por procesar con el argumento de palabra clave limit:
```
for song in q.run(limit=5):
  print song.title
```
Crear un nuevo iterador a partir del objeto de consulta reitera la misma consulta desde el principio, ya que su interfaz no almacena los resultados en caché.
Llama al método get() de la consulta para obtener la primera entidad que coincide en Datastore:
```
song = q.get()
print song.title
```
Llama al método fetch() de la consulta para obtener una lista de todas las entidades que coinciden hasta una cantidad específica de resultados:
```
results = q.fetch(limit=5)
for song in results:
  print song.title
```
Al igual que con run(), el objeto de consulta no almacena los resultados en caché, por lo que llamar a fetch() por segunda vez hace que se vuelva a enviar la misma consulta.

Nota: No necesitarás usar mucho este método; casi siempre es mejor usar run().

Constructor

El constructor para la clase GqlQuery se define de la manera siguiente:

class GqlQuery (query_string, *args, **kwds)

Crea una instancia de la clase GqlQuery para recuperar entidades de App Engine Datastore con el lenguaje de consulta de GQL.

Argumentos

query_string: String que contiene una declaración de GQL completa.
args: Valores de los parámetros posicionales.
kwds: Valores de los parámetros de palabras clave.

Métodos de instancia

Las instancias de la clase GqlQuery tienen los métodos siguientes:

bind (*args, **kwds)

Vuelve a vincular los valores de los parámetros de la consulta. La consulta modificada se ejecutará la primera vez que se acceda a los resultados después de volver a vincular sus parámetros.

Volver a vincular los parámetros a un objeto GqlQuery es más rápido que compilar un objeto GqlQuery nuevo, ya que no es necesario volver a analizar la string de consulta.

Argumentos

args: Valores de los parámetros posicionales nuevos.
kwds: Valores de los parámetros de palabras clave nuevos.

projection()

Muestra la tupla de propiedades en la proyección o None.

is_keys_only ()

Muestra un valor booleano que indica si la consulta es de solo claves.

run (read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, limit=None, batch_size=20, keys_only=False, projection=None, start_cursor=None, end_cursor=None)

Muestra un iterable para repetir en bucle los resultados de la consulta. Esto te permite especificar la operación de la consulta con la configuración de los parámetros y acceder a los resultados de manera iterativa.

Recupera y descarta la cantidad de resultados especificada por el argumento offset.
Recupera y muestra hasta la cantidad máxima de resultados especificada por el argumento limit.

El rendimiento del bucle se escala de forma lineal con la suma de offset + limit. Siempre debes configurar un valor explícito de limit si sabes cuántos resultados deseas recuperar.

Este método usa una recuperación previa asíncrona para mejorar el rendimiento. De manera predeterminada, recupera sus resultados desde el almacén de datos en lotes pequeños. Esto hace que la aplicación detenga la iteración y evite recuperar más resultados de los necesarios.

Sugerencia: Para recuperar todos los resultados disponibles cuando no conoces la cantidad, configura batch_size con un valor grande, como 1000.

Sugerencia: Si no necesitas cambiar los valores de argumento predeterminados, usa el objeto de consulta directamente como iterable para controlar el ciclo. Esto llama de manera implícita a run() con los argumentos predeterminados.

Argumentos

read_policy

La política de lectura que especifica el nivel deseado de coherencia de datos:

STRONG_CONSISTENCY: Garantiza los resultados más recientes, pero se limita a un solo grupo de entidades.
EVENTUAL_CONSISTENCY: Puede abarcar varios grupos de entidades, pero a veces puede mostrar resultados obsoletos. Por lo general, las consultas de coherencia eventual se ejecutan más rápido que las de coherencia sólida, pero no se garantiza.

Nota: Las consultas globales (no las principales) omiten este argumento.

deadline

El tiempo máximo en segundos que se esperará que Datastore muestre un resultado antes de anular con un error. Acepta un valor de número entero o punto flotante. No puedes configurarlo con un valor más alto que el predeterminado (60 segundos), pero puedes reducirlo para asegurarte de que una operación en particular falle rápidamente (por ejemplo, con el objetivo de mostrar una respuesta más rápida al usuario, intentar nuevamente la operación, probar con otra o agregarla a la lista de tareas en cola).

offset

Cantidad de resultados que se omiten antes de mostrar el primero.

limit

Es la cantidad máxima de resultados que se mostrarán. Si se omite este parámetro, se usará el valor especificado en la cláusula LIMIT de la string de consulta de GQL. Si se configura de manera explícita como None, se recuperarán los resultados disponibles.

batch_size

Cantidad de resultados que se intenta recuperar por lote. Si se configura limit, la configuración predeterminada será el límite especificado; de lo contrario, será 20.

keys_only

Si es true, muestra solo claves en lugar de entidades completas. Las consultas de solo claves son más rápidas y económicas que las que muestran entidades completas.

projection

Lista o tupla de nombres de propiedades que se mostrarán. Solo se mostrarán las entidades que posean las propiedades especificadas. Si no se especifican, se mostrarán las entidades completas según la configuración predeterminada. Las consultas de proyección son más rápidas y económicas que las que muestran entidades completas.

Nota: Especificar este parámetro puede cambiar los requisitos de índice de la consulta.

start_cursor

Posición del cursor en la que se inicia la consulta.

end_cursor

Posición del cursor en la que se finaliza la consulta.

get (read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, keys_only=False, projection=None, start_cursor=None, end_cursor=None)

Ejecuta la consulta y muestra el primer resultado, o None si no se encontraron resultados. Se recupera como máximo un resultado de Datastore; se omite si existe la cláusula LIMIT de la string de consulta de GQL.

Argumentos

read_policy

La política de lectura que especifica el nivel deseado de coherencia de datos:

STRONG_CONSISTENCY: Garantiza los resultados más recientes, pero se limita a un solo grupo de entidades.
EVENTUAL_CONSISTENCY: Puede abarcar varios grupos de entidades, pero a veces puede mostrar resultados obsoletos. Por lo general, las consultas de coherencia eventual se ejecutan más rápido que las de coherencia sólida, pero no se garantiza.

Nota: Las consultas globales (no las principales) omiten este argumento.

deadline

offset

Cantidad de resultados que se omiten antes de mostrar el primero.

keys_only

Si es true, muestra solo claves en lugar de entidades completas. Las consultas de solo claves son más rápidas y económicas que las que muestran entidades completas.

projection

Nota: Especificar este parámetro puede cambiar los requisitos de índice de la consulta.

start_cursor

Posición del cursor en la que se inicia la consulta.

end_cursor

Posición del cursor en la que se finaliza la consulta.

fetch (limit, read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, keys_only=False, projection=None, start_cursor=None, end_cursor=None)

Ejecuta la consulta y muestra una lista de resultados (posiblemente vacía):

Recupera y descarta la cantidad de resultados especificada por el argumento offset.
Recupera y muestra hasta la cantidad máxima de resultados especificada por el argumento limit.

El rendimiento del método se escala de manera lineal con la suma de offset + limit.

Nota: Este método es un wrapper delgado alrededor del método run(); es menos eficiente y consume más memoria que usar run() directamente. En pocas ocasiones deberás usar fetch(); se proporciona, sobre todo, por motivos de comodidad para casos en los que necesites recuperar una lista completa de resultados de consulta en la memoria.

Sugerencia: El método fetch() está diseñado para recuperar solo la cantidad de resultados que especifica el argumento limit. Para recuperar todos los resultados disponibles de una consulta cuando la cantidad es desconocida, usa run() con un tamaño de lote grande, como run(batch_size=1000), en lugar de fetch().

Argumentos

limit

Es la cantidad máxima de resultados que se mostrarán. Si se configura como None, se recuperarán los resultados disponibles.

read_policy

La política de lectura que especifica el nivel deseado de coherencia de datos:

STRONG_CONSISTENCY: Garantiza los resultados más recientes, pero se limita a un solo grupo de entidades.
EVENTUAL_CONSISTENCY: Puede abarcar varios grupos de entidades, pero a veces puede mostrar resultados obsoletos. Por lo general, las consultas de coherencia eventual se ejecutan más rápido que las de coherencia sólida, pero no se garantiza.

Nota: Las consultas globales (no las principales) omiten este argumento.

deadline

offset

Cantidad de resultados que se omiten antes de mostrar el primero.

keys_only

Si es true, muestra solo claves en lugar de entidades completas. Las consultas de solo claves son más rápidas y económicas que las que muestran entidades completas.

projection

Nota: Especificar este parámetro puede cambiar los requisitos de índice de la consulta.

start_cursor

Posición del cursor en la que se inicia la consulta.

end_cursor

Posición del cursor en la que se finaliza la consulta.

count (read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, limit=1000, start_cursor=None, end_cursor=None)

Muestra la cantidad de resultados que coinciden con la consulta. El uso de un factor constante hace que esto sea más rápido que con la recuperación de todos los resultados, pero el tiempo de ejecución se sigue escalando de manera lineal con la suma de offset + limit. A menos que se espere que la cantidad de resultados sea baja, es recomendable especificar un argumento limit. De lo contrario, el método continuará hasta que termine de contar o se agote el tiempo de espera.

Argumentos

read_policy

La política de lectura que especifica el nivel deseado de coherencia de datos:

STRONG_CONSISTENCY: Garantiza los resultados más recientes, pero se limita a un solo grupo de entidades.
EVENTUAL_CONSISTENCY: Puede abarcar varios grupos de entidades, pero a veces puede mostrar resultados obsoletos. Por lo general, las consultas de coherencia eventual se ejecutan más rápido que las de coherencia sólida, pero no se garantiza.

Nota: Las consultas globales (no las principales) omiten este argumento.

deadline

offset

Cantidad de resultados que se omiten antes de contar el primero.

limit

Cantidad máxima de resultados que se contarán.

Nota: Si este parámetro se especifica de manera explícita, anulará el valor establecido en la cláusula LIMIT de la string de consulta de GQL. Sin embargo, si el parámetro se omite, el valor predeterminado de 1000 no anulará la cláusula LIMIT de la consulta de GQL y se aplicará solo si no se especificó una cláusula LIMIT.

start_cursor

Posición del cursor en la que se inicia la consulta.

end_cursor

Posición del cursor en la que se finaliza la consulta.

index_list ()

Muestra una lista de índices usados por una consulta ejecutada, incluidos los índices principales, compuestos, de tipo y con una sola propiedad.

Precaución: Si invocas este método en una consulta que todavía no se ejecutó, se generará una excepción AssertionError.

Nota: El servidor de desarrollo no admite esta función totalmente. Cuando se usa con el servidor de desarrollo, el resultado es una lista vacía o una que contiene exactamente un índice compuesto.

Por ejemplo, el comando siguiente emite mucha información sobre el índice que una consulta usa:

# other imports ...
import webapp2
from google.appengine.api import users
from google.appengine.ext import db

class Greeting(db.Model):
  author = db.StringProperty()
  content = db.StringProperty(multiline=True)
  date = db.DateTimeProperty(auto_now_add=True)

class MainPage(webapp2.RequestHandler):
  def get(self):
    user = users.get_current_user()
    q = db.GqlQuery(Greeting)
    q.filter("author =", user.user_id())
    q.order("-date")
    q.fetch(100)
    index_list = q.index_list()
    for ix in index_list:
      self.response.out.write("Kind: %s" % ix.kind())
      self.response.out.write("<br />")
      self.response.out.write("Has ancestor? %s" % ix.has_ancestor())
      self.response.out.write("<br />")
      for name, direction in ix.properties():
        self.response.out.write("Property name: "+name)
        self.response.out.write("<br />")
        if direction == db.Index.DESCENDING:
          self.response.out.write("Sort direction: DESCENDING")
        else:
          self.response.out.write("Sort direction: ASCENDING")
        self.response.out.write("<br />")

Esto produce un resultado como el siguiente para cada índice:

Kind: Greeting
Has ancestor? False
Property name: author
Sort direction: ASCENDING
Property name: date
Sort direction: DESCENDING

cursor ()

Muestra una string de cursor con codificación base64 que denota la posición en el conjunto de resultados de la consulta después del último resultado recuperado. Es seguro usar la string de cursor en los parámetros HTTP GET y POST, y también se puede almacenar en el almacén de datos o en Memcache. Una invocación futura de la misma consulta puede proporcionar esta string a través del parámetro start_cursor o del método with_cursor() para reanudar los resultados recuperados desde esta posición.

Precaución: Si invocas este método en una consulta que todavía no se ejecutó, se generará una excepción AssertionError.

Nota: No todas las consultas son compatibles con los cursores. Consulta la página Consultas de Datastore para obtener más información.

with_cursor (start_cursor, end_cursor=None)

Especifica las posiciones de inicio y de fin (opcional) en el conjunto de resultados de una consulta del cual se pueden recuperar resultados. Las strings de cursor que denotan las posiciones de inicio y de fin se pueden obtener si llamas a cursor() después de una invocación previa de la consulta. La consulta actual debe ser idéntica a la invocación anterior, incluidos el tipo de entidad, los filtros de propiedades, los filtros principales y las órdenes de clasificación.

Argumentos

start_cursor: La string de cursor con codificación base64 especifica dónde iniciar la consulta.
end_cursor: La string de cursor con codificación base64 especifica dónde finalizar la consulta.