Python 2.7 ha llegado al final de su ciclo de vida y dejará de estar disponible el 31 de enero del 2026. Después de la retirada, no podrás desplegar aplicaciones de Python 2.7, aunque tu organización haya usado anteriormente una política de organización para volver a habilitar los despliegues de entornos de ejecución antiguos. Tus aplicaciones de Python 2.7 seguirán ejecutándose y recibiendo tráfico después de la fecha de retirada. Te recomendamos que migres a la versión compatible más reciente de Python.

Esta página se ha traducido con Cloud Translation API.

La clase GqlQuery

Nota: Se recomienda encarecidamente a los desarrolladores que creen aplicaciones nuevas que usen la biblioteca de cliente de NDB, que ofrece varias ventajas en comparación con esta biblioteca de cliente, como el almacenamiento automático en caché de entidades mediante la API Memcache. Si actualmente usas la biblioteca de cliente de DB anterior, consulta la guía de migración de DB a NDB.

La clase GqlQuery representa una consulta para obtener entidades del almacén de datos de App Engine mediante el lenguaje de consultas de App Engine similar a SQL, GQL. Para obtener información completa sobre la sintaxis y las funciones de GQL, consulta la referencia de GQL. También puedes consultar la clase relacionada Query, que usa objetos y métodos en lugar de GQL para preparar las consultas.

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

Nota: El mecanismo de consulta basado en índices admite una amplia gama de consultas y es adecuado para la mayoría de las aplicaciones. Sin embargo, no admite algunos tipos de consultas habituales en otras tecnologías de bases de datos. En concreto, las combinaciones y las consultas de agregación no se admiten en el motor de consultas de Datastore. Consulta la página Consultas de Datastore para ver las limitaciones de las consultas de Datastore.

Introducción

Una aplicación crea un objeto de consulta GQL llamando directamente al constructor GqlQuery o al método de clase gql() de la clase de modelo de un tipo de entidad. El constructor GqlQuery toma como argumento una cadena de consulta,una instrucción GQL completa que empieza por SELECT ... FROM model-name. Los valores de las cláusulas WHERE pueden ser literales numéricos o de cadena, o bien pueden usar la vinculación de parámetros para los valores. Los parámetros se pueden enlazar 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 devuelve una instancia de GqlQuery. Este método toma una cadena de consulta de GQL sin el prefijo SELECT ... FROM model-name, que se da por supuesto:

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

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

Trata el objeto de consulta como un objeto iterable para procesar las entidades coincidentes de una en una:
```
for song in q:
  print song.title
```
De esta forma, se llama implícitamente al método run() de la consulta para generar las entidades coincidentes. Por lo tanto, es equivalente a
```
for song in q.run():
  print song.title
```
Puedes definir un límite en el número de resultados que se procesarán con el argumento de palabra clave limit:
```
for song in q.run(limit=5):
  print song.title
```
La interfaz del iterador no almacena en caché los resultados, por lo que, al crear un nuevo iterador a partir del objeto de consulta, se vuelve a iterar la misma consulta desde el principio.
Llama al método get() de la consulta para obtener la primera entidad coincidente que se encuentre en Datastore:
```
song = q.get()
print song.title
```
Llama al método de la consulta fetch() para obtener una lista de todas las entidades coincidentes hasta un número de resultados especificado:
```
results = q.fetch(limit=5)
for song in results:
  print song.title
```
Al igual que con run(), el objeto de consulta no almacena en caché los resultados, por lo que, si se llama a fetch() una segunda vez, se vuelve a emitir la misma consulta.

Nota: Rara vez tendrás que usar este método. Casi siempre es mejor usar run() en su lugar.

Constructor

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

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

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

Argumentos

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

Métodos de instancia

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

bind (*args, **kwds)

Vuelve a enlazar 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 que se hayan vuelto a enlazar sus parámetros.

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

Argumentos

args: Nuevos valores de los parámetros posicionales.
kwds: Nuevos valores de parámetros de palabras clave.

projection ()

Devuelve la tupla de propiedades de la proyección o None.

is_keys_only ()

Devuelve un valor booleano que indica si la consulta es una consulta 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)

Devuelve un objeto iterable para recorrer los resultados de la consulta. Esto le permite especificar la operación de la consulta con los ajustes de los parámetros y acceder a los resultados de forma iterativa:

Obtiene y descarta el número de resultados especificado por el argumento offset.
Obtiene y devuelve hasta el número máximo de resultados especificado por el argumento limit.

Por lo tanto, el rendimiento del bucle se ajusta de forma lineal a la suma de offset + limit. Si sabes cuántos resultados quieres obtener, siempre debes definir un valor limit explícito.

Este método usa la prefetched asíncrona para mejorar el rendimiento. De forma predeterminada, obtiene los resultados de Datastore en pequeños lotes, lo que permite que la aplicación detenga la iteración y evite obtener más resultados de los necesarios.

Nota: Para obtener todos los resultados disponibles cuando se desconozca su número, asigna a batch_size un valor grande, como 1000.

Nota: Si no necesitas cambiar los valores de los argumentos predeterminados, puedes usar el objeto de consulta directamente como iterable para controlar el bucle. Esto llama implícitamente a run() con argumentos predeterminados.

Argumentos

read_policy

Lee la política que especifica el nivel de coherencia de datos que quieres:

STRONG_CONSISTENCY: Garantiza los resultados más recientes, pero solo se puede usar con un grupo de entidades.
EVENTUAL_CONSISTENCY: Puede abarcar varios grupos de entidades, pero puede devolver resultados obsoletos en ocasiones. Por lo general, las consultas de coherencia eventual se ejecutan más rápido que las de coherencia fuerte, pero no hay ninguna garantía.

Nota: Las consultas globales (no antecesoras) ignoran este argumento.

deadline

Tiempo máximo, en segundos, que debe esperar Datastore para devolver un resultado antes de cancelar la operación con un error. Acepta un número entero o un valor de punto flotante. No se puede definir un valor superior al predeterminado (60 segundos), pero se puede reducir para asegurarse de que una operación concreta falle rápidamente (por ejemplo, para devolver una respuesta más rápida al usuario, volver a intentar la operación, probar otra operación o añadir la operación a una cola de tareas).

offset

Número de resultados que se omitirán antes de devolver el primero.

limit

Número máximo de resultados que se devolverán. Si se omite este parámetro, se usará el valor especificado en la cláusula LIMIT de la cadena de consulta de GQL. Si se asigna explícitamente el valor None, se recuperarán todos los resultados disponibles.

batch_size

Número de resultados que se intentarán obtener por lote. Si se define limit, se aplicará el límite especificado. De lo contrario, se aplicará 20 de forma predeterminada.

keys_only

Si true, devuelve solo las claves en lugar de las entidades completas. Las consultas para obtener solo las claves son más rápidas y económicas que las que devuelven entidades completas.

proyección

Lista o tupla de nombres de propiedades que se van a devolver. Solo se devolverán las entidades que tengan las propiedades especificadas. Si no se especifica, se devuelven todas las entidades de forma predeterminada. Las consultas de proyección son más rápidas y económicas que las que devuelven entidades completas.

Nota: Si especifica este parámetro, es posible que cambien los requisitos de índice de la consulta.

start_cursor

Posición del cursor en la que se debe iniciar la consulta.

end_cursor

Posición del cursor en la que finalizar 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 devuelve el primer resultado o None si no se encuentra ningún resultado. Se recupera como máximo un resultado de Datastore. Se ignora la cláusula LIMIT de la cadena de consulta de GQL, si la hay.

Argumentos

read_policy

Lee la política que especifica el nivel de coherencia de datos que quieres:

STRONG_CONSISTENCY: Garantiza los resultados más recientes, pero solo se puede usar con un grupo de entidades.
EVENTUAL_CONSISTENCY: Puede abarcar varios grupos de entidades, pero puede devolver resultados obsoletos en ocasiones. Por lo general, las consultas de coherencia eventual se ejecutan más rápido que las de coherencia fuerte, pero no hay ninguna garantía.

Nota: Las consultas globales (no antecesoras) ignoran este argumento.

deadline

offset

Número de resultados que se omitirán antes de devolver el primero.

keys_only

Si true, devuelve solo las claves en lugar de las entidades completas. Las consultas para obtener solo las claves son más rápidas y económicas que las que devuelven entidades completas.

proyección

Nota: Si especifica este parámetro, es posible que cambien los requisitos de índice de la consulta.

start_cursor

Posición del cursor en la que se debe iniciar la consulta.

end_cursor

Posición del cursor en la que finalizar 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 devuelve una lista de resultados (que puede estar vacía):

Obtiene y descarta el número de resultados especificado por el argumento offset.
Obtiene y devuelve hasta el número máximo de resultados especificado por el argumento limit.

Por lo tanto, el rendimiento del método se escala de forma lineal con la suma de offset + limit.

Nota: Este método es solo un envoltorio fino alrededor del método run() y es menos eficiente y requiere más memoria que usar run() directamente. Rara vez necesitarás usar fetch(). Se proporciona principalmente para que te resulte más cómodo en los casos en los que necesites obtener una lista completa en memoria de los resultados de la consulta.

Nota: El método fetch() se ha diseñado para recuperar solo el número de resultados especificado por el argumento limit. Para obtener todos los resultados disponibles de una consulta cuando se desconoce su número, usa run() con un tamaño de lote grande, como run(batch_size=1000), en lugar de fetch().

Argumentos

limit

Número máximo de resultados que se devolverán. Si se le asigna el valor None, se recuperarán todos los resultados disponibles.

read_policy

Lee la política que especifica el nivel de coherencia de datos que quieres:

STRONG_CONSISTENCY: Garantiza los resultados más recientes, pero solo se puede usar con un grupo de entidades.
EVENTUAL_CONSISTENCY: Puede abarcar varios grupos de entidades, pero puede devolver resultados obsoletos en ocasiones. Por lo general, las consultas de coherencia eventual se ejecutan más rápido que las de coherencia fuerte, pero no hay ninguna garantía.

Nota: Las consultas globales (no antecesoras) ignoran este argumento.

deadline

offset

Número de resultados que se omitirán antes de devolver el primero.

keys_only

Si true, devuelve solo las claves en lugar de las entidades completas. Las consultas para obtener solo las claves son más rápidas y económicas que las que devuelven entidades completas.

proyección

Nota: Si especifica este parámetro, es posible que cambien los requisitos de índice de la consulta.

start_cursor

Posición del cursor en la que se debe iniciar la consulta.

end_cursor

Posición del cursor en la que finalizar la consulta.

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

Devuelve el número de resultados que coinciden con la consulta. Es más rápido por un factor constante que recuperar todos los resultados, pero el tiempo de ejecución sigue aumentando de forma lineal con la suma de offset + limit. A menos que se espere que el número de resultados sea pequeño, es mejor 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

Lee la política que especifica el nivel de coherencia de datos que quieres:

STRONG_CONSISTENCY: Garantiza los resultados más recientes, pero solo se puede usar con un grupo de entidades.
EVENTUAL_CONSISTENCY: Puede abarcar varios grupos de entidades, pero puede devolver resultados obsoletos en ocasiones. Por lo general, las consultas de coherencia eventual se ejecutan más rápido que las de coherencia fuerte, pero no hay ninguna garantía.

Nota: Las consultas globales (no antecesoras) ignoran este argumento.

deadline

offset

Número de resultados que se omitirán antes de contabilizar el primero.

limit

Número máximo de resultados que se contabilizarán.

Nota: Si se especifica explícitamente, este parámetro anula cualquier valor definido en la cláusula LIMIT de la cadena de consulta de GQL. Sin embargo, si se omite el parámetro, el valor predeterminado 1000 no anula la cláusula LIMIT de la consulta de GQL y solo se aplica si no se ha especificado ninguna cláusula LIMIT.

start_cursor

Posición del cursor en la que se debe iniciar la consulta.

end_cursor

Posición del cursor en la que finalizar la consulta.

index_list ()

Devuelve una lista de los índices utilizados por una consulta ejecutada, incluidos los índices primarios, compuestos, de tipo y de una sola propiedad.

Precaución: Si invocas este método en una consulta que aún no se ha ejecutado, se generará una excepción AssertionError.

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

Por ejemplo, el siguiente código imprime información variada sobre los índices que usa una consulta:

# 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 />")

De esta forma, se genera una salida como la siguiente para cada índice:

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

cursor ()

Devuelve una cadena de cursor codificada en base64 que indica la posición en el conjunto de resultados de la consulta después del último resultado obtenido. La cadena de cursor se puede usar de forma segura en los parámetros GET y POST de HTTP, y también se puede almacenar en Datastore o Memcache. En una invocación futura de la misma consulta, se puede proporcionar esta cadena a través del parámetro start_cursor o del método with_cursor() para reanudar la obtención de resultados desde esta posición.

Precaución: Si invocas este método en una consulta que aún no se ha ejecutado, 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 (opcionalmente) de finalización dentro del conjunto de resultados de una consulta desde las que se deben obtener los resultados. Las cadenas de cursor que indican las posiciones inicial y final se pueden obtener llamando a cursor() después de una invocación anterior de la consulta. La consulta actual debe ser idéntica a la invocación anterior, incluido el tipo de entidad, los filtros de propiedad, los filtros de ancestro y los criterios de ordenación.

Argumentos

start_cursor: Cadena de cursor codificada en Base64 que especifica dónde empezar la consulta.
end_cursor: Cadena de cursor codificada en base64 que especifica dónde finalizar la consulta.

La clase GqlQuery Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Introducción

Constructor

Métodos de instancia

La clase GqlQuery