Обновлена 22 июня 2026 г. в 15:31

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

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

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

model_accessor

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

CRUD

В примерах, приведенных в этом справочнике, используется модель данных из раздела Определение модели данных руководства разработчика.

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

Пример

Запрос вычисляет количество городов, в которых живет более 1000000 человек:


model_accessor.count(  "City",  {{"population", ">", 1000000}})

Example

find(type_name, filter[, options])

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

Параметры:

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

Возвращает

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

Тип возвращаемого значения

table

Пример

Запроc возвращает города с названием Moscow и населением population больше 1000000 человек:


model_accessor.find(  "City",  {{"title", "==", "Moscow"},  {"population", ">", 1000000}})

Example

get(type_name, filter[, options])

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

Параметры:

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

Возвращает

объект

Тип возвращаемого значения

table

Пример


model_accessor.get("Country", {"Russia"})

Example

delete(type_name, filter[, options])

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

Параметры:

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

Возвращает

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

Тип возвращаемого значения

number

Пример

Запрос удаляет объект по первичному составному ключу:


model_accessor.delete(  "City",  {{"primary", "==", {"Saint Petersburg", "Russia"}}})

Example

put(type_name, object[, options])

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

Параметры:

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

Возвращает

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

Тип возвращаемого значения

number

Пример

Запрос добавляет объект с первичным ключом title:


model_accessor.put(  "Country",  {title = "Germany", phone_code = "+49"})

Example

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.update(  "City",  {{"primary", "==", {"Saint Petersburg", "Russia"}},  {{"set", "population", 56523922},  {"set", "postcodes", {190000, 190001, 190002, 190003, 190004}}})

Example

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

begin_transaction()

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

Возвращает

none

commit_transaction()

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

Возвращает

none

rollback_transaction()

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

Возвращает

none

is_in_transaction()

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

Возвращает

true при наличии активной транзакции, иначе - false

Тип возвращаемого значения

boolean

Утилиты

unflatten(type_name, tuple)

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

Параметры:

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

Возвращает

Lua-таблица

Тип возвращаемого значения

table

is_read_only()

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

Возвращает

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

Тип возвращаемого значения

boolean

snapshot()

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

Возвращает

результат выполнения операции - ok, если снимок создан успешно

Тип возвращаемого значения

string

blob_storage

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

new(namespace)

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

Параметры:

namespace (string) — имя хранилища

Возвращает

указатель на созданное хранилище

Тип возвращаемого значения

table

local_cache

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

set(key, val)

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

Параметры:

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

Возвращает

none

get(key)

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

Параметры:

key (string) — ключ

Возвращает

значение для переданного ключа

Тип возвращаемого значения

any

shared_storage

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

function new(namespace)

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

namespace (string) — имя хранилища

Возвращает

указатель на созданное хранилище

Тип возвращаемого значения

table

Пример

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


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 в коннектор.

send(output_name, obj[, output_options])

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

Параметры:

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

Возвращает

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

Тип возвращаемого значения

boolean

odbc

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

execute(connection_name, statement, params)

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

Параметры:

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

Возвращает

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

Тип возвращаемого значения

object

prepare(connection_name, query)

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

Параметры:

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

Возвращает

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

Тип возвращаемого значения

object

oracle

Доступно с версии 2.17.0.

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

execute(connection_name, statement, params)

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

Параметры:

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

Возвращает

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

Тип возвращаемого значения

object

cursor(sql [, args, opts])

Создает курсор для получения результатов SELECT.

Параметры:

sql (string) — SELECT-запрос SQL
args (table) — аргументы запроса
opts (table) — дополнительные параметры. Доступные параметры:
- scrollable - включить режим прокрутки курсора. Значение по умолчанию: false.

Возвращает

cursor - объект курсора в случае успеха, иначе nil
- err (опционально) - таблица с ошибкой

Тип возвращаемого значения

object

Была ли статья полезна?

Содержание
model_accessor
blob_storage
local_cache
shared_storage
connector
odbc
oracle
Была ли статья полезна?