Observação: o Python 2.7 chegou ao fim do suporte em 31 de janeiro de 2024. Os aplicativos Python 2.7 atuais continuarão a ser executados e a receber tráfego. No entanto, o App Engine pode bloquear a reimplantação de aplicativos que usam ambientes de execução após o término da data de suporte. Recomendamos que você migre para a versão compatível mais recente do Python.

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:

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 a qry.filter(filter1, filter2)

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, **q_options)

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