Referência GQL para Python NDB/DB

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

O GQL é aproximadamente equivalente ao SQL: pode considerar um kind GQL como uma tabela SQL, um entity GQL como uma linha SQL e um property GQL como uma coluna SQL. No entanto, uma pesquisa de linha-coluna SQL é um valor único, enquanto no GQL um valor de propriedade pode ser uma lista.

Versões GQL

Precisa de diferentes versões da GQL consoante o local onde executa as consultas. Existem duas referências ao GQL:

Sintaxe

A sintaxe GQL para Python NDB/DB pode ser resumida da seguinte forma:

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> ...]])

Tal como acontece com o SQL, as palavras-chave da GQL não são sensíveis a maiúsculas e minúsculas. Os nomes de tipos e propriedades são sensíveis a maiúsculas e minúsculas.

O GQL só suporta declarações SELECT.

Uma consulta GQL devolve zero ou mais entidades inteiras, entidades projetadas, ou chaves do tipo pedido. Todas as consultas GQL começam sempre com SELECT *, SELECT __key__ ou SELECT <property list>, onde property é uma lista delimitada por vírgulas de uma ou mais propriedades de entidades a serem devolvidas pela consulta. (Uma consulta GQL não pode executar uma consulta "join" semelhante a SQL.)

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

A cláusula DISTINCT(experimental) opcional especifica que apenas os resultados completamente únicos são devolvidos num conjunto de resultados. Isto só devolve o primeiro resultado para entidades que têm os mesmos valores para as propriedades que estão a ser projetadas.

A cláusula FROM opcional limita o conjunto de resultados às entidades do tipo especificado. Uma consulta sem uma cláusula FROM é denominada uma consulta sem tipo e só pode ter uma cláusula WHERE que especifique uma propriedade __key__.

A cláusula WHERE opcional limita o conjunto de resultados às entidades que cumprem uma ou mais condições. Cada condição compara uma propriedade da entidade com um valor através de um operador de comparação. Se forem indicadas várias condições com a palavra-chave AND, uma entidade tem de cumprir todas as condições para ser devolvida pela consulta. O GQL não tem um operador OR. No entanto, tem um operador IN, que oferece uma forma limitada de OR.

O operador IN compara o valor de uma propriedade com cada item numa lista. O operador IN é equivalente a muitas consultas =, uma para cada valor, que são combinadas com o operador OU. Uma entidade cujo valor para a propriedade especificada seja igual a qualquer um dos valores na lista pode ser devolvida para a consulta.

Nota: os operadores IN e != usam várias consultas nos bastidores. Por exemplo, o operador IN executa uma consulta de banco de dados subjacente separada para cada item na lista. As entidades devolvidas são o resultado do produto cruzado de todas as consultas da base de dados subjacente e são desduplicadas. É permitido um máximo de 30 consultas de armazenamento de dados para qualquer consulta GQL única.

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

O lado esquerdo de uma comparação é sempre um nome de propriedade. Um nome de propriedade típico consiste em carateres alfanuméricos, opcionalmente misturados com sublinhados e pontos. Por outras palavras, correspondem à expressão regular [a-zA-Z0-9_]+(\.[a-zA-Z0-9_]+)*.

Atenção: os nomes de propriedades que contenham outros carateres imprimíveis têm de ser colocados entre aspas duplas. Por exemplo: "first-name". Não são suportados espaços nem carateres não imprimíveis nos nomes das propriedades.

O lado direito de uma comparação pode ser um dos seguintes (conforme adequado para o tipo de dados da propriedade):

  • Um literal str, como uma string entre aspas simples. Os carateres de aspas simples na string têm de ser interpretados de forma literal como ''. Por exemplo: 'Joe''s Diner'
  • Um literal de número inteiro ou de vírgula flutuante. Por exemplo: 42.7
  • Um literal booleano, como TRUE ou FALSE.
  • O literal NULL, que representa o valor nulo (None em Python).
  • Um literal de data/hora, data ou 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 em string ou um caminho completo de tipos e nomes/IDs de chaves:

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

Nota: as condições do formulário property = NULL verificam se um valor nulo está explicitamente armazenado no arquivo de dados para essa propriedade. Isto não é o mesmo que verificar se a entidade não tem nenhum valor para a propriedade! As consultas do Datastore que fazem referência a uma propriedade nunca devolvem entidades que não tenham algum valor para essa propriedade.

Os parâmetros associados podem ser associados como argumentos posicionais ou argumentos de palavras-chave transmitidos a the GqlQuery constructor ou ao método gql() de uma classe de modelo. Os tipos de dados de propriedades que não têm uma sintaxe literal de valor correspondente têm de ser especificados através da associação de parâmetros, incluindo o tipo de dados de lista. As associações de parâmetros podem ser reassociadas com novos valores durante o tempo de vida da instância GqlQuery (por exemplo, para reutilizar uma consulta de forma eficiente) através do método bind().

A cláusula ORDER BY opcional indica que os resultados devem ser devolvidos ordenados pelas propriedades indicadas, por ordem ascendente (ASC) ou descendente (DESC). A cláusula ORDER BY pode especificar várias ordens de ordenação como uma lista delimitada por vírgulas, avaliada da esquerda para a direita. Se a direção não for especificada, é utilizada ASC por predefinição. Se não for especificada nenhuma cláusula ORDER BY, a ordem dos resultados não é definida e pode mudar ao longo do tempo.

Uma cláusula LIMIT opcional faz com que a consulta deixe de devolver resultados após as primeiras <count> entidades. A cláusula LIMIT também pode incluir um <offset> para ignorar esse número de resultados e encontrar o primeiro resultado a devolver. Uma cláusula OFFSET opcional pode especificar um <offset>, se não existir uma cláusula LIMIT.

Nota: tal como o parâmetro offset para o método fetch(), um OFFSET numa string de consulta GQL não reduz o número de entidades obtidas a partir do arquivo de dados. Apenas afeta os resultados devolvidos pelo método fetch(). Uma consulta com um desvio tem características de desempenho que correspondem linearmente ao tamanho do desvio mais o tamanho do limite.

Para ver informações sobre a execução de consultas GQL, a associação de parâmetros e o acesso aos resultados, consulte a classe GqlQuery e o método da 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 cuja idade esteja entre 18 e 35 anos (ou seja, Charlie e Edna), use esta consulta:

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

Para encontrar as três entidades do tipo Person cujas idades são as mais elevadas (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 cujos nomes sejam "Betty" ou "Charlie", use esta consulta:

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

Para devolver apenas os valores name para cada Person, use esta consulta:

SELECT name FROM Person

Para devolver apenas os valores de name para cada Person, ordenados por age, use esta consulta:

SELECT name FROM Person ORDER BY age

Para encontrar as chaves das entidades do tipo Person com uma idade de 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 estão no grupo de entidades de Amy (ou seja, Amy e Fred), use esta consulta:

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

Para fazer a correspondência por chave, podemos usar __key__ no lado esquerdo de uma condição. Por exemplo, podemos usar isto para obter todas as entidades Person que tenham um nome de utilizador que comece por "a". 

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

Nota: se alguma vez criar uma consulta com uma igualdade em __key__, considere usar get() em alternativa para obter a entidade diretamente.