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, objeto
datastore_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
- filter(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 aqry.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 aq.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 comoqry.order(-Account.birthday, Account.name)
- bind(...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 aqry.bind(region = "USA", threshold = 49)
.Muestra un objeto
Query
Query 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, page_size)
- 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.
(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 esFalse
, no hay más resultados; si esTrue
, 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 mediantecursor.urlsafe()
y reconstruir ese cursor en una solicitud posterior conCursor(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 proporcionapass_batch_into_callback=True
, la devolución de llamada se realiza con tres argumentos: el lote actual, el índice del lote y la entidad oKey
en ese índice. La devolución de llamada puede mostrar lo que desee. Si la devolución de llamada esNone
, se supone que una devolución de llamada trivial solo muestra la entidad o clave que se le pasó.merge_future
opcional Lamerge_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 demap()
. 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 detasklets.MultiFuture
para ver la implementación predeterminada y una descripción del protocolo que debe implementar el objetomerge_future
. Las alternativas del mismo módulo incluyenQueueFuture
,SerialQueueFuture
yReducingFuture
.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().