Classe de consulta NDB

Nesta página, você verá como usar as APIs e os serviços legados em pacote. Ela só pode ser executada em ambientes de execução de primeira geração no ambiente padrão do App Engine. Se você estiver atualizando para o ambiente de execução do Python 3 do App Engine, consulte o guia de migração para saber mais sobre as opções de migração para serviços incluídos legados.

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