Um objeto Query
representa uma consulta NDB, uma solicitação para
uma lista de entidades filtrada e classificada.
Esta página contém documentação de referência. Para uma discussão geral sobre as consultas NDB, veja Consultas.
Opções de consulta
Muitos métodos de consulta usam um conjunto padrão de opções
extras, seja na forma de argumentos de palavra-chave, como
keys_only=True
, ou como objeto
QueryOptions
transmitido com
options=QueryOptions(...)
.
As consultas são compatíveis com várias opções de configuração.
Elas são especificadas por argumentos de palavra-chave para os métodos Query
:
Argumento | Tipo | Padrão | Descrição |
---|---|---|---|
keys_only | bool | False | Todas as operações retornam chaves em vez de entidades. |
projection | tupla (ou lista) de propriedades (ou strings) | None
| As operações retornam entidades apenas com o conjunto especificado de
propriedades.
projection=[Article.title, Article.date]
ou projection=['title', 'date']
busca entidades com somente esses dois campos definidos.
Veja Consultas de projeção.
|
offset | int | 0 | Número de resultados da consulta para ignorar. |
limit | int | Sem limite | Número máximo de resultados da consulta para retornar. |
batch_size | int | 20 | Tamanho do batch. Afeta somente a eficiência das consultas. Tamanhos de lote maiores usam mais memória, mas fazem menos chamadas RPC. |
prefetch_size | int | None | Modifica o tamanho do lote para o primeiro lote retornado. |
produce_cursors | bool | False
| Gera cursores da consulta. Veja Iteradores de consulta e Cursores de consulta. |
start_cursor | Cursor | None
| Ponto de partida da pesquisa. Veja Cursores de consulta. |
end_cursor | Cursor | None
| Ponto final da pesquisa. Veja Cursores de consulta. |
deadline | int | Depende do Context
| Modifica o prazo final da RPC (que tem o padrão de cinco segundos se não for modificada quando
Context é criado)
|
read_policy | ndb.EVENTUAL_CONSISTENCY
| A política de leitura. Defina como ndb.EVENTUAL_CONSISTENCY para gerar
resultados que podem ser mais rápidos sem esperar que o Datastore
aplique as alterações pendentes a todos os registros retornados.
|
Para executar uma consulta com um conjunto específico de opções, passe os argumentos de palavra-chave para o método aplicável:
qry = Employee.query().filter(...).order(...) # Create a query for acct in qry.fetch(10, offset=20): # Skip the first 20 print acct
Às vezes, pode ser conveniente manter um conjunto de opções de consulta e usá-las em vários lugares. É possível mantê-las
em um dicionário e transmitir este dicionário para os
métodos usando **kwds
. Também é possível criar um objeto
QueryOptions
e transmiti-lo
usando o argumento de opções de palavra-chave.
Os dois exemplos seguintes são equivalentes:
qo = ndb.QueryOptions(keys_only=True, offset=20) results = qry.fetch(10, options=qo) results = qry.fetch(10, keys_only=True, offset=20)
Construtor
Normalmente, um aplicativo cria um Query
chamando
Model.query()
. No entanto, também é possível chamar
ndb.Query()
.
Argumentos
- kind
- String de tipo opcional. Normalmente, o nome de uma classe de entidade.
- ancestor
- Chave ancestral opcional.
- filters
- Nó opcional que representa uma árvore de expressão de filtro.
- orders
- Objeto
datastore_query.Order
opcional. - app
- ID opcional do aplicativo.
- namespace
- Namespace opcional. Se não for especificado, será usado o namespace padrão no momento em que a consulta for executada.
- projection
- Lista ou tupla opcional de propriedades para projetar.
- group_by
- Lista ou tupla opcional de propriedades para agrupamento.
- default_options
- Objeto
QueryOptions
opcional que fornece as opções de consulta padrão a serem usadas quando a consulta é executada.
Métodos de instância
- filter(filter1, filter2, ...)
- Retorna uma nova
Query
com mais filtros aplicados. Aceita argumentos de filtro, conforme descrito em Consultas.qry.filter(filter1).filter(filter2)
é equivalente aqry.filter(filter1, filter2)
- get(**q_options)
- Retorna o primeiro resultado da consulta, se houver (caso contrário,
None
). Isso é semelhante a chamarq.fetch(1)
e retornar o primeiro item da lista de resultados.Argumentos
- **q_options
- Todos os argumentos de palavra-chave das opções de consulta são aceitos.
- order(order1, order2, ...)
- Retorna uma nova
Query
com mais ordens de classificação aplicadas. Aceita um ou mais argumentos que são propriedades ou propriedades "negadas". Por exemplo, para classificar os usuários por idade e "separações" por nome, use algo comoqry.order(-Account.birthday, Account.name)
- bind(...values...)
- Esta função é para uso em consultas GQL que usam vinculações de
parâmetro (
:1
,:2
etc.) ou vinculações nomeadas (:foo
,:bar
etc.). Ela vincula os valores passados aos parâmetros.Para vincular parâmetros, chame algo como
qry.bind("USA", 49)
. Para vincular parâmetros nomeados, chame algo comoqry.bind(region = "USA", threshold = 49)
.Retorna um novo objeto
Query
com os valores de parâmetro vinculados. - count(limit=None, **q_options)
- Retorna o número de resultados da consulta, até um limite.
Isso retorna o mesmo resultado
len(q.fetch(limit))
, mas com mais eficiência.Argumentos
- limit
- Máximo de resultados para contar
- **q_options
- Todos os argumentos de palavra-chave das opções de consulta e as opções de contexto são aceitos.
- count_async(limit, **q_options)
- Conta de maneira assíncrona o número de resultados da consulta, até um limite.
Retorna um
Future
que tem um número como resultado. Esta é a versão assíncrona de count(). - fetch(limit, **q_options)
- Busca uma lista de resultados da consulta, até um limite.
Argumentos
- limit
- Máximo de resultados para contar
- **q_options
- Todos os argumentos de palavra-chave das opções de consulta são aceitos.
- fetch_async(limit, **q_options)
- Busca, de maneira assíncrona, uma lista de resultados da consulta, até um limite.
Retorna um
Future
que tem como resultado uma lista de resultados. Esta é a versão assíncrona de fetch(). - fetch_page(page_size, page_size)
- Busca uma "página" de resultados. Trata-se de um método especializado para uso por interfaces do usuário de paginação.
Argumentos
- page_size
- Limite de quantos resultados serão retornados.
- **q_options
- Todos os argumentos de palavra-chave das opções de consulta são aceitos.
(results, cursor, more)
:- results lista de resultados da consulta
- cursor um cursor de consulta que aponta
para o "próximo" lote de resultados. Se não houver mais resultados, pode
ser
None
. - more
bool
indica se há (provavelmente) mais resultados após esse lote. SeFalse
, não há mais resultados. SeTrue
, há provavelmente mais resultados.
Para buscar a próxima página, transmita o cursor retornado por uma chamada para a próxima chamada usando
start_cursor=cursor
. Um idioma comum é transmitir o cursor para o cliente usandocursor.urlsafe()
e reconstruir esse cursor em uma solicitação subsequente usandoCursor(urlsafe=string)
. - fetch_page_async(page_size, **q_options)
- Busca, de maneira assíncrona, uma "página" de resultados. Esta é a versão assíncrona de fetch_page().
- get_async(**q_options)
- Retorna, de maneira assíncrona, o primeiro resultado da consulta, se houver.
Caso contrário,
None
. Esta é a versão assíncrona de get(). - iter(**q_options)
- Constrói e retorna um iterador com base na consulta.
Argumentos
- **q_options
- Todos os argumentos de palavra-chave das opções de consulta são aceitos.
Retorna um objeto QueryIterator.
- map(callback, pass_batch_into_callback=None, merge_future=None, **q_options)
- Mapeia uma função de callback ou um tasklet com base nos resultados da consulta. Ou seja, aplica a função (ou tasklet) a cada entidade nos resultados da consulta.
Argumentos
- callback
- Uma função ou tasklet para aplicação em cada resultado.
- pass_batch_into_callback
- Se
True
, chamará o callback com argumentos de informações do lote, conforme descrito abaixo. - merge_future
- Subclasse
Future
opcional. Veja abaixo. - **q_options
- Todos os argumentos de palavra-chave das opções de consulta são aceitos.
Assinatura de retorno de chamada: o retorno de chamada é normalmente chamado com uma entidade como argumento. No entanto, se
keys_only=True
for fornecido, ele será chamado com uma Chave. Sepass_batch_into_callback=True
for fornecido, a callback será chamada com três argumentos: o lote atual, o índice dentro do lote e a entidade ouKey
nesse índice. O retorno de chamada pode retornar o que quiser. Se a callback forNone
, será considerada uma callback trivial que só retorna a entidade ou a chave transmitida.merge_future
opcional Omerge_future
é um argumento avançado que pode ser usado para modificar como os resultados de callback são combinados no valor de retorno geralmap()
. Por padrão, uma lista de valores de retorno de chamada é produzida. Ao substituir uma de um pequeno número de alternativas especializadas, você pode providenciar o contrário. Consulte o código-fonte detasklets.MultiFuture
para a implementação padrão e uma descrição do protocolo que o objetomerge_future
precisa implementar. As alternativas do mesmo módulo incluemQueueFuture
,SerialQueueFuture
eReducingFuture
.Retorna uma lista dos resultados de todos os retornos de chamada. Mas veja "
merge_future
opcional" acima. Ele é retornado quando a consulta foi executada até a conclusão e todos os retornos de chamada foram apresentados. - map_async(callback, pass_batch_into_callback=None, merge_future=None, **q_options)
- Mapeia, de maneira assíncrona, uma função de callback ou um tasklet com base nos resultados da consulta. Esta é a versão assíncrona de map().