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

Создание, получение и удаление данных

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

Создание и изменение объекта

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

CnBldCA9IFBldChuYW1lPSJGbHVmZnkiLAp0eXBlPSJjYXQiLApvd25lcj11c2Vycy5nZXRfY3VycmVudF91c2VyKCkpCg===

Новый объект не сохраняется в хранилище до тех пор, пока он явно не будет записан либо с помощью вызова метода put(), либо с помощью функции db.put() с передачей параметра его экземпляра.

CnBldC5wdXQoKQpkYi5wdXQocGV0KQo==

Если объект уже был ранее сохранен, то вызов метода put() запишет его изменения в хранилище.

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

CmlmIHVzZXJzLmdldF9jdXJyZW50X3VzZXIoKToKdXNlcl9wZXRzID0gZGIuR3FsUXVlcnkoIlNFTEVDVCAqIEZST00gUGV0IFdIRVJFIHBldC5vd25lciA9IDoxIiwKdXNlcnMuZ2V0X2N1cnJlbnRfdXNlcigpKQpmb3IgcGV0IGluIHVzZXJfcGV0czoKcGV0LnNwYXllZF9vcl9uZXV0ZXJlZCA9IFRydWUKZGIucHV0KHVzZXJfcGV0cykK=

Получение объектов с помощью запроса

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

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

Интерфейс Datastore API реализует два варианта подготовки и выполнения запросов: Query, который использует методы для подготовки запроса и GqlQuery, который использует похожий на SQL язык запросов, названный GQL.

Интерфейс Query

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

CmNsYXNzIFN0b3J5KGRiLk1vZGVsKToKdGl0bGUgPSBkYi5TdHJpbmdQcm9wZXJ0eSgpCmRhdGUgPSBkYi5EYXRlVGltZVByb3BlcnR5KCkKcXVlcnkgPSBTdG9yeS5hbGwoKQpxdWVyeS5maWx0ZXIoJ3RpdGxlID0nLCAnRm9vJykKcXVlcnkub3JkZXIoJy1kYXRlJykKcXVlcnkuYW5jZXN0b3Ioa2V5KQojINCS0YvQt9C+0LIg0LLRgdC10YUg0Y3RgtC40YUg0LzQtdGC0L7QtNC+0LIg0LzQvtC20LXRgiDQvtGB0YPRidC10YHRgtCy0LvRj9GC0YzRgdGPINCyINC+0LTQvdC+0Lkg0YHRgtGA0L7QutC1LgpxdWVyeS5maWx0ZXIoJ3RpdGxlID0nLCAnRm9vJykub3JkZXIoJy1kYXRlJykuYW5jZXN0b3Ioa2V5KQo==

Интерфейс GqlQuery

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

CiMg0J/QsNGA0LDQvNC10YLRgNGLINC80L7Qs9GD0YIg0YPQutCw0LfRi9Cy0LDRgtGM0YHRjyDRgSDQv9C+0LzQvtGJ0YzRjiDQv9C+0LfQuNGG0LjQvtC90L3Ri9GFINCw0YDQs9GD0LzQtdC90YLQvtCyLgpxdWVyeSA9IGRiLkdxbFF1ZXJ5KCJTRUxFQ1QgKiBGUk9NIFN0b3J5IFdIRVJFIHRpdGxlID0gOjEgIgoiQU5EIEFOQ0VTVE9SIElTIDoyICIKIk9SREVSIEJZIGRhdGUgREVTQyIsCidGb28nLCBrZXkpCiMg0JjQu9C4INCx0YvRgtGMINC30LDQtNCw0L3RiyDRgSDQv9C+0LzQvtGJ0YzRjiDQuNC80LXQvdC+0LLQsNC90L3Ri9GFLgpxdWVyeSA9IGRiLkdxbFF1ZXJ5KCJTRUxFQ1QgKiBGUk9NIFN0b3J5IFdIRVJFIHRpdGxlID0gOnRpdGxlICIKIkFORCBBTkNFU1RPUiBJUyA6cGFyZW50ICIKIk9SREVSIEJZIGRhdGUgREVTQyIsCnRpdGxlPSdGb28nLCBwYXJlbnQ9a2V5KQojINCX0L3QsNGH0LXQvdC40Y8g0YLQuNC/0LAg0YHRgtGA0L7QutCwLCDRh9C40YHQu9C+INC4INC70L7Qs9C40YfQtdGB0LrQuNC5INGC0LjQvyDQvNC+0LPRg9GCINCx0YvRgtGMINC30LDQtNCw0L3RiyDQv9GA0Y/QvNC+INCyINGB0YLRgNC+0LrQtSDQt9Cw0L/RgNC+0YHQsApxdWVyeSA9IGRiLkdxbFF1ZXJ5KCJTRUxFQ1QgKiBGUk9NIFN0b3J5IFdIRVJFIHRpdGxlID0gJ0ZvbycgIgoiQU5EIEFOQ0VTVE9SIElTIDpwYXJlbnQgIgoiT1JERVIgQlkgZGF0ZSBERVNDIiwKcGFyZW50PWtleSkK=

Метод gql() класса Model также выполняет формирование объекта GqlQuery с использованием строки запроса. В строке с GQL запросом часть, начинающаяся на SELECT * FROM Model, опускается, так как она уже подразумевается этой конструкцией.

CnF1ZXJ5ID0gU3RvcnkuZ3FsKCJXSEVSRSB0aXRsZSA9IDp0aXRsZSAiCiJBTkQgQU5DRVNUT1IgSVMgOnBhcmVudCAiCiJPUkRFUiBCWSBkYXRlIERFU0MiLAp0aXRsZT0nRm9vJywgcGFyZW50PWtleSkK=

Параметрам готового запроса могут быть присвоены другие значения с использованием метода bind(). Приложение может повторно использовать объект типа GqlQuery путем изменения его параметров и повторного выполнения запроса.

Выполнение запроса и получение результатов

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

Метод fetch() принимает в качестве своих параметров обязательный: максимальное число результатов для загрузки (limit) и опциональный: количество объектов, которые необходимо будет пропустить от начала набора данных (offset). Этот метод выполняет сформированный запрос и загружает его результаты до тех пор, пока не достигнет заданного лимита или конца выборки. Когда результаты запроса загружаются в память, система производит пропуск заданного числа объектов, остальная часть возвращается списком экземпляров класса модели. Запрос загружает все данные целиком при каждом вызове метода fetch().

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

CnJlc3VsdHMgPSBxdWVyeS5mZXRjaCgxMCkKZm9yIHJlc3VsdCBpbiByZXN1bHRzOgpwcmludCAiVGl0bGU6ICIgKyByZXN1bHQudGl0bGUK=

Параметры ограничения числа результатов и смещение (limit и offset), передаваемые методу fetch() перекрывают все заданные ранее аналогичные параметры в строке запроса, сформированной с помощью языка GQL.

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

CmZvciByZXN1bHQgaW4gcXVlcnk6CnByaW50ICJUaXRsZTogIiArIHJlc3VsdC50aXRsZQo==

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

Получение объекта с помощью его ключа

После того, как хранилище выполняет операцию по сохранению нового объекта, он получает уникальный ключ. В рассматриваемом интерфейсе эти значения представляют собой экземпляры класса Key. Метод put() экземпляра класса модели и функция db.put() возвращают соответствующий сохраненному объекту экземпляр класса Key. После выполнения первой операции по сохранению объекта, метод key() экземпляра класса модели также будет возвращать соответствующий объект типа Key.

CmVudGl0eS5wdXQoKQprZXkgPSBlbnRpdHkua2V5KCkKIyAuLi4KZW50aXR5ID0gZGIuZ2V0KGtleSkK=

Предназначение объекта Key состоит в возможности задания с помощью его значения ссылки на другой объект хранилища. Свойство модели ReferenceProperty производит автоматическое связывание экземпляров класса моделей с помощью их ключей: когда свойству типа ReferenceProperty присваивается значение экземпляра класса, то будет использовано значение его ключа.

CmNsYXNzIFBldChkYi5Nb2RlbCk6Cm5hbWUgPSBTdHJpbmdQcm9wZXJ0eSgpCm93bmVyID0gUmVmZXJlbmNlUHJvcGVydHkoUGV0T3duZXIpCmNsYXNzIFBldE93bmVyKGRiLk1vZGVsKToKbmFtZSA9IFN0cmluZ1Byb3BlcnR5KCkKb3duZXIgPSBQZXRPd25lcihuYW1lPSJBbGJlcnQiKQpwZXQgPSBQZXQobmFtZT0iRmx1ZmZ5Iiwgb3duZXI9b3duZXIpCiMg0K3QutCy0LjQstCw0LvQtdC90YLQvdC+INC/0YDQtdC00YvQtNGD0YnQtdC80YM6CnBldCA9IFBldChuYW1lPSJGbHVmZnkiLCBvd25lcj1vd25lci5rZXkoKSkK=

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

CnBldHMgPSBHcWxRdWVyeSgiU0VMRUNUICogRlJPTSBQZXQgV0hFUkUgbmFtZSA9IDoxIiwgIkZsdWZmeSIpCnBldCA9IHBldHMuZ2V0KCkKb3duZXJfbmFtZSA9IHBldC5vd25lci5uYW1lCg===

Значения ключей объектов, сохраняемые без использования типа ReferenceProperty (например, динамические свойства расширенных моделей или свойства типа ListProperty) не будут иметь возможностей по автоматическому связыванию объектов.

Функция db.get() производит загрузку объекта из хранилища с помощью указания его ключа (или списка ключей для множества объектов).

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

Cm9iaiA9IE15TW9kZWwobmFtZT0iRm9vIikKc2VsZi5yZXNwb25zZS53cml0ZSgnJmx0O2EgaHJlZj0iL3ZpZXc/a2V5PSVzIiZndDslcyZsdDsvYSZndDsnICUgKHN0cihvYmoua2V5KCkpLApvYmoubmFtZSgpKSkKIyAuLi4Ka2V5X25hbWUgPSBzZWxmLnJlcXVlc3QuZ2V0KCdrZXknKQpvYmogPSBkYi5nZXQoZGIuS2V5KGtleV9uYW1lKSkK=

Примечание: Хотя и строковое представление ключа нечитаемо, шифрация его значения не проводится. Если приложению требуется скрыть содержимое ключа объекта, то ему необходимо выполнить дополнительные преобразования или шифрацию перед тем, как ключ будет отправлен пользователю.

Удаление объекта

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

CnEgPSBkYi5HcWxRdWVyeSgiU0VMRUNUICogRlJPTSBNZXNzYWdlIFdIRVJFIGNyZWF0ZV9kYXRlICZsdDsgOjEiLCBlYXJsaWVzdF9kYXRlKQpyZXN1bHRzID0gcS5mZXRjaCgxMCkKZm9yIHJlc3VsdCBpbiByZXN1bHRzOgpyZXN1bHQuZGVsZXRlKCkKIyDQpNGD0L3QutGG0LjRjyBkYi5kZWxldGUoKSDRgtGA0LXQsdGD0LXRgiwg0YfRgtC+0LHRiyDQstGB0LUg0L7QsdGK0LXQutGC0YssINGD0LTQsNC70Y/QtdC80YvQtSDQt9CwINC+0LTQuNC9INCy0YvQt9C+0LIKIyDQv9GA0LjQvdCw0LTQu9C10LbQsNC70Lgg0L7QtNC90L7QuSDQs9GA0YPQv9C/0LUsINGC0LDQuiDQutCw0Log0L/RgNC+0YbQtdC00YPRgNCwINGD0LTQsNC70LXQvdC40Y8g0LjRgdC/0L7Qu9GM0LfRg9C10YIg0YLRgNCw0L3Qt9Cw0LrRhtC40Y4uCnEgPSBkYi5HcWxRdWVyeSgiU0VMRUNUICogRlJPTSBNZXNzYWdlIFdIRVJFIGNyZWF0ZV9kYXRlICZsdDsgOjEiICsKIkFORCBBTkNFU1RPUiBJUyA6MiIsCmVhcmxpZXN0X2RhdGUsIHBhcmVudCkKcmVzdWx0cyA9IHEuZmV0Y2goMTApCmRiLmRlbGV0ZShyZXN1bHRzKQo==

Процедура удаления объектов не влияет на другие объекты хранилища, которые могут ссылаться на удаляемый. Если ваше приложение может использовать запрос, содержащий ссылку на удаленный объект, то необходимо с помощью функции db.get() выполнять тестирование возвращаемого результата до его использования приложением.

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