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 Query

Observação: os desenvolvedores que criam novos aplicativos são bastante incentivados a usar a biblioteca de cliente do NDB, que oferece diversos benefícios em comparação a esta biblioteca de cliente, como armazenamento em cache automático de entidades por meio da API Memcache. Se você estiver usando a antiga biblioteca de cliente DB, leia o Guia de migração de DB para NDB.

A classe Query representa uma consulta para recuperar entidades do App Engine Datastore. Consulte também a classe relacionada GqlQuery, que define as consultas usando GQL, uma linguagem de consulta semelhante a SQL.

Query é definido no módulo google.appengine.ext.db.

Observação: o mecanismo de consulta baseado em índice é compatível com uma grande variedade de consultas e adequado à maioria dos aplicativos. No entanto, ele não aceita alguns tipos de consulta comuns em outras tecnologias de banco de dados. Especificamente, mesclagens e consultas agregadas não são compatíveis com o mecanismo de consulta do Datastore. Para conhecer as limitações das consultas do Datastore, consulte a página Consultas do Datastore.

Introdução

Um aplicativo cria um objeto de consulta para um determinado tipo de entidade ao chamar o construtor Query diretamente

class Song(db.Model):
  title = db.StringProperty()
  composer = db.StringProperty()
  date = db.DateTimeProperty()

q = db.Query(Song)

ou o método de classe all() da classe de modelo do tipo:

q = Song.all()

Sem mais modificações, a instância resultante da classe Query recupera todas as entidades existentes do tipo especificado. As chamadas de método no objeto podem ser usadas para personalizar a consulta com critérios de filtro adicionais, condições de ancestral e ordens de classificação:

q.filter('title =', 'Imagine')
q.ancestor(ancestor_key)
q.order('-date')

Por conveniência, todos esses métodos retornam o próprio objeto de consulta para que possam ser colocados em cascata em uma única instrução:

q.filter('title =', 'Imagine').ancestor(key).order('-date')

O aplicativo pode, então, executar a consulta e acessar os resultados de uma das seguintes maneiras:

Trate o objeto de consulta como iterável, para processar entidades correspondentes uma por vez:
```
for song in q:
  print song.title
```
Isso chama implicitamente o método run() da consulta para gerar as entidades correspondentes. Sendo assim, é equivalente a
```
for song in q.run():
  print song.title
```
é possível definir um limite para o número de resultados a serem processados com o argumento de palavra-chave limit:
```
for song in q.run(limit=5):
  print song.title
```
A interface do iterador não armazena em cache os resultados. Portanto, criar um novo iterador a partir do objeto de consulta reitera a mesma consulta desde o início.
Chame o método get() da consulta para receber a primeira entidade correspondente encontrada no Datastore:
```
song = q.get()
print song.title
```
Chame o método fetch() da consulta para receber uma lista de todas as entidades correspondentes até um número especificado de resultados:
```
results = q.fetch(limit=5)
for song in results:
  print song.title
```
Assim como com run(), o objeto de consulta não armazena em cache os resultados. Portanto, chamar fetch() uma segunda vez reedita a mesma consulta.

Observação: raramente será necessário usar esse método. Em quase todas as ocasiões, é recomendável utilizar run() .

Construtor

O construtor da classe Query é definido da seguinte maneira:

class Query (model_class=None, keys_only=False, cursor=None, namespace=None, projection=None, distinct=False)

Cria uma instância da classe Query para recuperar entidades do App Engine Datastore.

Sem modificação adicional, o objeto de consulta resultante recuperará todas as entidades existentes do tipo especificado por model_class. Os métodos de instância filter(), ancestor(), e order() podem ser usados para personalizar a consulta com critérios de filtro adicionais, condições de ancestral e ordens de classificação.

Argumentos

model_class

A classe Model (ou Expando) que representa o tipo de entidade ao qual a consulta se aplica.

keys_only

truetrue, retornará apenas chaves em vez de entidades completas. As consultas somente de chaves são mais rápidas e mais baratas do que aquelas que retornam entidades completas.

cursor

Posição do cursor de onde a consulta será retomada.

namespace

Namespace a ser usado para a consulta.

projection

Lista ou tupla de nomes de propriedades a serem retornados. Somente entidades com as propriedades especificadas serão retornadas. Se não especificado, entidades inteiras serão retornadas por padrão. As consultas de projeção são mais rápidas e mais baratas do que aquelas que retornam entidades completas.

Observação: especificar este parâmetro pode alterar os requisitos de índice da consulta.

distinct

No caso de Consultas de projeção, distinct=True especifica que somente resultados totalmente exclusivos serão retornados em um conjunto de resultados. Isso retornará apenas o primeiro resultado de entidades com os mesmos valores das propriedades projetadas.

True: Retorna somente o primeiro resultado para cada conjunto distinto de valor para propriedades na projeção.
False: Todos os resultados são retornados.

Métodos da instância

As instâncias de classe Query têm os seguintes métodos:

filter (property_operator, value)

Adiciona um filtro de propriedade à consulta. A consulta retornará apenas entidades com propriedades que satisfazem a todos os filtros.

Argumentos

property_operator

String que consiste em um nome de propriedade e um operador de comparação opcional (=, !=, <, <=, >, >=, IN), separados por um espaço: por exemplo, 'age >'. Se apenas um nome de propriedade for especificado sem um operador de comparação, o filtro fará a comparação de igualdade (=) por padrão.

value

Valor a comparar com o valor da propriedade. Exemplo:

q.filter('height >', 42).filter('city =', 'Seattle')
q.filter('user =', users.get_current_user())

O valor de comparação especificado precisa ser do mesmo tipo de valor que o da propriedade que está sendo comparada.

ancestor (ancestor)

Adiciona um filtro ancestral à consulta. A consulta retornará apenas entidades com o ancestral especificado.

Argumento

ancestor: Entidade ou chave ancestral.

order (property)

Adiciona uma ordem de classificação à consulta. Se mais de uma ordem de classificação for adicionada, elas serão aplicadas na ordem especificada.

Argumento

property

String que fornece o nome da propriedade na qual classificar, opcionalmente precedido por um hífen (-) para especificar a ordem decrescente. Omitir o hífen especifica a ordem crescente por padrão. Exemplo:

# Order alphabetically by last name:
q.order('last_name')

# Order by height, tallest to shortest:
q.order('-height')

projection ()

Retorna a tupla de propriedades na projeção ou None.

is_keys_only ()

Retorna um valor booleano indicando se a consulta é somente de chaves.

run (read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, limit=None, batch_size=20, keys_only=False, projection=None, start_cursor=None, end_cursor=None)

Retorna um iterável para loop nos resultados da consulta. Isso permite que você especifique a operação da consulta com configurações de parâmetro e acesse os resultados de maneira iterativa:

Recupera e descarta o número de resultados especificado pelo argumento offset.
Recupera e retorna até o número máximo de resultados especificado pelo argumento limit.

O desempenho do loop, portanto, se ajusta à soma de offset + limit. Se você souber quantos resultados quer recuperar, deverá sempre definir um valor limit explícito.

Esse método usa pré-busca assíncrona para melhorar o desempenho. Por padrão, ele recupera seus resultados do Datastore em pequenos lotes, permitindo que o aplicativo interrompa a iteração e evite o recebimento de mais resultados do que o necessário.

Dica: para recuperar todos os resultados disponíveis quando o número é desconhecido, defina batch_size como um valor grande, por exemplo, 1000.

Dica: se você não precisa alterar os valores de argumento padrão, basta usar o objeto de consulta diretamente como um iterável para controlar o loop. Isso implicitamente chama run() com argumentos padrão.

Argumentos

read_policy

Política de leitura que especifica o nível desejado de consistência de dados:

STRONG_CONSISTENCY: Garante os resultados mais recentes, mas limitados a um único grupo de entidades.
EVENTUAL_CONSISTENCY: Abrange diversos grupos de entidades, mas de vez em quando retorna resultados obsoletos. Em geral, as consultas de consistência eventual são executadas mais rapidamente do que as de consistência forte, mas não há garantias.

Observação: consultas globais (não ancestrais) ignoram esse argumento.

deadline

Tempo máximo de espera, em segundos, para que o Datastore retorne um resultado antes de cancelar com um erro. Aceita um número inteiro ou um valor de ponto flutuante. Não é aumentado além do valor padrão de 60 segundos, mas diminuído para garantir que uma determinada operação falhe rapidamente. Por exemplo, para retornar uma resposta mais rápida ao usuário, repita a operação, tente uma operação diferente ou adicione essa operação a uma fila de tarefas.

offset

Número de resultados a pular antes de retornar o primeiro.

limit

Número máximo de resultados a serem retornados. Se omitido ou definido como None, todos os resultados disponíveis serão recuperados por padrão.

batch_size

Número de resultados a tentar recuperar por lote. Se limit for definido, o padrão será o limite especificado. Caso contrário, o padrão será 20.

keys_only

truetrue, retornará apenas chaves em vez de entidades completas. As consultas somente de chaves são mais rápidas e mais baratas do que aquelas que retornam entidades completas.

projection

Observação: especificar este parâmetro pode alterar os requisitos de índice da consulta.

start_cursor

Posição do cursor em que a consulta será iniciada.

end_cursor

Posição do cursor em que a consulta será encerrada.

get (read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, keys_only=False, projection=None, start_cursor=None, end_cursor=None)

Executa a consulta e retorna o primeiro resultado ou None, se nenhum resultado for encontrado.

Argumentos

read_policy

Política de leitura que especifica o nível desejado de consistência de dados:

STRONG_CONSISTENCY: Garante os resultados mais recentes, mas limitados a um único grupo de entidades.
EVENTUAL_CONSISTENCY: Abrange diversos grupos de entidades, mas de vez em quando retorna resultados obsoletos. Em geral, as consultas de consistência eventual são executadas mais rapidamente do que as de consistência forte, mas não há garantias.

Observação: consultas globais (não ancestrais) ignoram esse argumento.

deadline

offset

Número de resultados a pular antes de retornar o primeiro.

keys_only

truetrue, retornará apenas chaves em vez de entidades completas. As consultas somente de chaves são mais rápidas e mais baratas do que aquelas que retornam entidades completas.

projection

Observação: especificar este parâmetro pode alterar os requisitos de índice da consulta.

start_cursor

Posição do cursor em que a consulta será iniciada.

end_cursor

Posição do cursor em que a consulta será encerrada.

fetch (limit, read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, keys_only=False, projection=None, start_cursor=None, end_cursor=None)

Executa a consulta e retorna uma lista (possivelmente vazia) de resultados:

Recupera e descarta o número de resultados especificado pelo argumento offset.
Recupera e retorna até o número máximo de resultados especificado pelo argumento limit.

O desempenho do método, portanto, se ajusta à soma de offset + limit.

Observação: esse método é só um encapsulamento fino em torno do método run(). Ele é menos eficiente e consome muito mais memória quando comparado ao uso de run() diretamente. Raramente é necessário usar fetch(). Ele é fornecido principalmente por comodidade, nos casos em que é necessário recuperar da memória uma lista completa de resultados da consulta.

Dica: o método fetch() foi desenvolvido para recuperar apenas o número de resultados especificado pelo argumento limit. Para recuperar todos os resultados disponíveis de uma consulta quando o número é desconhecido, use run() com um tamanho grande de lote, como run(batch_size=1000), em vez de fetch().

Argumentos

limit

Número máximo de resultados a serem retornados. Se definido como None, todos os resultados disponíveis serão recuperados.

read_policy

Política de leitura que especifica o nível desejado de consistência de dados:

STRONG_CONSISTENCY: Garante os resultados mais recentes, mas limitados a um único grupo de entidades.
EVENTUAL_CONSISTENCY: Abrange diversos grupos de entidades, mas de vez em quando retorna resultados obsoletos. Em geral, as consultas de consistência eventual são executadas mais rapidamente do que as de consistência forte, mas não há garantias.

Observação: consultas globais (não ancestrais) ignoram esse argumento.

deadline

offset

Número de resultados a pular antes de retornar o primeiro.

keys_only

truetrue, retornará apenas chaves em vez de entidades completas. As consultas somente de chaves são mais rápidas e mais baratas do que aquelas que retornam entidades completas.

projection

Observação: especificar este parâmetro pode alterar os requisitos de índice da consulta.

start_cursor

Posição do cursor em que a consulta será iniciada.

end_cursor

Posição do cursor em que a consulta será encerrada.

count (read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, limit=1000, start_cursor=None, end_cursor=None)

Retorna o número de resultados que correspondem à consulta. Isso é mais rápido por um fator constante do que realmente recuperar todos os resultados, mas o tempo de execução ainda se ajusta à soma de offset + limit de modo linear. A menos que seja esperada uma contagem de resultados pequena, é melhor especificar um argumento limit. Caso contrário, o método continuará até terminar a contagem ou expirar.

Argumentos

read_policy

Política de leitura que especifica o nível desejado de consistência de dados:

STRONG_CONSISTENCY: Garante os resultados mais recentes, mas limitados a um único grupo de entidades.
EVENTUAL_CONSISTENCY: Abrange diversos grupos de entidades, mas de vez em quando retorna resultados obsoletos. Em geral, as consultas de consistência eventual são executadas mais rapidamente do que as de consistência forte, mas não há garantias.

Observação: consultas globais (não ancestrais) ignoram esse argumento.

deadline

offset

Número de resultados a pular antes de contar o primeiro.

limit

Número máximo de resultados a serem contados.

start_cursor

Posição do cursor em que a consulta será iniciada.

end_cursor

Posição do cursor em que a consulta será encerrada.

index_list ()

Retorna uma lista de índices usados por uma consulta executada, incluindo índices principais, compostos, tipo e propriedade única.

Cuidado: invocar esse método em uma consulta que ainda não foi executada gerará uma exceção AssertionError .

Observação: esse recurso não é totalmente compatível no servidor de desenvolvimento. Quando usado com o servidor de desenvolvimento, o resultado é a lista vazia ou uma lista que contém exatamente um índice composto.

Por exemplo, o código a seguir imprime várias informações sobre os índices usados por uma consulta:

# other imports ...
import webapp2
from google.appengine.api import users
from google.appengine.ext import db

class Greeting(db.Model):
  author = db.StringProperty()
  content = db.StringProperty(multiline=True)
  date = db.DateTimeProperty(auto_now_add=True)

class MainPage(webapp2.RequestHandler):
  def get(self):
    user = users.get_current_user()
    q = db.Query(Greeting)
    q.filter("author =", user.user_id())
    q.order("-date")
    q.fetch(100)
    index_list = q.index_list()
    for ix in index_list:
      self.response.out.write("Kind: %s" % ix.kind())
      self.response.out.write("<br />")
      self.response.out.write("Has ancestor? %s" % ix.has_ancestor())
      self.response.out.write("<br />")
      for name, direction in ix.properties():
        self.response.out.write("Property name: "+name)
        self.response.out.write("<br />")
        if direction == db.Index.DESCENDING:
          self.response.out.write("Sort direction: DESCENDING")
        else:
          self.response.out.write("Sort direction: ASCENDING")
        self.response.out.write("<br />")

Isso produz uma saída como esta para cada índice:

Kind: Greeting
Has ancestor? False
Property name: author
Sort direction: ASCENDING
Property name: date
Sort direction: DESCENDING

cursor ()

Retorna uma string de cursor codificada em base64 denotando a posição no conjunto de resultados da consulta após o último resultado recuperado. A string de cursor é segura para usar nos parâmetros HTTP GET e POST e também pode ser armazenada no Datastore ou no Memcache. Uma invocação futura da mesma consulta pode fornecer essa string por meio do parâmetro start_cursor ou do método with_cursor() para retomar a recuperação dos resultados dessa posição.

Cuidado: invocar esse método em uma consulta que ainda não foi executada gerará uma exceção AssertionError .

Observação: nem todas as consultas são compatíveis com cursores. Para mais informações, confira a página Consultas do Datastore.

with_cursor (start_cursor, end_cursor=None)

Especifica as posições inicial e final (opcional) no conjunto de resultados de uma consulta a partir da qual os resultados são recuperados. Para conseguir as strings de cursor referentes às posições inicial e final, chame cursor() após uma invocação anterior da consulta. A consulta atual precisa ser idêntica à chamada anterior, incluindo o tipo de entidade, filtros de propriedade, filtros de ancestral e ordens de classificação.

Argumentos

start_cursor: String de cursor codificada em base64 que especifica o ponto de início da consulta.
end_cursor: String de cursor codificada em base64 que especifica o ponto de término da consulta.