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

Основные функции для доступа к данным в 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

shared_storage¶

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

shared_storage.new(namespace)¶

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

Параметры: namespace (string) – имя хранилища
Результат: указатель на созданное хранилище
Тип результата: table

Примечание

При создании распределенного кэша создаётся спейс, хранящийся на одном из наборов реплик с ролью 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 для отправки в смежную систему.

Параметры

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

Версия:

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

model_accessor¶

CRUD¶

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

Утилиты¶

blob_storage¶

local_cache¶

shared_storage¶

connector¶

odbc¶