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.

A classe GqlQuery

Observação: é altamente recomendável a desenvolvedores que criam novos aplicativos usar a biblioteca de cliente NDB, porque ela oferece diversos benefícios em comparação com 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 GqlQuery representa uma consulta que recupera entidades do App Engine Datastore usando a linguagem de consulta do App Engine semelhante ao SQL, o GQL. Para encontrar os tópicos completos sobre a sintaxe e os recursos dessa linguagem, consulte a Referência do GQL. Veja também a classe Query relacionada. Em vez do GQL, ela usa objetos e métodos para preparar consultas.

GqlQuery é 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

Para criar um objeto de consulta GQL, o aplicativo chama diretamente o construtor GqlQuery ou o método de classe gql() de uma classe de modelo de um tipo de entidade. O construtor GqlQuery utiliza como argumento uma string de consulta, uma instrução GQL completa que começa com SELECT ... FROM model-name. Os valores em cláusulas WHERE podem ser literais numéricos ou de string ou podem usar a vinculação de parâmetro para valores. Os parâmetros podem ser vinculados com o uso de argumentos posicionais ou de palavra-chave:

q = GqlQuery("SELECT * FROM Song WHERE composer = 'Lennon, John'")

q = GqlQuery("SELECT __key__ FROM Song WHERE composer = :1", "Lennon, John")

q = GqlQuery("SELECT * FROM Song WHERE composer = :composer", composer="Lennon, John")

Por conveniência, as classes Model e Expando têm um método de classe gql() que retorna uma instância GqlQuery. Esse método usa uma string de consulta GQL sem o prefixo SELECT ... FROM model-name, que está implícito:

q = Song.gql("WHERE composer = 'Lennon, John'")

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 GqlQuery é definido da seguinte maneira:

class GqlQuery (query_string, *args, **kwds)

Cria uma instância da classe GqlQuery para recuperar entidades do App Engine Datastore usando a linguagem de consulta GQL.

Argumentos

query_string: String que contém uma instrução GQL completa.
args: Valores de parâmetro posicionais.
kwds: Valores de parâmetro de palavra-chave.

Métodos de instância

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

bind (*args, **kwds)

Vincula novamente os valores de parâmetro da consulta. A consulta modificada será executada na primeira vez em que os resultados forem acessados, depois que os parâmetros tiverem sido vinculados novamente.

Vincular novamente parâmetros a um objeto GqlQuery existente é mais rápido do que criar um novo objeto GqlQuery, porque a string de consulta não precisa ser reanalisada.

Argumentos

args: Novos valores de parâmetro posicionais.
kwds: Novos valores de parâmetro de palavra-chave.

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 este parâmetro for omitido, o valor especificado na cláusula LIMIT da string de consulta GQL será usado. Se definido explicitamente como None, todos os resultados disponíveis serão recuperados.

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

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.

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. No máximo, um resultado é recuperado do Datastore. A cláusula LIMIT da string de consulta GQL, se houver, será ignorada.

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 contar.

Observação: se especificado explicitamente, esse parâmetro modificará qualquer valor definido na cláusula LIMIT da string de consulta GQL. No entanto, se o parâmetro for omitido, o valor padrão de 1000 não modificará a cláusula LIMIT da consulta GQL e só será aplicado se nenhuma cláusula LIMIT tiver sido especificada.

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