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 adicionais, na forma de argumentos de palavra-chave, como keys_only=True, ou como objeto QueryOptions passado 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 de 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 apenas com os 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 a eficiência das consultas apenas. 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 Substitui o prazo final do RPC (cujo padrão é de 5 segundos se não for substituído 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. Embora você possa mantê-las em um dicionário e passar esse dicionário para os métodos que usam **kwds, também é possível criar um objeto QueryOptions e passá-lo usando o argumento de palavra-chave das opções. 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 uma Query chamando Model.query(). Mas é possível também 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
Código do aplicativo opcional.
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 por qual agrupar.
default_options
Objeto QueryOptions opcional que fornece as opções de consulta padrão a serem usadas quando a consulta é executada.

Métodos da instância

filtro(filter1, filter2, ...)
Retorna uma nova Query com o(s) filtro(s) adicional(is) aplicado(s). 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.
ordem(order1, order2, ...)
Retorna uma nova Query com ordem(ns) de classificação adicional aplicada(s). Aceita um ou mais argumentos que são propriedades ou propriedades "negadas". Por exemplo, para classificar usuários por idade e "quebrar vínculos" por nome, você pode usar algo como qry.order(-Account.birthday, Account.name).
bind(...values...)
Essa função é para uso com consultas GQL que utilizam vinculações de parâmetros (:1, :2 etc.) ou vinculações nomeadas (:foo, :bar etc.). Ela vincula os valores passados aos parâmetros.

Para vincular parâmetros, você pode chamar algo como qry.bind("USA", 49). Para vincular parâmetros nomeados, você pode chamar algo como qry.bind(region = "USA", threshold = 49).

Retorna um novo objeto Query com os valores de parâmetro vinculados.

contagem(limit=None, **q_options)
Retorna o número de resultados da consulta, até um limite. Isso retorna o mesmo resultado que len(q.fetch(limit)), porém, 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, assincronamente, o número de resultados da consulta, até um limite; retorna um Future cujo resultado é um número. 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 cujo 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
No máximo, muitos 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, ele poderá ser None.
  • more: bool que indica se há (provavelmente) mais resultados após esse lote. Se for False, não haverá mais resultados. Se for True, haverá provavelmente mais resultados.

Para buscar a próxima página, passe o cursor retornado por uma chamada para a próxima chamada usando start_cursor=cursor. Um idioma comum serve para passar o cursor para o cliente usando cursor.urlsafe() e para 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 retorno de chamada 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 a ser aplicado a cada resultado.
pass_batch_into_callback
Se for True, chamará o retorno de chamada 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, o retorno de chamada será chamado com três argumentos: o lote atual, o índice no lote e a entidade ou Key nesse índice. O retorno de chamada pode retornar o que quiser. Se o retorno de chamada for None, será considerado um retorno de chamada comum que apenas retornará 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 do retorno de chamada 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. Veja 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. 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 retorno de chamada ou um tasklet com base nos resultados da consulta. Esta é a versão assíncrona de map().
Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Ambiente padrão do App Engine para Python 2