A classe Query

A classe Query é uma interface de consulta do armazenamento de dados que utiliza objetos e métodos para preparar consultas.

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

• Introdução
• Query()
• Métodos da instância:
  • filter()
  • order()
  • ancestor()
  • get()
  • fetch()
  • count()

Introdução

Um aplicativo cria um objeto Query, chamando o construtor com a classe Model cujas entidades serão consultadas ou chamando o método da classe all().

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

query = db.Query(Song)

query = Song.all()

Sem modificações, o objeto representa uma consulta por todas as entidades do tipo determinado. As chamadas de método personalizam a consulta com condições de propriedade (filter()), condições de ancestral (ancestor()) e classificação (order()). Por uma questão de conveniência, estes métodos retornam self para que possam ser encadeados em uma única instrução.

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

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

O aplicativo executa a consulta em uma das maneiras abaixo:

• chamando o método fetch(). Isso executa uma única chamada para o armazenamento de dados para obter resultados, até o número de resultados especificado. O objeto Query não armazena os resultados em cache. Portanto, chamar fetch() uma segunda vez executará a consulta novamente.

  results = query.fetch(limit=5)
  for song in results:
    print song.title
  

• tratando o objeto Query como iterável. O iterador recupera os resultados do armazenamento de dados em pequenos lotes, permitindo que o aplicativo pare a iteração dos resultados para evitar obter mais do que o necessário. A iteração é interrompida quando todos os resultados correspondentes à consulta tiverem sido recuperados. Assim como em fetch(), a interface do iterador não armazena os resultados em cache. Portanto, criar um novo iterador a partir do objeto Query irá executar a consulta novamente.

  for song in query:
    print song.title
  

Veja também GqlQuery, uma classe de consulta que utiliza uma linguagem semelhante a SQL.

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 Query é definido como é mostrado abaixo:

class Query(model_class)

Uma interface de consulta de armazenamento de dados que utiliza objetos e métodos para preparar as consultas.

A instância de Query retornada pelo construtor representa uma consulta para todas as entidades do tipo. Os métodos de instância filter(), order() e ancestor() aplicam à consulta critérios para filtrar ou ordenar os resultados.

Argumentos:

model_class

A classe de Model (ou Expando) que representa o tipo de entidade do armazenamento de dados da consulta.

Métodos da instância

As instâncias da classe Query têm os métodos abaixo:

filter(property_operator, value)

Adiciona um filtro de condição de propriedade à consulta. Somente as entidades com propriedades que atendam a todas as condições serão retornadas pela consulta.

Argumentos:

property_operator

Uma string contendo o nome da propriedade e um operador de comparação opcional. O nome e o operador devem ser separados por um espaço, como em: age > Os seguintes operadores de comparação são suportados: < <= = >= > != IN Se o operador for omitido da string (o argumento é apenas o nome da propriedade), o filtro usará o operador =.

value

O valor a ser usado na comparação do lado direito da expressão. Seu tipo deve ser o tipo de dados de valor da propriedade sendo comparada. Consulte Tipos e classes Property.

query.filter('height >', 42).filter('city = ', 'Seattle')

query.filter('user = ', users.get_current_user())

order(property)

Adiciona uma classificação aos resultados. Os resultados são ordenados a partir da primeira ordem adicionada.

Argumentos:

property

Uma string, o nome da propriedade a classificar. Para especificar que a ordem deve ser decrescente, coloque um hífen (-) antes do nome. Sem o hífen a ordem será crescente.

# Order by last name, alphabetical:
query.order('last_name')

# Order tallest to shortest:
query.order('-height')

ancestor(ancestor)

Adiciona um filtro de condição de ancestral à consulta. A consulta retorna somente as entidades com a entidade dada como ancestral (em qualquer parte do caminho).

Argumentos:

ancestor

Uma instância de Model ou de Key representando o ancestral.

get()

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

get() implica em um "limite" de 1. 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. 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 Query como iterável em vez de utilizar o método fetch().

offset

O número de resultados a serem pulados.

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 de resultados a serem contados.