Доступ к данным¶

Основные функции для доступа к данным в TDG входят в программный интерфейс репозитория. Кроме этого, для работы доступны следующие модули:

model_accessor – доступ к данным на экземпляре с ролью storage. Модуль включает в себя группы функций:
blob_storage – key-value хранилище на базе движка vinyl;
local_cache – локальный кэш;
shared_storage – распределенный кэш;
connector – работа с коннекторами;
odbc – работы с API ODBC.

model_accessor¶

Модуль model_accessor содержит функции для доступа к данным на экземпляре с ролью storage.

CRUD¶

Note

Все запросы ниже, за исключением put(), поддерживают параметр filter, позволяющий задать условия фильтрации объектов. Узнать больше об этом параметре можно в разделе Repository API.

model_accessor.count(type_name, filter[, options])¶

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

Parameters

type_name (string) – тип объекта
filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа
options (table) –
параметры для управления запросом. Доступные параметры:
- first – количество элементов. Значение по умолчанию: 10;
- after – курсор пагинации на первый элемент;
- version – версия объекта. Параметр применяется только при включенном версионировании. Если параметр задан, обрабатывается указанная версия объекта. Если такой версии не существует, обрабатывается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия. Если вместе с этим параметром задан параметр all_versions, то обрабатываются все версии меньше или равные заданной;
- all_versions – поиск по всем версиям объекта, если задано значение true. Параметр применяется только при включенном версионировании. По умолчанию: false;
- indexed_by – индекс, по которому выполняется поиск. Используется, если необходимо явным образом указать индекс.

Returns

количество записей, соответствующих фильтру

Return type

number

model_accessor.find(type_name, filter[, options])¶

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

Parameters

type_name (string) – тип объекта
filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа
options (table) –
параметры для управления запросом. Доступные параметры:
- first – количество возвращаемых элементов. Значение по умолчанию: 10;
- after – курсор пагинации на первый элемент;
- all_versions – поиск по всем версиям объекта, если задано значение true. Параметр применяется только при включенном версионировании. По умолчанию: false;
- version – версия объекта, которая будет возвращена. Параметр применяется только при включенном версионировании. Если параметр задан, возвращается указанная версия объекта. Если такой версии не существует, возвращается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия. Если вместе с этим параметром задан параметр all_versions, то обрабатываются все версии меньше или равные заданной.

Returns

таблица объектов, соответствующих заданным условиям

Return type

table

model_accessor.get(type_name, filter[, options])¶

Получает объект по первичному ключу. Если тип объекта поддерживает версионирование, метод возвращает указанную версию объекта.

Parameters

type_name (string) – тип объекта
filter (table) – первичный ключ
options (table) –
параметры для управления запросом. Доступные параметры:
- first – количество возвращаемых элементов. Значение по умолчанию: 10;
- after – курсор пагинации на первый элемент;
- version – версия объекта, которая будет получена. Параметр применяется только при включенном версионировании. Если параметр задан, возвращается указанная версия объекта. Если такой версии не существует, возвращается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия;
- all_versions – указатель для поиска по всем версиям объекта, если задано значение true. Параметр применяется только при включенном версионировании. По умолчанию: false.

Returns

объект

Return type

table

model_accessor.delete(type_name, filter[, options])¶

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

Parameters

type_name (string) – тип объекта
filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа
options (table) –
параметры для управления запросом. Доступные параметры:
- first – количество возвращаемых элементов. Значение по умолчанию: 10;
- version – версия объекта для удаления. Параметр применяется только при включенном версионировании. Если параметр задан, удаляется указанная версия объекта. Если такой версии не существует, удаляется ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия;
- only_if_version – проверка имеющейся версии перед удалением. Параметр применяется только при включенном версионировании. При указанном параметре объект удаляется, только если последняя версия объекта совпадает с указанной;
- indexed_by – индекс, по которому выполняется поиск. Используется, если необходимо явным образом указать индекс.

Returns

количество удаленных объектов

Return type

number

model_accessor.put(type_name, object[, options])¶

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

Parameters

type_name (string) – тип объекта
object (table) – объект для вставки
options (table) –
параметры для управления запросом. Доступные параметры:
- version – версия объекта, которая будет добавлена или заменена. Параметр применяется только при включенном версионировании. Если параметр задан, заменяется указанная версия объекта. Если такой версии не существует, заменяется ближайшая предшествующая версия. Объект при этом сохраняется с той же версией. Если параметр не задан, запрос получает последнюю версию объекта и вставляет новую версию объекта. Значение по умолчанию: целое монотонно возрастающее число;
- only_if_version – проверка имеющейся версии перед вставкой. Параметр применяется только при включенном версионировании. При указанном параметре запрос добавляет или заменяет объект, только если последняя версия объекта совпадает с указанной;
- if_not_exists – проверка имеющегося объекта перед вставкой. По умолчанию: false. Если задано значение true, система проверяет, существует ли уже такой объект в хранилище. Новый объект будет добавлен, если его еще нет в хранилище.

Returns

количество измененных объектов

Return type

number

model_accessor.update(type_name, filter, updaters[, options])¶

Обновляет объекты, соответствующие заданным условиям. Если тип объекта поддерживает версионирование, метод сохраняет новую версию объекта или обновляет существующую.

Parameters

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 – индекс, по которому выполняется поиск. Используется, если необходимо явным образом указать индекс.

Returns

количество обновленных объектов

Return type

number

Управление транзакциями¶

model_accessor.begin_transaction()¶

Начинает транзакцию. Аналог функции box.begin().

Returns: none

model_accessor.commit_transaction()¶

Завершает транзакцию и сохраняет все изменения. Аналог функции box.commit().

Returns: none

model_accessor.rollback_transaction()¶

Завершает транзакцию без сохранения изменений. Аналог функции box.rollback().

Returns: none

model_accessor.is_in_transaction()¶

Проверяет наличие активной транзакции. Аналог функции box.is_in_txn().

Returns: true при наличии активной транзакции, иначе – false
Return type: boolean

Утилиты¶

model_accessor.unflatten(type_name, tuple)¶

Преобразует плоский кортеж в Lua-таблицу.

Parameters

type_name (string) – тип объекта
tuple (table/tuple) – кортеж, который требуется преобразовать

Returns

Lua-таблица

Return type

table

model_accessor.is_read_only()¶

Возвращает значение параметра box.info.ro – true или false.

Returns: true, если экземпляр находится в режиме read-only или в статусе orphan, иначе false.
Return type: boolean

model_accessor.snapshot()¶

Создает снимок всех данных и сохраняет его. Аналог функции box.snapshot

Returns: результат выполнения операции – ok, если снимок создан успешно
Return type: string

blob_storage¶

Модуль blob_storage содержит функции для работы с key-value хранилищем на базе движка vinyl.

blob_storage.new(namespace)¶

Создает новое key-value хранилище.

Parameters: namespace (string) – имя хранилища
Returns: указатель на созданное хранилище
Return type: table

local_cache¶

Модуль local_cache содержит функции для доступа к локальному кэшу. Локальный кэш представляет собой Lua-таблицу, с которой можно работать (добавлять и получать данные) в рамках одного экземпляра.

local_cache.set(key, val)¶

Задает в таблице пару ключ–значение.

Parameters

key (string) – ключ
val (any) – значение

Returns

none

local_cache.get(key)¶

Получает значение из таблицы по переданному ключу.

Parameters: key (string) – ключ
Returns: значение для переданного ключа
Return type: any

shared_storage¶

Модуль shared_storage содержит функции для работы с распределенным кэшем. Распределенный кэш можно использовать для передачи объектов между функциями и экземплярами TDG.

shared_storage.new(namespace)¶

Создает новый распределенный кэш.

Parameters: namespace (string) – имя хранилища
Returns: указатель на созданное хранилище
Return type: table

Note

При создании распределенного кэша создаётся спейс, хранящийся на одном из наборов реплик с ролью storage. Персистентность данных в распределенном кэше не гарантируется: данные из него могут быть потеряны, например, при перезапуске кластера.

Пример

Чтобы подключить существующий распределенный кэш или создать новый, используйте следующую команду:

local shared_storage_object = shared_storage.new('some_namespace')

Данные в распределенный кэш помещаются в формате key, value, например:

shared_storage_object:set('abc', 123)

где 'abc' – это ключ (key), а 123 – значение (value).

Для получения данных из распределенного кэша выполните следующую команду:

shared_storage_object:get('abc')

connector¶

Модуль connector содержит функции для отправки данных из sandbox в коннектор.

connector.send(output_name, obj[, output_options])¶

Направляет объект в секцию output для отправки в смежную систему.

Parameters

output_name (string) – имя коннектора
obj (object) – объект для отправки
output_options (table) – опции для отправки во внешнюю систему

Returns

true в случае успешной отправки, false в случае возникновения ошибки

Return type

boolean

odbc¶

Модуль odbc содержит функции для работы с API ODBC.

odbc.execute(connection_name, statement, params)¶

Выполняет запрос через ODBC c заданными параметрами.

Parameters

connection_name (string) – название соединения
statement (string) – выполняемый запрос
params (table) – параметры запроса

Returns

объект запроса

Return type

object

odbc.prepare(connection_name, query)¶

Подготавливает запрос через ODBC.

Parameters

connection_name (string) – название соединения
query (string) – запрос

Returns

объект подготовленного запроса

Return type

object

Version:

Доступ к данным¶

model_accessor¶

CRUD¶

Управление транзакциями¶

Утилиты¶

blob_storage¶

local_cache¶

shared_storage¶

connector¶

odbc¶