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. (Consulte también la clase relacionada GqlQuery, que define las consultas con 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 instancia filter(), ancestor(), y order() se pueden usar para personalizar la consulta con criterios de filtro adicionales, condiciones principales 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.

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

El rendimiento del bucle se escala de manera lineal con la suma de offset + limit. Si sabe cuántos resultados desea recuperar, siempre debe establecer un valor limit explícito.

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 se desconoce su número, establece batch_size en 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 entidad.
EVENTUAL_CONSISTENCY
Puede abarcar varios grupos de entidad, 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.

plazo
El tiempo máximo en segundos que se esperará que el almacén de datos 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
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.

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 entidad.
EVENTUAL_CONSISTENCY
Puede abarcar varios grupos de entidad, 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.

plazo
El tiempo máximo en segundos que se esperará que el almacén de datos 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.
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.
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):

  1. Recupera y descarta la cantidad de resultados especificada por el argumento offset.
  2. 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 especificados por el argumento limit. Para recuperar 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
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 entidad.
EVENTUAL_CONSISTENCY
Puede abarcar varios grupos de entidad, 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.

plazo
El tiempo máximo en segundos que se esperará que el almacén de datos 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.
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.
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. Esto es más rápido en un factor constante que recuperar todos los resultados, pero el tiempo de ejecución sigue escalando linealmente con la suma de offset + limit. A menos que se espere que el recuento 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
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 entidad.
EVENTUAL_CONSISTENCY
Puede abarcar varios grupos de entidad, 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.

plazo
El tiempo máximo en segundos que se esperará que el almacén de datos 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 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.