Classe de consulta NDB

Um objeto Query representa uma consulta NDB, um pedido de uma lista filtrada e ordenada de entidades.

Esta página contém documentação de referência. Para uma discussão geral sobre consultas NDB, consulte Consultas.

Opções de consulta

Muitos métodos de consulta usam um conjunto padrão de opções adicionais, quer na forma de argumentos de palavras-chave, como keys_only=True, quer como um objeto QueryOptions transmitido com options=QueryOptions(...).

As consultas suportam várias opções de configuração. Estes são especificados por argumentos de palavras-chave para os métodos Query:

Argumento Tipo Predefinição Descrição
keys_only bool False Todas as operações devolvem chaves em vez de entidades.
projeção Tuplo (ou lista) de propriedades (ou strings) None As operações devolvem entidades com apenas as propriedades especificadas definidas. projection=[Article.title, Article.date] ou projection=['title', 'date'] obtém entidades com apenas esses dois campos definidos. (Consulte Consultas de projeção.)
compensação int 0 Número de resultados da consulta a ignorar.
limite int Sem limite Número máximo de resultados da consulta a devolver.
batch_size int 20 Tamanho do lote.

Apenas afeta a eficiência das consultas; os tamanhos dos lotes maiores usam mais memória, mas fazem menos chamadas RPC.
prefetch_size int None Substitui o tamanho do lote para o primeiro lote devolvido.
produce_cursors bool False Gere cursores a partir da consulta (consulte Iteradores de consultas). Cursores de consulta).
start_cursor Cursor None Ponto de partida para a pesquisa (consulte cursores de consultas).
end_cursor Cursor None Ponto final para a pesquisa (consulte cursores de consulta).
prazo int Depende de Context Substitui o prazo da RPC (que é de 5 segundos por predefinição se não for substituído quando o objeto Context é criado)
read_policy ndb.EVENTUAL_CONSISTENCY A política de leitura. Definido como ndb.EVENTUAL_CONSISTENCY para obter resultados possivelmente mais rápidos sem esperar que o Datastore aplique as alterações pendentes a todos os registos devolvidos.

Para executar uma consulta com um conjunto específico de opções, transmita os argumentos de palavras-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

Ocasionalmente, pode querer manter um conjunto de opções de consulta e usá-las em vários locais. Embora possa simplesmente mantê-los num dicionário e passar este dicionário para os métodos usando **kwds, também pode criar um objeto QueryOptions e passá-lo usando o argumento da palavra-chave options. 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, uma aplicação cria um Query chamando Model.query(). No entanto, também é possível ligar para ndb.Query().

Argumentos

kind
String de tipo opcional. Normalmente, o nome de uma classe de entidade.
ancestor
Chave de antepassado opcional.
filtros
Nó opcional que representa uma árvore de expressões de filtro.
encomendas
Objeto
opcionaldatastore_query.Order.
app
ID da app opcional.
namespace
Espaço de nomes opcional. Se não for especificado, é usado o espaço de nomes predefinido no momento em que a consulta é executada.
projeção
Lista ou tuplo opcional de propriedades a projetar.
group_by
Lista opcional ou tuplo de propriedades pelas quais agrupar.
default_options
Opcional QueryOptions objeto que fornece opções de consulta predefinidas a usar quando a consulta é executada.

Métodos de instância

filtrar(filter1, filter2, ...)
Devolve um novo Query com filtros adicionais aplicados. Aceita argumentos de filtro, conforme descrito em Consultas. qry.filter(filter1).filter(filter2) é equivalente a qry.filter(filter1, filter2)
get(**q_options)
Devolve o primeiro resultado da consulta, se existir (caso contrário, None). Isto é semelhante a chamar q.fetch(1) e devolver o primeiro item da lista de resultados.

Argumentos

**q_options
Todos os argumentos de palavras-chave das opções de consulta são suportados.
order(order1, order2, ...)
Devolve um novo Query com ordens de ordenação adicionais aplicadas. Aceita um ou mais argumentos que são propriedades ou propriedades "negadas". Por exemplo, para ordenar os utilizadores por idade e "desempatar" por nome, pode usar algo como qry.order(-Account.birthday, Account.name)
bind(...values...)
Esta função destina-se a ser usada com consultas GQL que usam associações de parâmetros (:1, :2, etc.) ou associações com nomes (:foo, :bar, etc.). Associa os valores transmitidos aos parâmetros.

Para associar parâmetros, pode chamar algo como qry.bind("USA", 49). Para associar parâmetros com nome, pode chamar algo como qry.bind(region = "USA", threshold = 49).

Devolve um novo objeto Query com os valores dos parâmetros associados.

count(limit=None, **q_options)
Devolve o número de resultados da consulta, até um limite. Isto devolve o mesmo resultado que len(q.fetch(limit)), mas de forma mais eficiente.

Argumentos

limit
Quantos resultados contar no máximo
**q_options
Todos os argumentos de palavras-chave das opções de consulta e as opções de contexto são suportados.
count_async(limit, **q_options)
Conta de forma assíncrona o número de resultados da consulta, até um limite; devolve um Future cujo resultado é um número. Esta é a versão assíncrona de count().
fetch(limit, **q_options)
Obter uma lista de resultados de consultas, até um limite.

Argumentos

limit
Quantos resultados contar no máximo
**q_options
Todos os argumentos de palavras-chave das opções de consulta são suportados.
fetch_async(limit, **q_options)
Obtenha de forma assíncrona uma lista de resultados da consulta, até um limite. Devolve um Future cujo resultado é uma lista de resultados. Esta é a versão assíncrona de fetch().
fetch_page(page_size, **q_options)
Obter uma "página" de resultados. Este é um método especializado para utilização por interfaces do utilizador de paginação.

Argumentos

page_size
No máximo, são devolvidos estes resultados.
**q_options
Todos os argumentos de palavras-chave das opções de consulta são suportados.
Devolve uma tupla (results, cursor, more):
  • results lista de resultados da consulta
  • cursor um cursor de consulta que aponta para o lote "seguinte" de resultados. Se não existirem mais resultados, o valor pode ser None.
  • more bool indicando se existem (provavelmente) mais resultados após este lote. Se False, não existem mais resultados; se True, provavelmente existem mais resultados.

Para obter a página seguinte, transmita o cursor devolvido por uma chamada para a chamada seguinte através de start_cursor=cursor. Um idioma comum é transmitir o cursor ao cliente através de cursor.urlsafe() e reconstruir esse cursor num pedido subsequente através de Cursor(urlsafe=string).

fetch_page_async(page_size, **q_options)
Obtenha de forma assíncrona uma "página" de resultados. Esta é a versão assíncrona de fetch_page().
get_async(**q_options)
Devolve de forma assíncrona o primeiro resultado da consulta, se existir (caso contrário, None). Esta é a versão assíncrona de get().
iter(**q_options)
Constrói e devolve um iterador sobre a consulta.

Argumentos

**q_options
Todos os argumentos de palavras-chave das opções de consulta são suportados.

Devolve um objeto QueryIterator.

map(callback, pass_batch_into_callback=None, merge_future=None, **q_options)
Mapeie uma função de chamada de retorno ou um tasklet sobre os resultados da consulta. Ou seja, aplique a função (ou o tasklet) a cada entidade nos resultados da consulta.

Argumentos

callback
Uma função ou uma tarefa a aplicar a cada resultado.
pass_batch_into_callback
Se True, chama a função de retorno com argumentos de informações em lote, conforme descrito abaixo.
merge_future
Opcional Future subclasse; veja abaixo.
**q_options
Todos os argumentos de palavras-chave das opções de consulta são suportados.

Assinatura de retorno de chamada O retorno de chamada é normalmente chamado com uma entidade como argumento. No entanto, se for fornecido o valor keys_only=True, é chamado com uma chave. Se for fornecido pass_batch_into_callback=True, a chamada de retorno é chamada com três argumentos: o lote atual, o índice no lote e a entidade ou Key nesse índice. A função de retorno de chamada pode devolver o que quiser. Se o retorno de chamada for None, é assumido um retorno de chamada trivial que apenas devolve a entidade ou a chave transmitida.

Opcional merge_future O merge_future é um argumento avançado que pode ser usado para substituir a forma como os resultados da chamada de retorno são combinados no valor de retorno map() geral. Por predefinição, é produzida uma lista de valores devolvidos de callback. Ao substituir uma das poucas alternativas especializadas, pode fazer outros arranjos. Consulte o código fonte de tasklets.MultiFuture para a implementação predefinida e uma descrição do protocolo que o objeto merge_future tem de implementar. As alternativas do mesmo módulo incluem QueueFuture, SerialQueueFuture e ReducingFuture.

Devolve uma lista dos resultados de todos os callbacks. (Mas consulte "opcional merge_future" acima.) É devolvido quando a consulta é executada até à conclusão e todos os callbacks são devolvidos.

map_async(callback, pass_batch_into_callback=None, merge_future=None, **q_options)
Mapeie de forma assíncrona uma função de chamada de retorno ou um pequeno programa sobre os resultados da consulta. Esta é a versão assíncrona de map().