Описание языка GQL

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

Синтаксис запроса GQL может быть кратко описан так:

  SELECT * FROM <тип>
    [WHERE <условие> [AND <условие> ...]]
    [ORDER BY <свойство> [ASC | DESC] [, <свойство> [ASC | DESC] ...]]
    [LIMIT [<смещение>,]<число результатов>]
    [OFFSET <смещение>]

  <условие> := <свойство> {< | <= | > | >= | = | != } <значение>
  <условие> := <свойство> IN <список>
  <свойство> := ANCESTOR IS <объект или его ключ>

Также как и в SQL, в GQL названия операций регистронезависимы. Однако указываемые в запросе типы и имена свойств являются чувствительными к регистру символов.

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

Необязательное выражение WHERE применяет к результирующему набору данных одно или несколько условий выборки. Каждое из них использует сравнение какого-либо свойства объекта с заданным значением с помощью оператора сравнения. Если несколько условий заданы с указанием оператора AND между ними, то объект, возвращаемый запросом, должен удовлетворять всем этим условиям. Запросы GQL не могут содержать оператор OR. Однако, может использоваться оператор IN, который является ограниченной реализацией OR.

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

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

В условии также может задаваться, что объект должен иметь вышестоящего предка, с использованием оператора ANCESTOR IS. Этим значением может быть экземпляр модели или ключ типа Key объекта-предка. Для дополнительной информации о предках объектов, обратитесь к разделу Ключи и группы объектов.

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

  • строка типа str, ограниченная одинарными кавычками. Все используемые символы кавычек внутри строки должны быть заданы двойным выражением: ''. К примеру: 'Joe''s Diner'
  • значение типа целое число или число с плавающей точкой. К примеру: 42.7
  • логическое значение, такое как TRUE или FALSE.
  • параметр подстановки. В строке запроса позиционные параметры задаются номерами: title = :1, именованные - именами title = :mytitle

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

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

Необязательное выражение LIMIT указывает запросу вернуть только заданное число результатов. Выражение LIMIT также может включать параметр смещение для указания пропуска нужного количества результатов, считая от начала выборки. Необязательное выражение OFFSET может также задавать параметр смещение, если в запросе не присутствует выражение LIMIT.

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

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

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