Classe de consulta NDB

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:

ArgumentoTipoPadrãoDescrição
keys_only bool False Todas as operações retornam chaves em vez de entidades.
projectiontupla (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.
offsetint 0 Número de resultados da consulta para ignorar.
limitint Sem limiteNú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.
deadlineint 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 a qry.filter(filter1filter2)
get(**q_options)
Retorna o primeiro resultado da consulta, se houver (caso contrário, None). Isso é semelhante a chamar q.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 como qry.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 como qry.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.
Retorna uma tupla (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. Se False, não há mais resultados. Se True, 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 usando cursor.urlsafe() e reconstruir esse cursor em uma solicitação subsequente usando Cursor(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. Se pass_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 ou Key nesse índice. O retorno de chamada pode retornar o que quiser. Se a callback for None, será considerada uma callback trivial que só retorna a entidade ou a chave transmitida.

merge_future opcional O merge_future é um argumento avançado que pode ser usado para modificar como os resultados de callback são combinados no valor de retorno geral map(). 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 de tasklets.MultiFuture para a implementação padrão e uma descrição do protocolo que o objeto merge_future precisa implementar. As alternativas do mesmo módulo incluem QueueFuture, SerialQueueFuture e ReducingFuture.

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().