Класс Query

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

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

• Введение
• Query()
• Методы экземпляра:
  • filter()
  • order()
  • ancestor()
  • get()
  • fetch()
  • count()

Введение

Приложение может создать объект Query либо вызовом его конструктора с параметром нужного для запроса класса модели, либо вызовом у этого класса метода all().

class Song(db.Model):
  title = db.StringProperty()
  composer = db.StringProperty()
  date = db.DateTimeProperty()

query = db.Query(Song)

query = Song.all()

Без дальнейшей модификации полученный интерфейс будет представлять собой запрос всех объектов заданного вида. Приложение может уточнить запрос указав соответствующие условия по значению свойств (filter()), совпадению предков объекта (ancestor()), и задать порядок сортировки (order()). Для удобства разработчика, все эти методы возвращают объект self, и таким образом могут быть использованы цепочкой в одном выражении.

query.filter('title =', 'Imagine')
query.order('-date')
query.ancestor(key)

query.filter('title =', 'Imagine').order('-date').ancestor(key)

Приложение может запустить выполнение запроса двумя вариантами:

• вызвав метод fetch(). Он выполняет одиночный запрос данных из хранилища с загрузкой указанного количества объектов. Интерфейс Query не производит кэширование результатов, таким образом повторный вызов метода fetch() приведет к еще одному выполнению запроса.

  results = query.fetch(limit=5)
  for song in results:
    print song.title
  

• использовав объект Query как итератор. Итератор производит загрузку результатов из хранилища маленькими порциями, позволяя приложению прервать получение данных в тот момент, когда это потребуется. Итератор закончит свою работу в тот момент, когда все результаты запроса будут извлечены. Также как и метод fetch() итератор не производит кэширование результатов, таким образом создание нового итератора из объекта Query приведет к повторному выполнению запроса.

  for song in query:
    print song.title
  

Смотрите также опиcание класса GqlQuery, интерфейса, который использует для запросов язык похожий на SQL.

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

Конструктор

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

class Query(model_class)

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

Экземпляр класса Query возвращается его конструктором и представляет собой запрос всех объектов заданного типа. К нему могут быть применены методы экземпляра filter(), order() и ancestor() для уточнения набора данных с помощью фильтров или выполнения сортировки результирующего набора данных.

Параметры:

model_class

Потомок класса Model (или Expando), который соответствует типу данных объектов, используемого в запросе.

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

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

filter(property_operator, value)

Добавляет фильтр условия по свойству к запросу. Таким образом только объекты, свойства которых удовлетворяют заданным условиям будут возвращены в результатах запроса.

Параметры:

property_operator

Строка, содержащая имя свойства и оператор сравнения. Поддерживаются операторы: < <= = >= > (Операторы неравенства (!=) и IN не поддерживаются)

value

Значение используемое в условии сравнения в правой части выражения. Его тип должен соответствовать типу свойства, с которым производится сравнение. Смотрите раздел Классы типов свойств.

query.filter('height >', 42).filter('city = ', 'Seattle')

query.filter('user = ', users.get_current_user())

order(property)

Задает порядок сортировки результатов. Она выполняется начиная с первого определенного аргумента.

Параметры:

property

Строка, содержащая имя свойства, по которому будет производится сортировка. Для указания того, что сортировку необходимо производить в порядке убывания, добавьте слева от имени свойства дефис (-). Без указания дефиса подразумевается сортировка по возрастанию.

# Сортировать по фамилии по возрастанию:
query.order('last_name')

# Сортировать от высоких к низким:
query.order('-height')

ancestor(ancestor)

Добавляет в запрос условие совпадения с объектом-предком. После его задания будут возвращены только те объекты, которые имеют определенного предка (в любом месте их пути).

Параметры:

ancestor

Экземпляр класса Model или Key, соответствующий предку объекта.

get()

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

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

fetch(limit, offset=0)

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

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

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

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

Параметры:

limit

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

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

offset

Количество результатов, которые будут опущены.

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

count(limit)

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

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

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

Параметры:

limit

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