Clase de consulta NDB

Un objeto Query representa una consulta de NDB, una solicitud de una lista filtrada y ordenada de entidades.

Esta página contiene documentación de referencia. Para obtener información general sobre las consultas de NDB, consulta Consultas.

Opciones de consulta

Muchos métodos de consulta aceptan un conjunto estándar de opciones adicionales, ya sea en forma de argumentos de palabras clave, como keys_only=True, o como objeto QueryOptions transmitido con options=QueryOptions(...).

Las consultas admiten varias opciones de configuración. Se especifican mediante argumentos de palabras clave en los métodos Query:

Argumento Tipo Predeterminado Descripción
keys_only bool False Todas las operaciones devuelven claves en lugar de entidades.
proyección tupla (o lista) de propiedades (o cadenas) None Las operaciones devuelven entidades con solo las propiedades especificadas. definidas. projection=[Article.title, Article.date] o projection=['title', 'date'] obtiene las entidades que tienen definidos esos dos campos. (Consulta Consultas de proyección).
offset int 0 Número de resultados de la consulta que se omitirán.
límite int Sin límite Número máximo de resultados de consulta que se devolverán.
batch_size int 20 Tamaño del lote.

Solo afecta a la eficiencia de las consultas. Los tamaños de lote más grandes usan más memoria, pero hacen menos llamadas RPC.
prefetch_size int None Anula el tamaño del lote del primer lote devuelto.
produce_cursors bool False Generar cursores a partir de una consulta (consulta Iteradores de consultas). Cursores de consultas).
start_cursor Cursor None Punto de partida de la búsqueda (consulta cursores de consulta).
end_cursor Cursor None Punto final de la búsqueda (consulta cursores de consulta).
deadline int Depende de Context Anula el plazo de RPC (que es de 5 segundos de forma predeterminada si no se anula al crear Context).
read_policy ndb.EVENTUAL_CONSISTENCY La política de lectura. Definir como ndb.EVENTUAL_CONSISTENCY para obtener resultados más rápidos sin esperar a que Datastore aplique los cambios pendientes a todos los registros devueltos.

Para ejecutar una consulta con un conjunto específico de opciones, pasa los argumentos de palabras clave al método aplicable: 

qry = Employee.query().filter(...).order(...) # Create a query
for acct in qry.fetch(10, offset=20): # Skip the first 20
  print acct

En ocasiones, puede que quieras conservar un conjunto de opciones de consulta y usarlas en varios lugares. Aunque podrías guardarlos en un diccionario y pasar este diccionario a los métodos mediante **kwds, también puedes crear un objeto QueryOptions y pasarlo mediante el argumento de palabra clave options. Los dos ejemplos siguientes son equivalentes: 

qo = ndb.QueryOptions(keys_only=True, offset=20)
results = qry.fetch(10, options=qo)
results = qry.fetch(10, keys_only=True, offset=20)

Constructor

Normalmente, una aplicación crea un Query llamando a Model.query(). Pero también puedes llamar a ndb.Query().

Argumentos

kind
Cadena de tipo opcional. Normalmente, el nombre de una clase de entidad.
ancestor
Clave de ancestro opcional.
filtros
Nodo opcional que representa un árbol de expresiones de filtro.
pedidos
Objeto
opcionaldatastore_query.Order.
aplicación
ID de aplicación opcional.
namespace
Espacio de nombres opcional. Si no se especifica, se usará el espacio de nombres predeterminado en el momento en que se ejecute la consulta.
proyección
Lista o tupla opcional de propiedades que se van a proyectar.
group_by
Lista o tupla opcional de propiedades por las que agrupar.
default_options
Opcional Objeto QueryOptions que proporciona opciones de consulta predeterminadas que se usarán cuando se ejecute la consulta.

Métodos de instancia

filter(filter1, filter2, ...)
Devuelve un nuevo Query con los filtros adicionales aplicados. Usa argumentos de filtro tal como se describe en Consultas. qry.filter(filter1).filter(filter2) es igual a qry.filter(filter1, filter2)
get(**q_options)
Devuelve el primer resultado de la consulta, si hay alguno (de lo contrario, None). Es similar a llamar a q.fetch(1) y devolver el primer elemento de la lista de resultados.

Argumentos

**q_options
Se admiten
todos los argumentos de palabras clave de las opciones de consulta.
order(order1, order2, ...)
Devuelve un nuevo Query con los criterios de ordenación adicionales aplicados. Toma uno o varios argumentos que son propiedades o propiedades "negadas". Por ejemplo, para ordenar a los usuarios por edad y "desempatar" por nombre, puedes usar algo como qry.order(-Account.birthday, Account.name)
bind(...values...)
Esta función se usa con consultas de GQL que utilizan enlaces de parámetros (:1, :2, etc.) o enlaces con nombre (:foo, :bar, etc.). Asigna los valores transmitidos a los parámetros.

Para vincular parámetros, puedes llamar a algo parecido a qry.bind("USA", 49). Para vincular parámetros con nombre, puedes llamar a algo como qry.bind(region = "USA", threshold = 49).

Devuelve un nuevo objeto Query con los valores de los parámetros vinculados.

count(limit=None, **q_options)
Devuelve el número de resultados de la consulta, hasta un límite. Devuelve el mismo resultado que len(q.fetch(limit)), pero de forma más eficiente.

Argumentos

limit
Número máximo de resultados que se deben contar
**q_options
Se admiten todos los argumentos de palabras clave de las opciones de consulta y las opciones de contexto.
count_async(limit, **q_options)
Cuenta de forma asíncrona el número de resultados de la consulta, hasta un límite; devuelve un Future cuyo resultado es un número. Esta es la versión asíncrona de count().
fetch(limit, **q_options)
Obtener una lista de resultados de consulta, hasta un límite.

Argumentos

limit
Número máximo de resultados que se deben contar
**q_options
Se admiten
todos los argumentos de palabras clave de las opciones de consulta.
fetch_async(limit, **q_options)
Obtiene de forma asíncrona una lista de resultados de consulta, hasta un límite. Devuelve un Future cuyo resultado es una lista de resultados. Esta es la versión asíncrona de fetch().
fetch_page(page_size, **q_options)
Obtener una "página" de resultados. Este es un método especializado para usar en interfaces de usuario de paginación.

Argumentos

page_size
Se devolverá este número de resultados como máximo.
**q_options
Se admiten
todos los argumentos de palabras clave de las opciones de consulta.
Devuelve una tupla (results, cursor, more):
  • results lista de resultados de la consulta
  • cursor un cursor de consulta que apunta al siguiente lote de resultados. Si no hay más resultados, puede que se trate de None.
  • more bool indica si (probablemente) hay más resultados después de este lote. Si el valor es False, no hay más resultados. Si el valor es True, probablemente haya más resultados.

Para obtener la página siguiente, pasa el cursor devuelto por una llamada a la siguiente llamada mediante start_cursor=cursor. Una práctica habitual es pasar el cursor al cliente mediante cursor.urlsafe() y reconstruir ese cursor en una solicitud posterior mediante Cursor(urlsafe=string).

fetch_page_async(page_size, **q_options)
Obtiene de forma asíncrona una "página" de resultados. Esta es la versión asíncrona de fetch_page().
get_async(**q_options)
Devuelve de forma asíncrona el primer resultado de la consulta (si hay alguno) (de lo contrario, None). Es la versión asíncrona de get().
iter(**q_options)
Crea y devuelve un iterador sobre la consulta.

Argumentos

**q_options
Se admiten
todos los argumentos de palabras clave de las opciones de consulta.

Devuelve un objeto QueryIterator.

map(callback, pass_batch_into_callback=None, merge_future=None, **q_options)
Asigna una función de retrollamada o una tarea a los resultados de la consulta. Es decir, aplica la función (o tasklet) a cada entidad de los resultados de la consulta.

Argumentos

devolución de llamada
Función o tarea que se aplicará a cada resultado.
pass_batch_into_callback
Si True, llama a la retrollamada con información del lote argumentos tal como se describe a continuación.
merge_future
Subclase
opcionalFuture; consulta la información que aparece más abajo.
**q_options
Se admiten
todos los argumentos de palabras clave de las opciones de consulta.

Firma de retrollamada: la retrollamada se suele invocar con una entidad como argumento. Sin embargo, si se proporciona keys_only=True, se llama con una clave. Si se proporciona pass_batch_into_callback=True, se llama a la retrollamada con tres argumentos: el lote actual, el índice dentro del lote y la entidad o Key en ese índice. La retrollamada puede devolver lo que quiera. Si la retrollamada es None, se presupone una retrollamada trivial que solo devuelve la entidad o la clave transferida.

Opcional merge_future merge_future es un argumento avanzado que se puede usar para anular cómo se combinan los resultados de la retrollamada en el valor de retorno general de map(). De forma predeterminada, se genera una lista de valores devueltos de retrollamada. Sustituyendo una de las pocas alternativas especializadas, puedes organizarlo de otra forma. Consulta el código fuente de tasklets.MultiFuture para ver la implementación predeterminada y una descripción del protocolo que debe implementar el objeto merge_future. Entre las alternativas del mismo módulo se incluyen QueueFuture, SerialQueueFuture y ReducingFuture.

Devuelve una lista con los resultados de todas las devoluciones de llamada. Sin embargo, consulta la sección "merge_future opcional" de arriba. Devuelve cuando la consulta se ha completado y todas las retrollamadas han devuelto un valor.

map_async(callback, pass_batch_into_callback=None, merge_future=None, **q_options)
Asigna de forma asíncrona una función de retrollamada o una tarea a los resultados de la consulta. Esta es la versión asíncrona de map().