Referência GQL para NDB/DB do Python

GQL é uma linguagem semelhante a SQL para recuperar entidades e chaves. A sintaxe de consultas GQL é semelhante à de SQL. Esta página é uma referência para usar GQL com as bibliotecas de cliente NDB e DB do Python.

GQL é mapeado de maneira aproximada para SQL: pense em um kind GQL como uma tabela SQL, uma entity GQL como uma linha SQL e uma property GQL como uma coluna SQL. No entanto, uma pesquisa de coluna/linha SQL é um valor único, e em GQL um valor de propriedade pode ser uma lista.

Versões de GQL

Você precisa de versões diferentes de GQL, dependendo de onde executa consultas. Há duas referências de GQL:

Sintaxe

A sintaxe GQL para NDB/DB do Python pode ser resumida assim:

SELECT [DISTINCT] [* | <property list> | __key__]
  [FROM <kind>]
  [WHERE <condition> [AND <condition> ...]]
  [ORDER BY <property> [ASC | DESC] [, <property> [ASC | DESC] ...]]
  [LIMIT [<offset>,]<count>]
  [OFFSET <offset>]

  <property list> := <property> [, <property> ...]
  <condition> := <property> {< | <= | > | >= | = | != } <value>
  <condition> := <property> IN <list>
  <condition> := ANCESTOR IS <entity or key>
  <list> := (<value> [, <value> ...]])

Assim como acontece com SQL, as palavras-chave GQL são indiferentes a maiúsculas. Os nomes de tipo e propriedade diferenciam maiúsculas e minúsculas.

O GQL aceita apenas instruções SELECT.

Uma consulta GQL retorna zero ou mais entidades inteiras, entidades projetadas ou chaves do tipo solicitado. Cada consulta GQL começa sempre com SELECT *, SELECT __key__ ou SELECT <property list>, em que property é uma lista delimitada por vírgulas de uma ou mais propriedades de entidade a serem retornadas da consulta. Uma consulta GQL não executa uma consulta "join" semelhante às de SQL.

Dica: as consultas SELECT __key__ or SELECT <property list> são mais rápidas e usam menos tempo de CPU do que consultas SELECT *.

A cláusula DISTINCT(experimental) opcional especifica que apenas resultados totalmente exclusivos serão retornados em um conjunto de resultados. Ela só retornará o primeiro resultado de entidades com os mesmos valores das propriedades projetadas.

A cláusula FROM opcional limita o conjunto de resultados a essas entidades do tipo indicado. Uma consulta sem uma cláusula FROM é chamada de consulta sem tipo e só pode ter um WHERE que especifique uma propriedade __key__.

A cláusula WHERE opcional limita o conjunto de resultados às entidades que atendam a uma ou mais condições. Cada condição compara uma propriedade da entidade com um valor usando um operador de comparação. Se várias condições forem fornecidas com a palavra-chave AND, uma entidade precisará atender a todas as condições a serem retornadas pela consulta. O GQL não tem um operador OR. No entanto, ele tem um operador IN, que fornece uma forma limitada de OR.

O operador IN compara o valor de uma propriedade com cada item em uma lista. O operador IN equivale a muitas consultas =, uma para cada valor, que são combinadas como OR. Uma entidade com valor da propriedade indicada que equivalha a qualquer um dos valores da lista pode ser retornada para a consulta.

Observação: os operadores IN e != usam várias consultas em segundo plano. Por exemplo, o operador IN executa uma consulta de armazenamento de dados subjacente separada para cada item na lista. As entidades retornadas são resultado do produto cruzado de todas as consultas subjacentes ao armazenamento de dados. A duplicação dessas entidades é eliminada. Um máximo de 30 consultas de armazenamento de dados é permitido para qualquer consulta GQL única.

Uma condição também pode testar se uma entidade tem uma determinada entidade como um ancestral usando o operador ANCESTOR IS. O valor é uma instância de modelo ou uma chave da entidade do ancestral. Para mais informações sobre ancestrais, consulte Chaves e grupos de entidades.

O lado esquerdo de uma comparação é sempre o nome de uma propriedade. Normalmente, o nome de uma propriedade consiste em caracteres alfanuméricos, que podem ser misturados com sublinhados e pontos. Em outras palavras, eles correspondem à expressão regular [a-zA-Z0-9_]+(\.[a-zA-Z0-9_]+)*.

Cuidado: os nomes de propriedade que contêm outros caracteres para impressão precisam estar entre aspas duplas. Por exemplo: "first-name". Espaços ou caracteres não imprimíveis em nomes de propriedade não são compatíveis.

O lado direito de uma comparação pode ser um destes itens (conforme apropriado para o tipo de dados da propriedade):

  • Um literal str, como uma string de aspas simples. Os caracteres de aspas simples na string precisam ter escape como ''. Por exemplo: 'Joe''s Diner'.
  • Um literal de número inteiro ou com ponto flutuante. Por exemplo: 42.7.
  • Um literal booleano, como TRUE ou FALSE.
  • O literal NULL, que representa o valor nulo (None no Python).
  • Literal de data e hora, de data ou de hora, com valores numéricos ou uma representação de string, nas seguintes formas:
    • DATETIME(year, month, day, hour, minute, second)
    • DATETIME('YYYY-MM-DD HH:MM:SS')
    • DATE(year, month, day)
    • DATE('YYYY-MM-DD')
    • TIME(hour, minute, second)
    • TIME('HH:MM:SS')
  • um literal de chave de entidade, com uma chave codificada por string ou um caminho completo de tipos e nomes/códigos de chaves:

    • KEY('encoded key')
    • KEY('kind', 'name'/ID [, 'kind', 'name'/ID...])
  • Um literal de objeto User, com o endereço de e-mail do usuário:
    USER('email-address')
  • Um literal de GeoPt, com latitude e longitude como valores de ponto flutuante:
    GEOPT(lat, long)
  • Um valor de parâmetro vinculado. Na string de consulta, os parâmetros posicionais são referenciados por número: title = :1. Os parâmetros de palavra-chave são referenciados por nome: title = :mytitle

Observação: as condições do formulário property = NULL verificam se um valor nulo é armazenado explicitamente no armazenamento de dados dessa propriedade. Isso não é o mesmo que verificar se a entidade não tem um valor da propriedade. As consultas de armazenamento de dados que se referem a uma propriedade jamais retornam entidades que não tenham um valor dessa propriedade.

Os parâmetros podem ser vinculados como argumentos posicionais ou de palavra-chave transferidos para o construtor GqlQuery ou um método gql() da classe de modelo. Os tipos de dados de propriedade que não tenham sintaxe literal de valor correspondente precisam ser especificados usando a vinculação de parâmetro, inclusive o tipo de dado da lista. As vinculações de parâmetros podem ser revinculadas com novos valores durante o ciclo de vida da instância GqlQuery (como para reutilizar uma consulta de maneira eficiente) usando o método bind().

A cláusula ORDER BY opcional indica que os resultados precisam ser retornados classificados pelas propriedades indicadas, em ordem crescente (ASC) ou decrescente (DESC). A cláusula ORDER BY pode especificar várias ordens de classificação como uma lista delimitada por vírgulas, avaliada da esquerda para a direita. Se a direção não for especificada, ela assumirá como padrão ASC. Se nenhuma cláusula ORDER BY for especificada, a ordem dos resultados será indefinida e poderá mudar com o passar do tempo.

Uma cláusula LIMIT opcional fará a consulta deixar de retornar resultados depois das primeiras entidades <count>. A cláusula LIMIT também pode incluir um <offset>, para pular os muitos resultados a fim de encontrar o primeiro resultado a ser retornado. Uma cláusula OFFSET opcional poderá especificar um <offset>, se nenhuma cláusula LIMIT estiver presente.

Observação: como o parâmetro offset para o método fetch(), um OFFSET em uma string de consulta GQL não reduz o número de entidades buscadas no armazenamento de dados. Isso só afeta resultados retornados pelo método fetch(). Uma consulta com um deslocamento tem características de desempenho correspondentes de maneira linear ao tamanho do deslocamento mais o tamanho limite.

Para informações sobre como executar consultas GQL, vincular parâmetros e acessar resultados, consulte a classe GqlQuery e o método de classe Model.gql().

Exemplos

from google.appengine.ext import db

class Person(db.Model):
  name = db.StringProperty()
  age = db.IntegerProperty()

# We use a unique username for the Entity's key.
amy = Person(key_name='amym', name='Amy', age=48)
amy.put()
Person(key_name='bettyd', name='Betty', age=42).put()
Person(key_name='charliec', name='Charlie', age=32).put()
Person(key_name='charliek', name='Charlie', age=29).put()
Person(key_name='eedna', name='Edna', age=20).put()
Person(key_name='fredm', name='Fred', age=16, parent=amy).put()
Person(key_name='georgemichael', name='George').put()

Para encontrar todas as entidades do tipo Person com idades entre 18 e 35 (ou seja, Charlies e Edna), use esta consulta:

SELECT * FROM Person WHERE age >= 18 AND age <= 35

Para encontrar as três entidades do tipo Person com idades maiores (ou seja, Amy, Betty e Charlie), use esta consulta:

SELECT * FROM Person ORDER BY age DESC LIMIT 3

Para encontrar as entidades do tipo Person com nomes de "Betty" ou "Charlie", use esta consulta:

SELECT * FROM Person WHERE name IN ('Betty', 'Charlie')

Para só retornar os valores name de cada Person, use esta consulta:

SELECT name FROM Person

Para só retornar os valores name de cada Person, ordenados por age, use esta consulta:

SELECT name FROM Person ORDER BY age

Para encontrar as chaves das entidades do tipo Person que tenham uma idade None (ou seja, KEY('Person', 'georgemichael')), use esta consulta:

SELECT __key__ FROM Person WHERE age = NULL

Para encontrar todas as entidades, independentemente do tipo, que estejam no grupo de entidades da Amy (ou seja, Amy e Fred), use esta consulta:

SELECT * WHERE __key__ HAS ANCESTOR KEY(Person, 'Amy')

Para corresponder por Key, podemos usar __key__ no lado esquerdo de uma condição. Por exemplo, podemos usá-lo para receber todas as entidades Person que tenham um nome de usuário que comece com "a".

SELECT * FROM Person WHERE __key__ >= KEY('Person', 'a') AND __key__ < KEY('Person', 'b')

Observação: caso você já tenha criado uma consulta com uma igualdade em __key__, use get() em vez de buscar a entidade diretamente.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Ambiente padrão do App Engine para Python 2