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.

Clase de consulta de NDB

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

Esta página contiene documentación de referencia. Para obtener una explicación general de las consultas de NDB, ve a Consultas.

Opciones de consulta

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

Las consultas admiten una variedad de opciones de configuración. Estas se especifican por argumentos de palabra clave para los métodos de Query:

Argumento	Tipo	Predeterminado	Descripción
keys_only	`bool`	`False`	Todas las operaciones muestran claves en lugar de entidades.
projection	tupla (o lista) de propiedades (o strings)	`None`	Las operaciones muestran las entidades solo con el conjunto de propiedades especificado. `projection=[Article.title, Article.date]` o `projection=['title', 'date']` recuperan las entidades solo con estos dos campos establecidos. (Ve a Consultas de proyección).
offset	`int`	`0`	Cantidad de resultados de la consulta que se omitirán.
limit	`int`	Sin límite	Cantidad máxima de resultados de la consulta que se mostrarán.
batch_size	`int`	`20`	Tamaño del lote. Afecta solo a la eficacia de las consultas. Los tamaños de lote grandes usan más memoria, pero realizan menos llamadas RPC.
prefetch_size	`int`	`None`	Anula el tamaño del primer lote que se muestra.
produce_cursors	`bool`	`False`	Genera cursores a partir de la consulta (ve a Iteradores de consulta. Cursores de consulta
start_cursor	`Cursor`	`None`	Punto de partida de la búsqueda (ve a Cursores de consulta).
end_cursor	`Cursor`	`None`	Punto final de la búsqueda (ve a Cursores de consulta).
plazo	`int`	Depende de `Context`	Anula el plazo de RPC (que se configura de forma predeterminada dentro de 5 segundos si no se anula cuando se crea `Context`).
read_policy	`ndb.EVENTUAL_CONSISTENCY`		La política de lectura. Establece `ndb.EVENTUAL_CONSISTENCY` para obtener resultados tal vez más rápidos sin esperar a que Datastore aplique los cambios pendientes a todos los registros que se muestran.

Para ejecutar una consulta con un conjunto de opciones específico, pasa los argumentos de palabra 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, es posible que desees guardar un conjunto de opciones de consulta y usarlas en diversos lugares. Aunque simplemente puedes mantenerlos en un diccionario y pasar este diccionario a los métodos con **kwds, también puedes crear un objeto QueryOptions y pasarlo con las opciones. Los siguientes dos ejemplos 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

Por lo general, una aplicación crea un Query llamando a Model.query(). Sin embargo, también puede llamar a ndb.Query().

Argumentos

tipo: String de tipo opcional. Normalmente, el nombre de una clase de entidad.
ancestor: Clave principal opcional.
filters: Nodo opcional que representa un árbol de expresión de filtro.
orders: Opcional, objetodatastore_query.Order.
app: 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.
projection: Lista o tupla opcional de propiedades que se proyectarán.
group_by: Lista o tupla opcional de propiedades que se agruparán.
default_options: Objeto QueryOptions opcional que proporciona las opciones de consulta predeterminadas que se usarán cuando se ejecute la consulta.

Métodos de instancia

filtro(filter1, filter2, ...)

Muestra una Query nueva con los filtros adicionales aplicados. Usa los argumentos del filtro como se describe en Consultas. qry.filter(filter1).filter(filter2) es equivalente a lo siguiente a qry.filter(filter1, filter2)

get(**q_options)

Muestra el primer resultado de la consulta, si existe alguno (sino se muestra None). Esto es similar a llamar a q.fetch(1) y mostrar el primer elemento de la lista de resultados.

Argumentos

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

orden(order1, order2, ...)

Muestra una Query nueva con órdenes de clasificación adicionales aplicados. Usa uno o más argumentos que son propiedades o propiedades "negadas". Por ejemplo, para ordenar usuarios por edad y “definir empates” por nombre, puedes usar algo como qry.order(-Account.birthday, Account.name)

vincular(...values...)

Esta función se usa con las consultas de GQL que usan vinculaciones de parámetros (:1, :2, etc.) o vinculaciones con nombre (:foo, :bar, etcétera). Vincula los valores que se pasan a los parámetros.

Para vincular los parámetros, puedes realizar una llamada similar a qry.bind("USA", 49). Para vincular los parámetros con nombre, puedes realizar una llamada similar a qry.bind(region = "USA", threshold = 49).

Muestra un objeto QueryQuery nuevo con los valores del parámetro vinculado.

count(limit=None, **q_options)

Muestra la cantidad de resultados de la consulta (hasta cierto límite). Esto muestra el mismo resultado que len(q.fetch(limit)), pero de manera más eficiente.

Argumentos

limit: Cuántos resultados se contarán como máximo.
**q_options: Se admiten todos los argumentos de palabra clave de opciones de consulta y opciones de contexto.

count_async(limit, **q_options)

Cuenta de forma asíncrona la cantidad de resultados de consultas, hasta un límite; muestra un Future cuyo resultado es un número. Esta es la versión asíncrona de count().

fetch(limit, **q_options)

Recupera una lista de resultados de la consulta (hasta cierto límite).

Argumentos

limit: Cuántos resultados se contarán como máximo.
**q_options: Se admiten todos los argumentos de palabra clave de las opciones de consulta.

fetch_async(limit, **q_options)

Recupera de manera asíncrona una lista de resultados de la consulta (hasta cierto límite). Muestra un Future cuyo resultado es una lista de resultados. Esta es la versión asíncrona de fetch().

fetch_page(page_size, **q_options)

Recupera una "página" de resultados. Este es un método especializado para paginar las interfaces de usuario.

Argumentos

page_size: Se mostrará esta cantidad de resultados como máximo.
**q_options: Se admiten todos los argumentos de palabra clave de las opciones de consulta.

Muestra una tupla

(results,
     cursor, more)

results lista de resultados de consultas
cursor un cursor de consultas que dirige al “siguiente” lote de resultados. Si no hay más resultados, es posible que esto se muestre como None.
more bool que indica si hay más resultados (probables) después de este lote. Si es False, no hay más resultados; si es True, probablemente hayan más resultados.

Para recuperar la página siguiente, pasa el cursor que muestra una llamada a la llamada siguiente con start_cursor=cursor. Una expresión común es pasar el cursor al cliente mediante cursor.urlsafe() y reconstruir ese cursor en una solicitud posterior con Cursor(urlsafe=string).

fetch_page_async(page_size, **q_options)

Recupera de manera asíncrona una "página" de resultados. Esta es la versión asíncrona de fetch_page().

get_async(**q_options)

Muestra el primer resultado de la consulta de forma asíncrona, si corresponde None. Esta es la versión asíncrona de get ().

iter(**q_options)

Crea y muestra un iterador en la consulta.

Argumentos

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

Muestra un objeto QueryIterator.

map(callback, pass_batch_into_callback=None, merge_future=None, **q_options)

Mapea una función de devolución de llamada o tasklet a los resultados de la consulta. Es decir, aplica la función (o tasklet) a cada entidad en los resultados de la consulta.

Argumentos

callback: Una función o tasklet que se aplicará a cada resultado.
pass_batch_into_callback: Si es True, llama a la función de devolución de llamada con argumentos de información del lote, como se describe a continuación.
merge_future: Subclase Future opcional; ver a continuación.
**q_options: Se admiten todos los argumentos de palabra clave de las opciones de consulta.

Firma de la devolución de llamada Normalmente, se llama a la función de devolución de llamada 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, la devolución de llamada se realiza con tres argumentos: el lote actual, el índice del lote y la entidad o Key en ese índice. La devolución de llamada puede mostrar lo que desee. Si la devolución de llamada es None, se supone que una devolución de llamada trivial solo muestra la entidad o clave que se le pasó.

merge_future opcional La merge_future es un argumento avanzado que se puede usar para anular cómo se combinan los resultados de la devolución de llamada en el valor general de que se muestra de map(). Según la configuración predeterminada, se genera una lista de valores de retorno de la devolución de llamada. Cuando se sustituye una cantidad pequeña de alternativas especializadas, puedes organizarlas de otro modo. 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. Las alternativas del mismo módulo incluyen QueueFuture, SerialQueueFuture y ReducingFuture.

Muestra una lista de resultados de todas las devoluciones de llamada. (Pero consulta "merge_future opcional" más arriba). Muestra el momento en que la consulta se ejecutó hasta completarse y en que se mostraron todas las devoluciones de llamada.

map_async(callback, pass_batch_into_callback=None, merge_future=None, **q_options)

Mapea de manera asíncrona una función de devolución de llamada o tasklet a los resultados de la consulta. Esta es la versión asíncrona de map().