Módulo google.appengine.ext.ndb.query

Resumo

Wrapper Query de nível superior.

Talvez haja muitas APIs de consulta no mundo.

A API fundamental aqui sobrecarrega os seis operadores de comparação para representar filtros em valores de propriedade. Ela também é compatível com as operações AND e OR implementadas como funções: os operadores "and" e "or" do Python não podem ser sobrecarregados, e os operadores "&" e "|" têm uma prioridade que entra em conflito com a prioridade dos operadores de comparação. Exemplo:

class Employee(Model):
  name = StringProperty()
  age = IntegerProperty()
  rank = IntegerProperty()

  @classmethod
  def demographic(cls, min_age, max_age):
    return cls.query().filter(AND(cls.age >= min_age, cls.age <= max_age))

  @classmethod
  def ranked(cls, rank):
    return cls.query(cls.rank == rank).order(cls.age)

for emp in Employee.seniors(42, 5):
  print emp.name, emp.age, emp.rank

O operador "in" não pode ser sobrecarregado, mas é aceito pelo método IN(). Exemplo:

Employee.query().filter(Employee.rank.IN([4, 5, 6]))

As ordens de classificação são aceitas pelo método order(). O menos unário está sobrecarregado na classe Property para representar uma ordem decrescente:

Employee.query().order(Employee.name, -Employee.age)

Além de usar AND() e OR(), os filtros também podem ser combinados com a chamada repetida de .filter():

q1 = Employee.query()  # A query that returns all employees
q2 = q1.filter(Employee.age >= 30)  # Only those over 30
q3 = q2.filter(Employee.age < 40)  # Only those in their 30s

Um atalho adicional está chamando .filter() com vários argumentos. Isso implica AND():

q1 = Employee.query()  # A query that returns all employees
q3 = q1.filter(Employee.age >= 30,
               Employee.age < 40)  # Only those in their 30s

E, por último, você também pode passar uma ou mais expressões de filtro diretamente para o método .query():

q3 = Employee.query(Employee.age >= 30,
                    Employee.age < 40)  # Only those in their 30s

Os objetos de consulta são imutáveis. Portanto, esses métodos sempre retornam um novo objeto Query. As chamadas acima para filter() não afetam q1. Por outro lado, as operações que são efetivamente de ambientes autônomos podem retornar o objeto Query original.

As ordens de classificação também podem ser combinadas dessa maneira. As chamadas de .filter() e .order() podem ser mescladas:

q4 = q3.order(-Employee.age)
q5 = q4.order(Employee.name)
q6 = q5.filter(Employee.rank == 5)

Várias chamadas .order() podem ser combinadas:

q5 = q3.order(-Employee.age, Employee.name)

A maneira mais simples de recuperar os resultados da consulta é com repetição:

for emp in q3:
  print emp.name, emp.age

Alguns outros métodos para executar uma consulta e acessar os respectivos resultados:

q.iter() # Return an iterator; same as iter(q) but more flexible
q.map(callback) # Call the callback function for each query result
q.fetch(N) # Return a list of the first N results
q.get() # Return the first result
q.count(N) # Return the number of results, with a maximum of N
q.fetch_page(N, start_cursor=cursor) # Return (results, cursor, has_more)

Todos os métodos acima usam um conjunto padrão de opções de consulta adicionais na forma de argumentos de palavra-chave, como keys_only=True, ou como objeto QueryOptions passado com options=QueryOptions(…). As opções de consulta mais importantes são estas:

  • keys_only: bool, se configurado, os resultados são chaves em vez de entidades.

  • limit: int, limita o número de resultados retornados.

  • offset: int, pula muitos resultados primeiro.

  • start_cursor: cursor, começa a retornar resultados após essa posição.

  • end_cursor: cursor, para de retornar resultados após essa posição.

  • batch_size: int, dica para o número de resultados retornados por RPC.

  • prefetch_size: int, dica para o número de resultados no primeiro RPC.

  • produce_cursors: bool, retorna objetos Cursor com os resultados.

Para opções de consulta adicionais (obscuras) e mais detalhes sobre elas, incluindo uma explicação sobre cursores, consulte datastore_query.py.

Todos os métodos acima, exceto iter(), também têm variantes assíncronas, que retornam um Future. Para ver o resultado final da operação, retorne o Future com yield (quando dentro de uma tasklet) ou chame o método get_result() do Future (fora de uma tasklet):

q.map_async(callback)  # Callback may be a task or a plain function
q.fetch_async(N)
q.get_async()
q.count_async(N)
q.fetch_page_async(N, start_cursor=cursor)

Por fim, há uma expressão para distribuir de maneira eficiente os resultados da consulta em uma tasklet, com yield adequado quando apropriado:

it = q.iter()
while (yield it.has_next_async()):
  emp = it.next()
  print emp.name, emp.age

Conteúdo

classe google.appengine.ext.ndb.query.Query(*args, **kwds)Fonte

Bases: object

Objeto Query.

Normalmente criado chamando-se Model.query().

Consulte o docstring do módulo para exemplos.

Nem todas as operações de Queries são aceitas por instâncias _MultiQuery. Estas últimas são geradas conforme necessário quando qualquer um dos operadores !=, IN ou OR é usado.

analyze()Fonte

Retorne uma lista que fornece os parâmetros obrigatórios por uma consulta.

ancestor

Acesso de ancestral (Key ou None).

app

Acesso de app (uma string ou None).

bind(*args, **kwds)Fonte

Associe valores de parâmetro. Retorna um novo objeto Query.

count(*args, **kwds)Fonte

Conte o número de resultados da consulta, até um limite.

Ele retorna o mesmo resultado de len(q.fetch(limit)), mas de maneira mais eficiente.

Você precisa passar um valor máximo para limitar o valor de trabalho feito pela consulta.

Parâmetros
  • limit: quantos resultados são contados no máximo.

  • **q_options: todos os argumentos de palavra-chave das opções de consulta são aceitos.

Retorna:

count_async(*args, **kwds)Fonte

Conte o número de resultados da consulta, até um limite.

Trata-se da versão assíncrona de Query.count().

default_options

Acesso de default_options (uma instância QueryOptions ou None).

fetch(*args, **kwds)Fonte

Busque uma lista de resultados da consulta, até um limite.

Parâmetros
  • limit: quantos resultados são recuperados no máximo.

  • **q_options: todos os argumentos de palavra-chave das opções de consulta são aceitos.

Retorna

Uma lista de resultados.

fetch_async(*args, **kwds)Fonte

Busque uma lista de resultados da consulta, até um limite.

Trata-se da versão assíncrona de Query.fetch().

fetch_page(*args, **kwds)Fonte

Busque uma página de resultados.

Este é um método especializado a ser usado paginando-se interfaces do usuário.

Parâmetros

page_size: o tamanho da página solicitado. Quantos resultados serão retornados no máximo.

Além disso, qualquer argumento de palavra-chave aceito pela classe QueryOptions é aceito. Em especial, para buscar a próxima página, você passa o cursor retornado por uma chamada para a próxima chamada usando start_cursor=<cursor>. Uma expressão comum é passar o cursor para o cliente usando <cursor>.to_websafe_string() e recriar esse cursor em uma solicitação subsequente usando Cursor.from_websafe_string(<string>).

Retorna

Uma tupla (results, cursor, more) na qual results é uma lista de resultados de consulta, cursor é um cursor que aponta logo após o último resultado retornado e more é um bool que indica se há (possivelmente) mais resultados depois disso.

fetch_page_async(*args, **kwds)Fonte

Busque uma página de resultados.

Trata-se da versão assíncrona de Query.fetch_page().

filter(*args)Fonte

Retorne uma nova consulta com filtros adicionais aplicados.

filters

Acesso de filtros (Node ou None).

get(**q_options)Fonte

Receba o primeiro resultado da consulta, caso haja algum.

Isso é semelhante a chamar q.fetch(1) e retornar o primeiro item da lista de resultados, caso haja algum, ou None.

Parâmetros

**q_options: todos os argumentos de palavra-chave das opções de consulta são aceitos.

Retorna

Um único resultado, ou None, caso não haja resultados.

get_async(**q_options)Fonte

Receba o primeiro resultado da consulta, caso haja algum.

Trata-se da versão assíncrona de Query.get().

group_by

Acesso de grupo por propriedades (uma instância de tupla ou None).

is_distinct

Verdadeiro, caso os resultados contenham um conjunto exclusivo de valores de propriedade.

Isso acontece quando todas as propriedades em group_by também estão na projeção.

iter(**q_options)Fonte

Crie um iterador na consulta.

Parâmetros

**q_options: todos os argumentos de palavra-chave das opções de consulta são aceitos.

Retorna

Um objeto QueryIterator.

kind

Acesso de tipo (uma string ou None).

map(*args, **kwds)Fonte

Mapeie uma função de retorno de chamada ou uma tasklet nos resultados da consulta.

Parâmetros
  • callback: uma função ou uma tasklet a ser aplicada a cada resultado. Consulte abaixo.

  • merge_future: subclasse Future opcional. Consulte abaixo.

  • **q_options: todos os argumentos de palavra-chave das opções de consulta são aceitos.

Assinatura de retorno: o retorno de chamada costuma ser chamado com uma entidade como argumento. No entanto, se keys_only=True for fornecido, ele será chamado com uma chave. Além disso, quando pass_batch_into_callback é True, ele é chamado com três argumentos: o lote atual, o índice dentro do lote e a entidade ou a Key nesse índice. O retorno de chamada pode retornar o que quiser. Se o retorno de chamada for None, um retorno de chamada trivial será considerado retornando somente a entidade ou a chave passada (ignorando produce_cursors).

Future de mesclagem opcional: merge_future é um argumento avançado que pode ser usado para modificar como os resultados de retorno de chamada são combinados no valor de retorno map() geral. Por padrão, uma lista de valores de retorno de chamada é produzida. Substituindo uma das poucas alternativas especializadas, você pode organizar de maneira contrária. Consulte as tasklets.MultiFuture da implementação padrão e uma descrição do objeto merge_future do protocolo precisam implementar o padrão. Entre as alternativas do mesmo módulo estão QueueFuture, SerialQueueFuture e ReducingFuture.

Retorna

Quando a consulta é executada até a conclusão e todas as são retornadas, map() retorna uma lista de resultados de todos os retornos de chamada. Porém, consulte "optional merge future" acima.

map_async(*args, **kwds)Fonte

Mapeie uma função de retorno de chamada ou uma tasklet nos resultados da consulta.

Trata-se da versão assíncrona de Query.map().

namespace

Acesso de namespace (uma string ou None).

order(*args)Fonte

Retorne uma nova consulta com pedidos de classificação adicionais aplicados.

orders

Acesso de filtros (uma datastore_query.Order ou None).

projection

Acesso de propriedades projetadas (uma instância de tupla ou None).

run_to_queue(*args, **kwds)Fonte

Execute esta consulta colocando entidades na fila indicada.

classe google.appengine.ext.ndb.query.QueryOptionsFonte

Bases: google.appengine.ext.ndb.context.ContextOptions, google.appengine.datastore.datastore_query.QueryOptions

Dê suporte a opções de contexto e consulta (esp. use_cache).

classe google.appengine.ext.ndb.query.Cursor(*args, **kwds)Fonte

Bases: google.appengine.datastore.datastore_query._BaseComponent

Uma classe imutável que representa uma posição relativa em uma consulta.

A posição denotada por um Cursor é relativa a um resultado em uma consulta, mesmo se o resultado tiver sido removido da consulta especificada. Normalmente para posicionar logo depois do último resultado retornado por um lote.

Um cursor só é usado em uma consulta com uma assinatura idêntica àquela que a produziu ou em uma consulta com a ordem de classificação inversa.

advance(offset, query, conn)Fonte

Avança um cursor pelo deslocamento especificado.

Parâmetros
  • offset: o valor para avançar a consulta atual

  • query: uma consulta idêntica àquela que criou este cursor

  • conn: o datastore_rpc.Connection a ser usado

Retorna

Um novo cursor avançado por deslocamento que usa a consulta fornecida.

static from_bytes(cursor)Fonte

Recebe um cursor dado o formulário serializado da string de byte dele.

A forma serializada de um cursor pode ser alterada de maneira não compatível com versões anteriores. Neste caso, os cursores precisam ser regenerados com base em uma nova solicitação Query.

Parâmetros

cursor: um cursor serializado conforme retornado por .to_bytes.

Retorna

Um cursor.

Gera
  • datastore_errors.BadValueError caso o argumento de cursor não represente um

  • cursor serializado.

static from_websafe_string(cursor)Fonte

Recebe um cursor dado o formulário serializado seguro para Web.

A forma serializada de um cursor pode ser alterada de maneira não compatível com versões anteriores. Neste caso, os cursores precisam ser regenerados com base em uma nova solicitação Query.

Parâmetros

cursor: um cursor serializado conforme retornado por .to_websafe_string.

Retorna

Um cursor.

Gera
  • datastore_errors.BadValueError caso o argumento do cursor não seja um tipo de

  • string ou não represente um cursor serializado.

reversed()Fonte

OBSOLETO. Não é mais necessário para chamar reversed() em cursores.

Um cursor retornado por uma consulta também pode ser usado em uma consulta com a ordem de classificação que foi revertida. Esse método retorna uma cópia do cursor original.

to_bytes()Fonte

Serialize o cursor como uma string de bytes.

to_websafe_string()Fonte

Serialize o cursor como uma string segura para a Web.

Retorna

Um cursor serializado codificado em base64.

urlsafe()Fonte

Serialize o cursor como uma string segura para a Web.

Retorna

Um cursor serializado codificado em base64.

classe google.appengine.ext.ndb.query.QueryIterator(*args, **kwds)Fonte

Bases: object

Este iterador funciona em autores de chamada síncronos e assíncronos.

Para autores de chamada síncronos, basta usar:

para entidade em Account.query():

<use entity>

Os autores de chamada assíncronos usam esta expressão:

it = iter(Account.query()) e (yield it.has_next_async()):

entity = it.next() <use entity>

Também é possível usar q.iter([options]), em vez de iter(q). Isso permite passar opções de consulta como keys_only ou produce_cursors.

Quando keys_only está definido, it.next() retorna uma chave, em vez de uma entidade.

Quando produce_cursors está definido, os métodos it.cursor_before() e it.cursor_after() retornam objetos Cursor correspondentes à posição de consulta pouco antes e logo depois do item retornado por it.next(). Antes de it.next() ser chamado pela primeira vez, ambos geram uma exceção. Quando o loop terminar, retorne o cursor depois do último item retornado. Chamar it.has_next() não afeta os cursores. Você precisa chamar it.next() para que os cursores se movam. Às vezes, solicitar um cursor exige ida e volta do Cloud Datastore (mas não se você acabar solicitando um cursor correspondente ao limite de lote). Caso produce_cursors não esteja definido, ambos os métodos sempre geram uma exceção.

As consultas que exigem a mesclagem na memória de várias consultas (ou seja, consultas que usem os operadores IN, != ou OR) não aceitam opções de consulta.

cursor_after()Fonte

Retorne o cursor após o item atual.

Você precisa passar um objeto QueryOptions com produce_cursors=True para que isso funcione.

Se não houver cursor ou item atual, gere BadArgumentError. Antes de next() retornar, não haverá cursor. Depois que o loop terminar, isso retornará o cursor depois do último item.

cursor_before()Fonte

Retorna o cursor antes do item atual.

Você precisa passar um objeto QueryOptions com produce_cursors=True para que isso funcione.

Se não houver cursor ou item atual, gere BadArgumentError. Antes de next() retornar, não haverá cursor. Depois que o loop terminar, isso retornará o cursor depois do último item.

has_next()Fonte

Retorne se um próximo item está disponível.

Consulte o docstring do módulo para o padrão de uso.

has_next_async(*args, **kwds)Fonte

Retorne um Future com um resultado que dirá se um próximo item está disponível.

Consulte o docstring do módulo para o padrão de uso.

index_list()Fonte

Retorne a lista de índices usados nesta consulta.

Ele retorna uma lista de representações de índice, em que uma representação do índice é igual à retornada por get_indexes().

Antes do primeiro resultado, as informações estão indisponíveis e None é retornado. Não se trata da mesma lista vazia: a lista vazia significa que nenhum índice foi usado para executar a consulta. Em dev_appserver, uma lista vazia também pode significar que somente índices internos foram usados. As consultas de metadados também retornam uma lista vazia aqui.

O uso apropriado é o seguinte:

q = <modelclass>.query(<filters>) i = q.iter() try:

i.next()

except Stopiteration:

pass

indexes = i.index_list() assert isinstance(indexes, list)

Observações: - Forçar produce_cursors=False faz isso retornar sempre None. - Isso sempre retorna None para várias consultas.

next()Fonte

Protocolo do iterador: receba o próximo item ou gere StopIteration.

probably_has_next()Fonte

Retorne se um próximo item está (provavelmente) disponível.

Ele não é igual a has_next(), porque, quando

produce_cursors é definido, alguns atalhos são possíveis. No entanto, em alguns casos (por exemplo, quando a consulta tem um post_filter), podemos receber um falso positivo (retorna True, mas next() vai gerar StopIteration). Não há falsos negativos.

classe google.appengine.ext.ndb.query.RepeatedStructuredPropertyPredicate(match_keys, pb, key_prefix)Fonte

Bases: google.appengine.datastore.datastore_query.FilterPredicate

google.appengine.ext.ndb.query.AND

alias de ConjunctionNode

google.appengine.ext.ndb.query.OU

alias de DisjunctionNode

classe google.appengine.ext.ndb.query.ConjunctionNodeFonte

Bases: google.appengine.ext.ndb.query.Node

Nó de árvore que representa um operador booleano AND em dois ou mais nós.

resolve(bindings, used)Fonte
classe google.appengine.ext.ndb.query.DisjunctionNodeFonte

Bases: google.appengine.ext.ndb.query.Node

Nó de árvore que representa um operador booleano OR em dois ou mais nós.

resolve(bindings, used)Fonte
classe google.appengine.ext.ndb.query.FilterNodeFonte

Bases: google.appengine.ext.ndb.query.Node

Nó de árvore para uma única expressão de filtro.

classe google.appengine.ext.ndb.query.PostFilterNodeFonte

Bases: google.appengine.ext.ndb.query.Node

Nó de árvore que representa uma operação de filtragem na memória.

Ele é usado para representar filtros que não podem ser executados pelo armazenamento de dados, por exemplo, uma consulta de um valor estruturado.

classe google.appengine.ext.ndb.query.FalseNodeFonte

Bases: google.appengine.ext.ndb.query.Node

Nó da árvore para um filtro de falha permanente.

classe google.appengine.ext.ndb.query.NodeFonte

Bases: object

Classe base para nós de árvore de expressão do filtro.

Os nós de árvore são considerados imutáveis, mesmo que contenham instâncias de Parameter, que não são. Em especial, duas árvores idênticas podem ser representadas pelo mesmo objeto Node em contextos diferentes.

resolve(bindings, used)Fonte

Retorne um Node com Parameters substituídos pelos valores selecionados.

Parâmetros
  • bindings: um dict que mapeia inteiros e strings para valores.

  • used: um dict com o uso de uma vinculação é registrado.

Retorna

Uma instância de Node.

classe google.appengine.ext.ndb.query.ParameterNodeFonte

Bases: google.appengine.ext.ndb.query.Node

Nó de árvore para um filtro parametrizado.

resolve(bindings, used)Fonte
classe google.appengine.ext.ndb.query.ParameterizedThingFonte

Bases: object

Classe base para Parameter e ParameterizedFunction.

Existe basicamente para verificações isinstance().

classe google.appengine.ext.ndb.query.Parameter(key)Fonte

Bases: google.appengine.ext.ndb.query.ParameterizedThing

Representa uma variável vinculada em uma consulta GQL.

Parameter(1) corresponde a um slot identificado “:1” em uma consulta GQL. Parameter(‘xyz’) corresponde a um slot identificado “:xyz”.

O valor precisa ser definido (vinculado) separadamente chamando .set(value).

key

Recupere a chave.

resolve(bindings, used)Fonte
classe google.appengine.ext.ndb.query.ParameterizedFunction(func, values)Fonte

Bases: google.appengine.ext.ndb.query.ParameterizedThing

Representa uma função GQL com argumentos parametrizados.

Por exemplo, ParameterizedFunction(‘key’, [Parameter(1)]) significa a sintaxe GQL KEY(:1).

func
is_parameterized()Fonte
resolve(bindings, used)Fonte
values
google.appengine.ext.ndb.query.gql(query_string, *args, **kwds)Fonte

Analise uma string de consulta GQL.

Parâmetros
  • query_string: consulta GQL completa. Por exemplo, ‘SELECT * FROM Kind WHERE prop = 1’.

  • **kwds (*args,) –

    Caso esteja presente, é usado para chamar bind().

Retorna

Uma instância de query_class.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Ambiente padrão do App Engine para Python 2