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 Query

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 anterior de la base de datos, lee la Guía de migración de la base de datos a NDB.

La clase Query representa una consulta para recuperar entidades de App Engine Datastore. (Consulta también la clase GqlQuery relacionada, que define consultas mediante GQL, un lenguaje de consulta similar a SQL).

Query 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 para un tipo de entidad determinado, mediante llamadas directas al constructor Query

class Song(db.Model):
  title = db.StringProperty()
  composer = db.StringProperty()
  date = db.DateTimeProperty()

q = db.Query(Song)

o al método de clase all() de la clase de modelo del tipo:

q = Song.all()

Sin más modificaciones, la instancia que resulte de la clase Query recuperará todas las entidades existentes del tipo especificado. Las llamadas de método al objeto se pueden usar para personalizar la consulta con criterios de filtro adicionales, condiciones de principal y órdenes de clasificación:

q.filter('title =', 'Imagine')
q.ancestor(ancestor_key)
q.order('-date')

Por comodidad, todos estos métodos muestran el objeto de consulta para que puedan conectarse en cascada en una sola declaración:

q.filter('title =', 'Imagine').ancestor(key).order('-date')

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 Query se define de la manera siguiente:

class Query(model_class=None,keys_only=False,cursor=None,namespace=None,projection=None,distinct=False)

Crea una instancia de la clase Query para recuperar entidades de App Engine Datastore.

Sin más modificaciones, el objeto de consulta resultante recuperará todas las entidades existentes del tipo especificado por model_class. Los métodos de la instancia filter(), ancestor(), y order() se puede usar para personalizar la búsqueda con criterios de filtro adicionales, condiciones de principal y órdenes de clasificación.

Argumentos

model_class

Clase de modelo (o Expando) que representa el tipo de entidad al que se aplica la consulta.

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.

cursor

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

namespace

Espacio de nombres para utilizar en la consulta.

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.

distinct

En el caso de las consultas de proyección, distinct=True especifica que solo se mostrarán resultados que sean únicos en un conjunto de resultados. Esto solo mostrará el primer resultado para las entidades que tienen los mismos valores en las propiedades que se están proyectando.

Verdadero: Solo muestra el primer resultado de cada conjunto distinto de valor para las propiedades en la proyección.
Falso: Se muestran todos los resultados.

Métodos de instancia

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

filter (property_operator, value)

Agrega un filtro de propiedades a la consulta. La consulta mostrará solo las entidades cuyas propiedades satisfagan todos sus filtros.

Argumentos

property_operator

String que consiste en un nombre de propiedad y un operador de comparación opcional (=, !=, <, <=, >, >=, IN), separados por un espacio: por ejemplo, 'age >'. Si solo se especifica un nombre de propiedad sin un operador de comparación, el filtro compara la igualdad (=) de forma predeterminada.

value

Valor para comparar con el valor de la propiedad. Por ejemplo:

q.filter('height >', 42).filter('city =', 'Seattle')
q.filter('user =', users.get_current_user())

El valor de comparación especificado debe ser del mismo tipo de valor que el de la propiedad que se está comparando.

ancestor (ancestor)

Agrega un filtro principal a la consulta. La consulta mostrará solo las entidades con el principal especificado.

Argumento

ancestor: Entidad o clave principal.

order (property)

Agrega un orden de clasificación a la consulta. Si se agrega más de un orden de clasificación, se aplicarán en el orden especificado.

Argumento

propiedad

String que proporciona el nombre de la propiedad en la que se va a ordenar, opcionalmente precedida por un guion (-) para especificar el orden descendente. La omisión del guion especifica el orden ascendente de forma predeterminada. Por ejemplo:

# Order alphabetically by last name:
q.order('last_name')

# Order by height, tallest to shortest:
q.order('-height')

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 o se establece en None, todos los resultados disponibles se recuperarán de forma predeterminada.

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

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.

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.

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.Query(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.