Справочное руководство по GQL

GQL – язык, подобный SQL, предназначенный для получения объектов данных из масштабируемого хранилища данных App Engine. В то время как функции GQL отличаются от функций других языков запросов для традиционных реляционных баз данных, синтаксис GQL во многом похож на синтаксис SQL.

Синтаксис GQL можно описать следующим образом:

  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>

Как и в SQL, ключевые слова GQL не зависят от регистра. Названия свойств и типов зависят от регистра.

Запрос GQL возвращает ноль или более объектов данных запрашиваемого типа в виде экземпляров класса модели данного типа. Результат – это всегда целый объект, поэтому запрос GQL всегда начинается с SELECT * FROM, после чего следует имя типа. (Подобный SQL спецификатор поля – всегда *. Синтаксис SQL сохраняется для быстрого понимания.) GQL не может выполнить запрос, подобный запросу "join" в SQL.

Дополнительный оператор WHERE отфильтрует результаты, не удовлетворяющие одному или нескольким условиям. Каждое условие сравнивает свойство объекта со значением, используемым в операторе сравнения. Если несколько условий соединены ключевым словом AND, то чтобы объект был возвращен в запросе, он должен удовлетворять всем условиям. В GQL нет оператора OR. Тем не менее, есть оператор IN, который является ограниченной формой оператора OR.

Оператор IN сравнивает значение свойства с каждом элементом в списке. Оператор IN соответствует нескольким запросам = для каждого значения, которые объединены с помощью OR. Объект, значение которого для указанного свойства совпадает с одним из значений списка, будет возвращен в запросе.

Примечание. Операторы IN и != используют несколько запросов. Например, оператор IN выполняет отдельный базовый запрос к хранилищу данных для каждого элемента списка. Возвращаемые объекты являются результатом векторного произведения всех базовых запросов к хранилищу данных и не дублируются. Для каждого отдельного запроса GQL допустимо не более 30 запросов к хранилищу данных.

Условие также может проверить, является ли данный объект родителем объекта, посредством оператора ANCESTOR IS. Значение – экземпляр модели или значение Key для родительского объекта. Подробнее о родительских объектах рассказано в статье Ключи и группы объектов.

Левая часть условия всегда является названием свойства. Правая часть может быть следующим (в соответствии с типом данных свойства):

• константой str в виде строки в одинарных кавычках. Перед одинарными кавычками в строке необходимо ставить ''. Например, 'Joe''s Diner'
• целой числовой константой или константой с плавающей точкой. Например, 42.7
• логической константой, TRUE или FALSE.
• значением datetime, датой или временным литералом, представленными либо числовыми значениями, либо строками, следующего вида:
  • 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')
• ключевым литералом объекта, содержащим либо ключ, закодированный в виде строки, либо полный путь, состоящий из типов и названий/идентификаторов ключей:
  • KEY('encoded key')
  • KEY(kind, name/ID [, kind, name/ID...])
• объектным литералом User, содержащим адрес электронной почты пользователя:
  USER(email-address)
• литералом GeoPt, содержащим широту и долготу в виде значений с плавающей точкой:
  GEOPT(lat, long)
• значением граничного параметра. В строке запроса на позиционные параметры можно ссылаться с помощью чисел: title = :1, а на именованные – по названию: title = :mytitle

Граничные параметры можно задать как позиционные или именованные аргументы, передаваемые в конструктор GqlQuery или метод gql() класса Model. Для типа данных свойств, у которого нет соответствующего значения, необходимо задать синтаксис константы с помощью связи параметров, в том числе и для типа данных списка. Можно переопределить связи параметров и связать параметры с новыми значениями во время существования экземпляра класса GqlQuery (например, для эффективного повторного использования запроса) с помощью метода bind().

Дополнительный оператор ORDER BY указывает, что возвращаемые результаты должны быть отсортированы по указанным свойствам по возрастанию (ASC) или по убыванию (DESC). Если порядок не указан, то по умолчанию используется ASC. Оператор ORDER BY может задавать несколько порядков сортировки в виде списка, разделенного запятыми, который реализуется слева направо.

Дополнительный оператор LIMIT останавливает возвращение результатов после первых count объектов. Оператор LIMIT может также содержать offset, чтобы пропустить ряд результатов до возвращения первого. Дополнительный оператор OFFSET указывает offset, если не присутствует оператор LIMIT.

Примечание. Максимально допустимое значение оператора LIMIT – 1000. Если указанное ограничение превышает максимально допустимое, используется максимум. Такое же максимально допустимое значение и у метода fetch() класса GqlQuery.

Примечание. Аналогично параметру offset в методе fetch(), OFFSET в строке запроса GQL не сокращает количество объектов, получаемых из хранилища данных. Он лишь определяет, какие результаты возвращаются методом fetch(). Время выполнения запроса со сдвигом линейно зависит от размера сдвига.

Дополнительную информацию по запросам GQL, связи параметров и получению результатов можно найти в классе GqlQuery и методе Model.gql().