Referência de GQL

GQL é uma linguagem semelhante a SQL para a recuperação de entidades de dados do armazenamento de dados escalável do Google App Engine. Embora os recursos de GQL sejam diferentes dos de uma linguagem de consulta de banco de dados relacional tradicional, a sintaxe de GQL é semelhante a SQL.

A sintaxe de GQL pode ser resumida da forma abaixo:

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

  <condition> := <property> {< | <= | > | >= | = | != } <value>
  <condition> := <property> IN <list>
  <condition> := ANCESTOR IS <entity or key>

Assim como SQL, as palavras-chave de GQL não fazem distinção entre maiúsculas e minúsculas. Os tipos e nomes de propriedade fazem distinção entre maiúsculas e minúsculas.

Uma consulta GQL retorna zero ou mais entidades de dados do tipo solicitado como instâncias da classe de modelo do tipo. Um resultado é sempre uma entidade completa. Portanto, cada consulta GQL sempre começa com SELECT * FROM seguido do nome do tipo. (O especificador do campo semelhante a SQL é sempre *. A sintaxe SQL foi mantida devido à familiaridade.) Uma consulta GQL não pode executar uma consulta "join" semelhante a SQL.

A cláusula WHERE opcional filtra o conjunto de resultados para obter as entidades que atendem a uma ou mais condições. Cada condição compara uma propriedade da entidade a um valor, utilizando um operador de comparação. Se forem fornecidas diversas condições com a palavra-chave AND, uma entidade deverá atender a todas as condições para ser retornada pela consulta. GQL não tem um operador OR. Entretanto, ela apresenta um operador IN, que oferece uma forma limitada de OR.

O operador IN compara o valor de uma propriedade a cada item de uma lista. O operador IN é equivalente a diversas consultas =, uma para cada valor, que são reunidas com OR. Uma entidade cujo valor da propriedade fornecida seja igual a qualquer um dos valores da lista poderá ser retornada pela consulta.

Observação: Os operadores IN e != utilizam diversas consultas nos bastidores. Por exemplo, o operador IN executa uma consulta básica ao armazenamento de dados separada para cada item da lista. As entidades retornadas são resultado do produto cruzado de todas as consultas básicas ao armazenamento de dados, sendo removidas as duplicações. É permitido um máximo de 30 consultas ao armazenamento de dados para qualquer consulta GQL única.

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

O lado esquerdo de uma comparação é sempre o nome de uma propriedade. O lado direito pode ser um dos seguintes (conforme apropriado para o tipo de dados da propriedade):

• um literal str, como uma string entre apóstrofos. Os caracteres entre apóstrofos da string devem receber códigos de 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.
• uma data e hora, data ou literal 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/IDs de chave:
  • 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 flutuantes:
  GEOPT(lat, long)
• Um valor de parâmetro vinculado. Na string da consulta, as referências dos parâmetros de posição são por números: title = :1 A referência de parâmetros de palavra-chave é por nome: title = :mytitle

Os parâmetros vinculados podem ser argumentos de posição ou de palavra-chave passados ao construtor GqlQuery ou ao método gql() de uma classe Model. Os tipos de dados de propriedade que não tiverem sintaxe de valor literal correspondente devem ser especificados utilizando vinculação de parâmetro, incluindo o tipo de dados da lista. As vinculações de parâmetro podem ser revinculadas com novos valores durante a instância de GqlQuery (como 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 retornados classificados segundo as propriedades fornecidas, em ordem crescente (ASC) ou decrescente (DESC). Se a direção não for especificada, o padrão é ASC. A cláusula ORDER BY pode especificar diversas ordens de classificação em uma lista separada por vírgulas, avaliada da esquerda para a direita.

Uma cláusula LIMIT opcional faz a consulta parar de retornar resultados após as primeiras count entidades. LIMIT também pode incluir um offset para pular o número equivalente de resultados para encontrar o primeiro resultado a ser retornado. Uma cláusula OFFSET opcional pode especificar um offset se não houver cláusula LIMIT presente.

Observação: A cláusula LIMIT retorna um máximo de 1000 resultados. Se for especificado um limite maior que o máximo, é usado o máximo. Este mesmo máximo é aplicável ao método fetch() da classe GqlQuery.

Observação: Assim como o parâmetro offset do método fetch(), um OFFSET em uma string de consulta GQL não reduz o número de entidades obtidas do armazenamento de dados. Ele afeta apenas os resultados retornados pelo método fetch(). Uma consulta com deslocamento tem características de desempenho correspondentes de maneira linear ao tamanho do deslocamento.

Para obter mais informações sobre a execução de consultas GQL, vinculação de parâmetros e acesso aos resultados, consulte a classe GqlQuery e o método de classe Model.gql().