Доступ к данным¶
Основные функции для доступа к данным в TDG входят в программный интерфейс репозитория. Кроме этого, для работы доступны следующие модули:
model_accessor – доступ к данным на экземпляре с ролью
storage
. Модуль включает в себя группы функций:blob_storage – key-value хранилище на базе движка vinyl;
local_cache – локальный кэш;
shared_storage – распределенный кэш;
connector – работа с коннекторами;
odbc – работы с API ODBC.
model_accessor¶
Модуль model_accessor
содержит функции для доступа к данным на экземпляре с ролью storage
.
CRUD¶
Примечание
Все запросы ниже, за исключением put()
, поддерживают параметр filter
, позволяющий задать условия фильтрации
объектов. Узнать больше об этом параметре можно в разделе Repository API.
- model_accessor.count(type_name, filter[, options])¶
Вычисляет количество записей, соответствующих заданным условиям. Если тип объекта поддерживает версионирование, метод обрабатывает указанную версию объекта.
- Параметры
type_name (string) – тип объекта
filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа
options (table) –
параметры для управления запросом. Доступные параметры:
first
– количество элементов. Значение по умолчанию: 10;after
– курсор пагинации на первый элемент;version
– версия объекта. Параметр применяется только при включенном версионировании. Если параметр задан, обрабатывается указанная версия объекта. Если такой версии не существует, обрабатывается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия. Если вместе с этим параметром задан параметрall_versions
, то обрабатываются все версии меньше или равные заданной;all_versions
– поиск по всем версиям объекта, если задано значениеtrue
. Параметр применяется только при включенном версионировании. По умолчанию:false
;indexed_by
– индекс, по которому выполняется поиск. Используется, если необходимо явным образом указать индекс.
- Результат
количество записей, соответствующих фильтру
- Тип результата
number
- model_accessor.find(type_name, filter[, options])¶
Возвращает объекты, соответствующие заданным условиям. Пагинация осуществляется аналогично операциям интерфейса репозитория TDG. Если тип объекта поддерживает версионирование, метод возвращает указанную версию объекта.
- Параметры
type_name (string) – тип объекта
filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа
options (table) –
параметры для управления запросом. Доступные параметры:
first
– количество возвращаемых элементов. Значение по умолчанию: 10;after
– курсор пагинации на первый элемент;all_versions
– поиск по всем версиям объекта, если задано значениеtrue
. Параметр применяется только при включенном версионировании. По умолчанию:false
;version
– версия объекта, которая будет возвращена. Параметр применяется только при включенном версионировании. Если параметр задан, возвращается указанная версия объекта. Если такой версии не существует, возвращается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия. Если вместе с этим параметром задан параметрall_versions
, то обрабатываются все версии меньше или равные заданной.
- Результат
таблица объектов, соответствующих заданным условиям
- Тип результата
table
- model_accessor.get(type_name, filter[, options])¶
Получает объект по первичному ключу. Если тип объекта поддерживает версионирование, метод возвращает указанную версию объекта.
- Параметры
type_name (string) – тип объекта
filter (table) – первичный ключ
options (table) –
параметры для управления запросом. Доступные параметры:
first
– количество возвращаемых элементов. Значение по умолчанию: 10;after
– курсор пагинации на первый элемент;version
– версия объекта, которая будет получена. Параметр применяется только при включенном версионировании. Если параметр задан, возвращается указанная версия объекта. Если такой версии не существует, возвращается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия;all_versions
– указатель для поиска по всем версиям объекта, если задано значениеtrue
. Параметр применяется только при включенном версионировании. По умолчанию:false
.
- Результат
объект
- Тип результата
table
- model_accessor.delete(type_name, filter[, options])¶
Удаляет объекты, соответствующие заданным условиям. Поддерживает оптимистичные блокировки. Если тип объекта поддерживает версионирование, метод удаляет указанную версию объекта.
- Параметры
type_name (string) – тип объекта
filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа
options (table) –
параметры для управления запросом. Доступные параметры:
first
– количество возвращаемых элементов. Значение по умолчанию: 10;version
– версия объекта для удаления. Параметр применяется только при включенном версионировании. Если параметр задан, удаляется указанная версия объекта. Если такой версии не существует, удаляется ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия;only_if_version
– проверка имеющейся версии перед удалением. Параметр применяется только при включенном версионировании. При указанном параметре объект удаляется, только если последняя версия объекта совпадает с указанной;indexed_by
– индекс, по которому выполняется поиск. Используется, если необходимо явным образом указать индекс.
- Результат
количество удаленных объектов
- Тип результата
number
- model_accessor.put(type_name, object[, options])¶
Вставляет новый или заменяет существующий объект. Поддерживает оптимистичные блокировки. Если тип объекта поддерживает версионирование, метод вставляет новую версию объекта или заменяет существующую.
- Параметры
type_name (string) – тип объекта
object (table) – объект для вставки
options (table) –
параметры для управления запросом. Доступные параметры:
version
– версия объекта, которая будет добавлена или заменена. Параметр применяется только при включенном версионировании. Если параметр задан, заменяется указанная версия объекта. Если такой версии не существует, заменяется ближайшая предшествующая версия. Объект при этом сохраняется с той же версией. Если параметр не задан, запрос получает последнюю версию объекта и вставляет новую версию объекта. Значение по умолчанию: целое монотонно возрастающее число;only_if_version
– проверка имеющейся версии перед вставкой. Параметр применяется только при включенном версионировании. При указанном параметре запрос добавляет или заменяет объект, только если последняя версия объекта совпадает с указанной;if_not_exists
– проверка имеющегося объекта перед вставкой. По умолчанию:false
. Если задано значениеtrue
, система проверяет, существует ли уже такой объект в хранилище. Новый объект будет добавлен, если его еще нет в хранилище.
- Результат
количество измененных объектов
- Тип результата
number
- model_accessor.update(type_name, filter, updaters[, options])¶
Обновляет объекты, соответствующие заданным условиям. Если тип объекта поддерживает версионирование, метод сохраняет новую версию объекта или обновляет существующую.
- Параметры
type_name (string) – тип объекта
filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа
updaters (table) –
список обновлений для объекта, состоящий из списка мутаторов
{{mutator, path, new_value}, ...}
, где:mutator
– имя мутатора, например:set
– устанавливает значение;add
– увеличивает значение на указанное число;sub
– уменьшает значение на указанное число;
path
– строковый путь до поля объекта с точкой-разделителем (.
). Путь до объекта(ов) массива должен включать индекс массива или символ*
для захвата всех вложенных объектов;new_value
– новое значение;
options (table) –
параметры для управления запросом. Доступные параметры:
first
– количество возвращаемых элементов. Значение по умолчанию: 10;version
– версия объекта, которая будет изменена. Параметр применяется только при включенном версионировании. Если параметр задан, обновляется указанная версия объекта. Если такой версии не существует, обновляется ближайшая предшествующая версия. Объект обновляется, и результат сохраняется с той же версией. Если параметр не задан, запрос получает последнюю версию объекта и сохраняет новую версию объекта. Значение по умолчанию: целое монотонно возрастающее число;only_if_version
– проверка имеющейся версии перед обновлением. Параметр применяется только при включенном версионировании. При указанном параметре объект обновляется, только если последняя версия объекта совпадает с указанной;indexed_by
– индекс, по которому выполняется поиск. Используется, если необходимо явным образом указать индекс.
- Результат
количество обновленных объектов
- Тип результата
number
Управление транзакциями¶
- model_accessor.begin_transaction()¶
Начинает транзакцию. Аналог функции box.begin().
- Результат
none
- model_accessor.commit_transaction()¶
Завершает транзакцию и сохраняет все изменения. Аналог функции box.commit().
- Результат
none
- model_accessor.rollback_transaction()¶
Завершает транзакцию без сохранения изменений. Аналог функции box.rollback().
- Результат
none
- model_accessor.is_in_transaction()¶
Проверяет наличие активной транзакции. Аналог функции box.is_in_txn().
- Результат
true
при наличии активной транзакции, иначе –false
- Тип результата
boolean
Утилиты¶
- model_accessor.unflatten(type_name, tuple)¶
Преобразует плоский кортеж в Lua-таблицу.
- Параметры
type_name (string) – тип объекта
tuple (table/tuple) – кортеж, который требуется преобразовать
- Результат
Lua-таблица
- Тип результата
table
- model_accessor.is_read_only()¶
Возвращает значение параметра box.info.ro –
true
илиfalse
.- Результат
true
, если экземпляр находится в режимеread-only
или в статусе orphan, иначеfalse
.- Тип результата
boolean
- model_accessor.snapshot()¶
Создает снимок всех данных и сохраняет его. Аналог функции box.snapshot
- Результат
результат выполнения операции –
ok
, если снимок создан успешно- Тип результата
string
blob_storage¶
Модуль blob_storage
содержит функции для работы с key-value хранилищем на базе
движка vinyl.
- blob_storage.new(namespace)¶
Создает новое key-value хранилище.
- Параметры
namespace (string) – имя хранилища
- Результат
указатель на созданное хранилище
- Тип результата
table
local_cache¶
Модуль local_cache
содержит функции для доступа к локальному кэшу.
Локальный кэш представляет собой Lua-таблицу, с которой можно работать (добавлять и получать данные) в рамках одного
экземпляра.
- local_cache.set(key, val)¶
Задает в таблице пару ключ–значение.
- Параметры
key (string) – ключ
val (any) – значение
- Результат
none
- local_cache.get(key)¶
Получает значение из таблицы по переданному ключу.
- Параметры
key (string) – ключ
- Результат
значение для переданного ключа
- Тип результата
any
connector¶
Модуль connector
содержит функции для отправки данных из sandbox в коннектор.
- connector.send(output_name, obj[, output_options])¶
Направляет объект в секцию
output
для отправки в смежную систему.- Параметры
output_name (string) – имя коннектора
obj (object) – объект для отправки
output_options (table) – опции для отправки во внешнюю систему
- Результат
true
в случае успешной отправки,false
в случае возникновения ошибки- Тип результата
boolean
odbc¶
Модуль odbc
содержит функции для работы с API ODBC.
- odbc.execute(connection_name, statement, params)¶
Выполняет запрос через ODBC c заданными параметрами.
- Параметры
connection_name (string) – название соединения
statement (string) – выполняемый запрос
params (table) – параметры запроса
- Результат
объект запроса
- Тип результата
object
- odbc.prepare(connection_name, query)¶
Подготавливает запрос через ODBC.
- Параметры
connection_name (string) – название соединения
query (string) – запрос
- Результат
объект подготовленного запроса
- Тип результата
object