O Python 2.7 atingiu o fim do suporte e vai ser descontinuado a 31 de janeiro de 2026. Após a descontinuação, não vai poder implementar aplicações Python 2.7, mesmo que a sua organização tenha usado anteriormente uma política organizacional para reativar as implementações de runtimes antigos. As suas aplicações Python 2.7 existentes vão continuar a ser executadas e a receber tráfego após a data de descontinuação. Recomendamos que migre para a versão suportada mais recente do Python.

Esta página foi traduzida pela API Cloud Translation.

A classe GqlQuery

Nota: os programadores que criam novas aplicações são fortemente aconselhados a usar a biblioteca de cliente NDB, que tem várias vantagens em comparação com esta biblioteca de cliente, como o armazenamento em cache automático de entidades através da API Memcache. Se estiver a usar atualmente a biblioteca cliente DB mais antiga, leia o guia de migração de DB para NDB

A classe GqlQuery representa uma consulta para obter entidades do App Engine Datastore através da linguagem de consulta do App Engine semelhante a SQL, GQL. Para uma discussão completa da sintaxe e das funcionalidades da GQL, consulte a referência da GQL. Consulte também a classe relacionada Query, que usa objetos e métodos, em vez da GQL, para preparar consultas.

GqlQuery está definido no módulo google.appengine.ext.db.

Nota: o mecanismo de consulta baseado em índice suporta uma vasta gama de consultas e é adequado para a maioria das aplicações. No entanto, não suporta alguns tipos de consultas comuns noutras tecnologias de bases de dados. Em particular, as junções e as consultas agregadas não são suportadas no motor de consultas do Datastore. Consulte a página Consultas do Datastore para ver as limitações das consultas do Datastore.

Introdução

Uma aplicação cria um objeto de consulta GQL chamando diretamente o construtor GqlQuery ou o método de classe gql() de uma classe de modelo de tipo de entidade. O construtor GqlQuery recebe como argumento uma string de consulta,uma instrução GQL completa que começa com SELECT ... FROM model-name. Os valores nas cláusulas WHERE podem ser literais numéricos ou de string, ou podem usar a associação de parâmetros para valores. Os parâmetros podem ser associados através de argumentos posicionais ou de palavras-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")

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

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

Em seguida, a aplicação pode executar a consulta e aceder aos resultados de qualquer uma das seguintes formas:

Trate o objeto de consulta como um objeto iterável para processar as entidades correspondentes uma de cada vez:
```
for song in q:
  print song.title
```
Isto chama implicitamente o método run() da consulta para gerar as entidades correspondentes. Assim, é equivalente a
```
for song in q.run():
  print song.title
```
Pode definir um limite para o número de resultados a processar 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, pelo que a criação de 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 obter a primeira entidade correspondente única encontrada no Datastore:
```
song = q.get()
print song.title
```
Chame o método fetch() da consulta para obter 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
```
Tal como acontece com run(), o objeto de consulta não armazena em cache os resultados, pelo que chamar fetch() uma segunda vez volta a emitir a mesma consulta.

Nota: raramente deve usar este método. Quase sempre é melhor usar run() em alternativa.

Construtor

O construtor da classe GqlQuery é definido da seguinte forma:

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

Cria uma instância da classe GqlQuery para obter entidades do App Engine Datastore através da linguagem de consulta GQL.

Argumentos

query_string: String que contém uma declaração GQL completa.
args: Valores dos parâmetros posicionais.
kwds: Valores dos parâmetros de palavras-chave.

Métodos de instância

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

bind (*args, **kwds)

Reassocia os valores dos parâmetros da consulta. A consulta modificada é executada na primeira vez que os resultados são acedidos depois de os respetivos parâmetros terem sido atualizados.

A associação de parâmetros a um objeto GqlQuery existente é mais rápida do que a criação de um novo objeto GqlQuery, porque a string de consulta não precisa de ser analisada novamente.

Argumentos

args: Novos valores de parâmetros posicionais.
kwds: Novos valores de parâmetros de palavras-chave.

projection ()

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

is_keys_only ()

Devolve um valor booleano que indica se a consulta é uma consulta apenas 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)

Devolve um iterável para percorrer os resultados da consulta. Isto permite-lhe especificar a operação da consulta com definições de parâmetros e aceder aos resultados de forma iterativa:

Obtém e rejeita o número de resultados especificado pelo argumento offset.
Obtém e devolve até ao número máximo de resultados especificado pelo argumento limit.

Assim, o desempenho do ciclo é dimensionado linearmente com a soma de offset + limit. Se souber quantos resultados quer obter, deve definir sempre um valor limit explícito.

Este método usa a obtenção prévia assíncrona para melhorar o desempenho. Por predefinição, obtém os respetivos resultados do Datastore em pequenos lotes, o que permite à aplicação parar a iteração e evitar a obtenção de mais resultados do que os necessários.

Sugestão: para obter todos os resultados disponíveis quando o respetivo número é desconhecido, defina batch_size para um valor elevado, como 1000.

Dica: se não precisar de alterar os valores dos argumentos predefinidos, pode usar o objeto de consulta diretamente como um iterável para controlar o ciclo. Isto chama implicitamente run() com argumentos predefinidos.

Argumentos

read_policy

Leia a política que especifica o nível de consistência de dados pretendido:

STRONG_CONSISTENCY: Garante os resultados mais recentes, mas está limitado a um único grupo de entidades.
EVENTUAL_CONSISTENCY: Pode abranger vários grupos de entidades, mas, ocasionalmente, pode devolver resultados desatualizados. Em geral, as consultas eventualmente consistentes são executadas mais rapidamente do que as consultas fortemente consistentes, mas não existe qualquer garantia.

Nota: as consultas globais (não antecessoras) ignoram este argumento.

deadline

Tempo máximo, em segundos, de espera para que o Datastore devolva um resultado antes de anular com um erro. Aceita um número inteiro ou um valor de vírgula flutuante. Não pode ser definido acima do valor predefinido (60 segundos), mas pode ser ajustado para baixo para garantir que uma operação específica falha rapidamente (por exemplo, para devolver uma resposta mais rápida ao utilizador, repetir a operação, experimentar uma operação diferente ou adicionar a operação a uma fila de tarefas).

offset

Número de resultados a ignorar antes de devolver o primeiro.

limit

Número máximo de resultados a devolver. Se este parâmetro for omitido, é usado o valor especificado na cláusula LIMIT da string de consulta GQL. Se for explicitamente definido como None, são obtidos todos os resultados disponíveis.

batch_size

Número de resultados a tentar obter por lote. Se limit estiver definido, a predefinição é o limite especificado. Caso contrário, a predefinição é 20.

keys_only

Se true, devolve apenas chaves em vez de entidades completas. As consultas apenas com chaves são mais rápidas e baratas do que as que devolvem entidades completas.

projeção

Lista ou tuplo de nomes de propriedades a devolver. Apenas são devolvidas as entidades que possuem as propriedades especificadas. Se não for especificado, são devolvidas entidades completas por predefinição. As consultas de projeção são mais rápidas e baratas do que as que devolvem entidades completas.

Nota: a especificação deste parâmetro pode alterar os requisitos de índice da consulta.

start_cursor

Posição do cursor na qual iniciar a consulta.

end_cursor

Posição do cursor na qual terminar a consulta.

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

Executa a consulta e devolve o primeiro resultado ou None se não forem encontrados resultados. É obtido, no máximo, um resultado do Datastore; a cláusula LIMIT da string de consulta GQL, se existir, é ignorada.

Argumentos

read_policy

Leia a política que especifica o nível de consistência de dados pretendido:

STRONG_CONSISTENCY: Garante os resultados mais recentes, mas está limitado a um único grupo de entidades.
EVENTUAL_CONSISTENCY: Pode abranger vários grupos de entidades, mas, ocasionalmente, pode devolver resultados desatualizados. Em geral, as consultas eventualmente consistentes são executadas mais rapidamente do que as consultas fortemente consistentes, mas não existe qualquer garantia.

Nota: as consultas globais (não antecessoras) ignoram este argumento.

deadline

offset

Número de resultados a ignorar antes de devolver o primeiro.

keys_only

Se true, devolve apenas chaves em vez de entidades completas. As consultas apenas com chaves são mais rápidas e baratas do que as que devolvem entidades completas.

projeção

Nota: a especificação deste parâmetro pode alterar os requisitos de índice da consulta.

start_cursor

Posição do cursor na qual iniciar a consulta.

end_cursor

Posição do cursor na qual terminar a consulta.

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 devolve uma lista (possivelmente vazia) de resultados:

Obtém e rejeita o número de resultados especificado pelo argumento offset.
Obtém e devolve até ao número máximo de resultados especificado pelo argumento limit.

Assim, o desempenho do método é dimensionado linearmente com a soma de offset + limit.

Nota: este método é apenas uma pequena união em torno do método run(), e é menos eficiente e requer mais memória do que usar run() diretamente. Raramente precisa de usar fetch(). Este elemento é fornecido principalmente por conveniência nos casos em que precisa de obter uma lista completa na memória dos resultados da consulta.

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

Argumentos

limit

Número máximo de resultados a devolver. Se estiver definido como None, são obtidos todos os resultados disponíveis.

read_policy

Leia a política que especifica o nível de consistência de dados pretendido:

STRONG_CONSISTENCY: Garante os resultados mais recentes, mas está limitado a um único grupo de entidades.
EVENTUAL_CONSISTENCY: Pode abranger vários grupos de entidades, mas, ocasionalmente, pode devolver resultados desatualizados. Em geral, as consultas eventualmente consistentes são executadas mais rapidamente do que as consultas fortemente consistentes, mas não existe qualquer garantia.

Nota: as consultas globais (não antecessoras) ignoram este argumento.

deadline

offset

Número de resultados a ignorar antes de devolver o primeiro.

keys_only

Se true, devolve apenas chaves em vez de entidades completas. As consultas apenas com chaves são mais rápidas e baratas do que as que devolvem entidades completas.

projeção

Nota: a especificação deste parâmetro pode alterar os requisitos de índice da consulta.

start_cursor

Posição do cursor na qual iniciar a consulta.

end_cursor

Posição do cursor na qual terminar a consulta.

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

Devolve o número de resultados que correspondem à consulta. Isto é mais rápido por um fator constante do que obter realmente todos os resultados, mas o tempo de execução continua a ser dimensionado linearmente com a soma de offset + limit. A menos que se espere que a contagem de resultados seja pequena, é melhor especificar um argumento limit; caso contrário, o método continua até terminar a contagem ou expirar o tempo.

Argumentos

read_policy

Leia a política que especifica o nível de consistência de dados pretendido:

STRONG_CONSISTENCY: Garante os resultados mais recentes, mas está limitado a um único grupo de entidades.
EVENTUAL_CONSISTENCY: Pode abranger vários grupos de entidades, mas, ocasionalmente, pode devolver resultados desatualizados. Em geral, as consultas eventualmente consistentes são executadas mais rapidamente do que as consultas fortemente consistentes, mas não existe qualquer garantia.

Nota: as consultas globais (não antecessoras) ignoram este argumento.

deadline

offset

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

limit

Número máximo de resultados a contabilizar.

Nota: se for especificado explicitamente, este parâmetro substitui qualquer valor definido na cláusula LIMIT da string de consulta GQL. No entanto, se o parâmetro for omitido, o valor predefinido de 1000 não substitui a cláusula LIMIT da consulta GQL e aplica-se apenas se não tiver sido especificada nenhuma cláusula LIMIT.

start_cursor

Posição do cursor na qual iniciar a consulta.

end_cursor

Posição do cursor na qual terminar a consulta.

index_list ()

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

Atenção: invocar este método numa consulta que ainda não foi executada gera uma exceção AssertionError.

Nota: esta funcionalidade não é totalmente suportada 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 seguinte 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 />")

Isto produz resultados semelhantes aos seguintes para cada índice:

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

cursor ()

Devolve uma string de cursor codificada em base64 que indica a posição no conjunto de resultados da consulta após o último resultado obtido. A string do cursor é segura para utilização 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 esta string através do parâmetro start_cursor ou do método with_cursor() para retomar a obtenção de resultados a partir desta posição.

Atenção: invocar este método numa consulta que ainda não foi executada gera uma exceção AssertionError.

Nota: nem todas as consultas são compatíveis com cursores. Consulte a página Consultas do Datastore para mais informações.

with_cursor (start_cursor, end_cursor=None)

Especifica as posições de início e (opcionalmente) de fim no conjunto de resultados de uma consulta a partir das quais obter resultados. As strings do cursor que denotam as posições inicial e final podem ser obtidas chamando cursor() após uma invocação anterior da consulta. A consulta atual tem de ser idêntica à invocação anterior, incluindo o tipo de entidade, os filtros de propriedades, os filtros de antepassados e as ordens de ordenação.

Argumentos

start_cursor: String do cursor codificada em Base64 que especifica onde iniciar a consulta.
end_cursor: String do cursor codificada em Base64 que especifica onde terminar a consulta.

A classe GqlQuery Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Introdução

Construtor

Métodos de instância

A classe GqlQuery