My favorites | Português | Sign in

A classe GqlQuery

A classe GqlQuery é uma interface de consulta ao armazenamento de dados que utiliza a linguagem de consulta GQL do Google App Engine.

GqlQuery é fornecida pelo módulo google.appengine.ext.db.

Introdução

GQL é uma linguagem de consulta semelhante a SQL, adequada para consultas no armazenamento de dados do Google App Engine. Leia uma discussão completa sobre a sintaxe e os recursos de GQL na Referência sobre GQL.

O construtor de GqlQuery assume como argumento uma instrução completa de GQL que começa com SELECT * FROM model-name. Os valores das cláusulas WHERE podem ser string ou literais de número, ou podem utilizar vinculação de parâmetro para os valores. Os parâmetros podem ser vinculados inicialmente usando argumentos de posição ou palavra-chave para o construtor.

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

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

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

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

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

Assim como na classe Query, o aplicativo executa a consulta e acessa os resultados chamando o método fetch() ou tratando o objeto GqlQuery como iterável. Para obter mais informações, consulte a documentação sobre Query.

Há uma diferença na forma como Query e GqlQuery acessam os resultados: se a consulta GQL incluir uma cláusula LIMIT ou OFFSET, os resultados são recuperados como no método fetch() equivalente, mesmo que a interface do iterador seja usada para acessar os resultados. Quando uma GqlQuery cujo GQL contém LIMIT ou OFFSET é usada como iterável, é realizada uma chamada ao armazenamento de dados para obter todos os resultados e o iterador retorna cada um dos resultados da memória.

for song in q:
  print song.title

Veja também Query, uma classe de consulta que utiliza objetos e métodos em vez de GQL para preparar as consultas.

Observação: As estruturas de dados baseadas em índice e os algoritmos por trás dos mecanismos de consulta ao armazenamento de dados não suportam alguns tipos de consulta. Veja Consultas e índices: Restrições às consultas para obter mais informações.

Construtor

O construtor da classe GqlQuery é definido da maneira abaixo:

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

Um objeto de consulta usando a linguagem de consulta GQL do Google App Engine.

Argumentos:

query_string
Uma instrução completa de GQL iniciada com SELECT * FROM model-name.
*args
Vinculações de parâmetro de posição.
**kwds
Vinculações de parâmetro de palavra-chave.

Métodos da instância

Uma instância de GqlQuery tem os seguintes métodos:

bind(*args, **kwds)

Revincula os parâmetros da consulta. A nova consulta é executada na primeira vez em que os resultados são acessados depois da revinculação dos parâmetros.

A reutilização do objeto GqlQuery com novos parâmetros é mais rápida que criar um novo objeto GqlQuery, pois a revinculação não requer uma nova análise da string de consulta.

Argumentos:

*args
As novas vinculações de parâmetro de posição.
**kwds
As novas vinculações de parâmetro de palavra-chave.
get()

Executa a consulta e retorna o primeiro resultado ou None, se a consulta não retornou resultados.

get() implica um "limite" de 1 e ignora a cláusula LIMIT da consulta GQL, se houver. Um resultado, quando muito, é obtido do armazenamento de dados.

fetch(limit, offset=0)

Executa a consulta e retorna os resultados.

Os argumentos limit e offset controlam quantos resultados são obtidos do armazenamento de dados e quantos são retornados pelo método fetch():

  • O armazenamento de dados obtém resultados offset + limit para o aplicativo. Os primeiros resultados de offset não são pulados pelo armazenamento de dados.
  • O método fetch() salta os primeiros resultados de offset e retorna o restante (resultados de limit).
  • A consulta tem características de desempenho que correspondem de maneira linear à quantidade deslocada mais o limite.

Observação: fetch() retorna um máximo de 1000 resultados. Se mais de 1000 entidades correspondem à consulta e não há limite especificado ou se este é maior que 1000, somente os primeiros 1000 resultados são retornados por fetch().

Argumentos:

limit

O número de resultados a serem retornados. Este valor ignora a cláusula LIMIT na declaração de consulta GQL, se houver. Podem ser retornados menos resultados que limit caso não haja resultados suficientes que atendam aos critérios.

limit é um argumento obrigatório. Para obter todos os resultados de uma consulta quando o número de resultados é desconhecido, utilize o objeto GqlQuery como iterável em vez de utilizar o método fetch().

offset
O número de resultados a serem pulados. Este valor ignora a cláusula OFFSET (ou o deslocamento em uma cláusula LIMIT) na declaração de consulta GQL, se houver.

O valor de retorno é uma lista de instâncias de modelo, possivelmente vazia.

count(limit)

Retorna o número de resultados obtidos por esta consulta.

Utilizar count() é um pouco mais rápido que recuperar todos os dados segundo um fator constante, mas o tempo de execução ainda cresce com o tamanho do conjunto de resultados. É melhor usar count() somente em casos onde a contagem esperada é pequena ou especificar um limite.

Observação: count() retorna um máximo de 1000 resultados. Se o número de entidades correspondentes aos critérios da consulta excede o máximo, count() retorna uma contagem de 1000.

Argumentos:

limit

O número máximo de resultados a serem contados. Este valor ignora a cláusula LIMIT na declaração de consulta GQL, se houver.