• Официальный сайт SDK
  • Сайт с примерами кода

Класс GqlQuery

Класс GqlQuery является интерфейсом для работы с хранилищем платформы App Engine, использующим язык запросов GQL.

Класс GqlQuery реализован в модуле google.appengine.ext.db.

Введение

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

Конструктор класса GqlQuery принимает в качестве своих параметров строку с полным GQL выражением, начинающимся на SELECT * FROM имя-модели. Значения в выражениях WHERE могут быть строками, числовыми значениями или параметрами подстановки. Параметры подстановки можно первоначально задавать как позиционными так и именованными аргументами с передачей их в конструктор класса.

CnF1ZXJ5ID0gR3FsUXVlcnkoIlNFTEVDVCAqIEZST00gU29uZyBXSEVSRSBjb21wb3NlciA9ICdMZW5ub24sIEpvaG4nIikKcXVlcnkgPSBHcWxRdWVyeSgiU0VMRUNUICogRlJPTSBTb25nIFdIRVJFIGNvbXBvc2VyID0gOjEiLCAiTGVubm9uLCBKb2huIikKcXVlcnkgPSBHcWxRdWVyeSgiU0VMRUNUICogRlJPTSBTb25nIFdIRVJFIGNvbXBvc2VyID0gOmNvbXBvc2VyIiwgY29tcG9zZXI9Ikxlbm5vbiwgSm9obiIpCg===

Для удобства разработчика, классы Model и Expando имеют метод gql(), который возвращает соответствующий модели экземпляр класса GqlQuery. Этот метод принимает в параметрах строку GQL запроса без первоначального выражения SELECT * FROM имя-модели, которое по умолчанию подразумевается системой.

CnF1ZXJ5ID0gU29uZy5ncWwoIldIRVJFIGNvbXBvc2VyID0gJ0xlbm5vbiwgSm9obiciKQo==

Также как и с классом Query, приложение запускает выполнение запроса либо вызовом метода fetch(), либо с помощью использования объекта GqlQuery в качестве итератора. Для дополнительной информации смотрите раздел документации Класс Query.

Между интерфейсами Query и GqlQuery имеется различие в том, как они производят доступ к результатам выборки: если GQL запрос включает в себя выражения LIMIT или OFFSET, то производится единовременная загрузка всех результатов, аналогично работе метода fetch(), даже в том случае, если затем для доступа к данным используется итератор. Например, когда объект GqlQuery с заданными выражениями LIMIT или OFFSET используется как итератор, то выполняется только один внутренний запрос к хранилищу, после чего результаты загружаются в память, где итератор и работает с ними.

CmZvciBzb25nIGluIHE6CnByaW50IHNvbmcudGl0bGUK=

Смотрите также описание Класса Query, который использует объекты и методы для подготовки запросов вместо работы с языком GQL.

Примечание: Используемый в хранилище данных алгоритм по обработке запросов с помощью индексов не поддерживает некоторые виды запросов. Для дополнительной информации смотрите раздел Запросы и индексы: Ограничения в запросах.

Конструктор

Конструктор класса GqlQuery определен следующим образом:

class GqlQuery(query_string, *args, **kwds)

Создает интерфейс для работы с запросами с помощью обработки выражения на языке GQL.

Параметры:

query_string
Строка с полным выражением на языке GQL, начинающаяся на SELECT * FROM имя-модели.
*args
Позиционные параметры для подстановки в запрос.
**kwds
Именованные параметры для подстановки в запрос.

Методы экземпляра

Экземпляр класса GqlQuery имеет следующие методы:

bind(*args, **kwds)

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

Использование механизма переподстановки параметров работает гораздо быстрее, чем создание еще одного объекта GqlQuery с новыми параметрами, так как не требует ресурсов для компиляции строки с выражением запроса.

Параметры:

*args
Новые позиционные параметры для подстановки в запрос.
**kwds
Новые именованные параметры для подстановки в запрос.
get()

Выполняет запрос, после чего возвращает его первый результат или None, в том случае если запрос не вернул результатов.

get() работает аналогично параметру "limit" со значением 1 и перекрывает текущие значения выражений LIMIT в GQL запросе, если они были указаны. В большинстве случаев из хранилища будет получен результат с одним объектом.

fetch(limit, offset=0)

Выполняет запрос и возвращает его результаты.

Параметры limit и offset определяют сколько объектов необходимо загрузить из хранилища и сколько из них будет возвращено методом fetch() в результирующей выборке:

  • Хранилище выполняет загрузку offset + limit объектов. Первые в количестве offset результатов выборки не игнорируются самим хранилищем.
  • Метод fetch() самостоятельно выполняет пропуск заданного количества первых offset объектов, после чего возвращает оставшиеся (limit результатов).
  • Запрос имеет характеристики производительности, которые линейно зависят от заданных параметров offset и limit.

Примечание: метод fetch() возвращает максимум 1000 результатов. Если запросу удовлетворяют более 1000 объектов и в нем не задан параметр limit (или он также более 1000), методом fetch() выполняется загрузка только 1000 первых результатов.

Параметры:

limit

Максимальное количество объектов, возвращаемых на запрос. Это значение перекрывает аналогичное в выражении LIMIT строки запроса GQL. Количество результатов меньше числа limit может быть возвращено в том случае, если условиям запроса соответствуют меньшее число объектов.

Параметр limit является обязательным аргументом функции. Для того, чтобы получить все результаты запроса, число которых неизвестно, используйте объект GqlQuery в качестве итератора вместо использования метода fetch().

offset
Количество результатов, которые будут опущены. Это значение перекрывает аналогичное выражение OFFSET (или параметр смещения в выражении LIMIT), заданное в строке GQL запроса.

Возвращает значение в виде списка экземпляров модели или, в случае если ничего не найдено, пустой список.

count(limit)

Возвращает число объектов, которые выдаст указанный запрос при его выполнении.

Метод count() работает быстрее, чем аналогичная загрузка всех объектов, соответствующих запросу, однако время его выполнения будет расти в зависимости от числа результирующей выборки. Поэтому рекомендуется использование метода count() только в тех случаях, когда результирующий набор однозначно небольшой или выполнять его ограничение с помощью параметра limit.

Примечание: Метод count() также будет возвращать максимальное количество объектов равное 1000. Если реальное число объектов, которое удовлетворяет условиям запроса превышает этот максимум, то метод count() вернет результат 1000.

Параметры:

limit

Ограничение на максимальное количество объектов, возвращаемое методом count(). Это значение перекрывает аналогичное в выражении LIMIT строки запроса GQL.