Repository API¶
Sandbox API включает в себя модуль repository
– интерфейс репозитория TDG.
Этот модуль предоставляет функции для работы с шардированным хранилищем.
Функции позволяют выполнять следующие действия с данными:
операции выбора, вставки, изменения и удаления данных;
управление процессом обработки данных.
Все запросы к данным в TDG от внешних информационных систем, включая GraphQL-запросы (а также запросы, выполняемые во вкладке GraphQL), реализованы на основе функций программного интерфейса репозитория.
Доступные функции:
repository.find() – выборка по полям объектов одного типа, включая несколько условий;
repository.get() – выбор одного кортежа по индексу;
repository.put() – вставка нового или замена существующего объекта;
repository.put_batch() – вставка нового или замена существующего массива;
repository.update() – обновление объектов;
repository.update_batch() – вызов нескольких обновлений объектов в одном запросе;
repository.delete() – удаление объектов;
repository.count() – количество объектов, соответствующих заданному условию;
repository.pairs() – создание итератора;
repository.call_on_storage() – вызов функции на экземпляре с ролью
storage
для локальной обработки данных;repository.call_on_storage_batch() – вызов нескольких функций на экземпляре с ролью
storage
;repository.push_job() – отложенный запуск задач и функций;
repository.map_reduce() – сложная агрегация по кластеру.
Функции find()
, update()
, update-batch()
, delete
и count()
поддерживают
порядковую нумерацию страниц (пагинацию).
Для этого используются параметры:
first
иafter
– в функцияхfind()
иcount()
;first_n_on_storage
иafter
– в функцияхupdate()
,update_batch()
иdelete()
.
Все функции модуля, кроме call_on_storage()
и push_job()
, поддерживают версионирование – получение
или обработку объектов, которые предшествуют или равны определённой версии.
Фильтрация объектов¶
Для выбора нужных объектов запросы применяют условия-предикаты, или фильтры.
Предикаты указываются в параметре filter
в формате булевых выражений.
Синтаксис предикатов¶
В запросах предикаты (filter
) записываются в виде:
{{left, comparator, right}, ...}
где:
left
– левая часть выражения. Содержит один из двух вариантов:полный путь к полю объекта (
Customer.first_name
);название индекса (
id
);
comparator
– оператор сравнения:">"
,">="
,"=="
,"<="
,"<"
;right
– правая часть выражения. Содержит один из двух вариантов:полный путь к полю объекта (
Customer.first_name
);строковое значение, численное значение, булево значение или таблица.
Если в предикате несколько условий, по умолчанию они объединяются логической операцией and
(конъюнкцией).
Примеры предикатов:
{{"id", ">", 10}}
{{"id", ">", 10}, {"id", "<", 100}}
{{"Customer.first_name", "==", "Ivan"}, {"birth_year", "==", 1990}}
{{"Customer.first_name", "==", "Ivan"}, {"reg_date", "==", {1990, 04, 23}}}
Как работают фильтры¶
Все условия-предикаты в параметре filter
проверяются по очереди, чтобы
определить основной фильтр для сканирования.
Остальные фильтры используются как дополнительные условия при прохождении по индексу.
При выборе основного фильтра соблюдается следующий порядок:
Если в списке условий есть фильтр по индексу, он используется в качестве основного и задает индекс для сканирования;
Если в запросе нет фильтра по индексу, проверяются фильтры по полю. Если при этом какое-то поле является первым в составном индексе, используется этот составной индекс.
Если нет ни одного подходящего индекса, идет полное сканирование спейса по первичному ключу.
При этом в версиях до 2.7.0 TDG использует ограничение на полное сканирование спейса (параметр
scanned
в секции hard-limits конфигурации). По умолчанию при выполнении запроса сканируются 2000 кортежей.Начиная с версии 2.7.0, вместо ограничения
scanned
дляhard-limits
TDG использует механизм fiber.slice;Если условие содержит операторы like или ilike, такое условие не может задавать индекс для сканирования.
Для примера определим модель данных с двумя типами объектов: Client
и Passport
:
[
{
"name": "Passport",
"type": "record",
"fields": [
{"name": "id", "type": "long"},
{"name": "passport_series", "type": "string"},
{"name": "passport_number", "type": "string"},
{"name": "expired_flag", "type": "boolean"}
],
"indexes": [
"id",
{
"name": "passport",
"parts": ["passport_series", "passport_number"]
}
]
},
{
"name": "Client",
"type": "record",
"fields": [
{"name": "id", "type": "long"},
{"name": "first_name", "type": "string"},
{"name": "last_name", "type": "string"},
{"name": "passports", "type": {"type": "array", "items": "Passport"}}
],
"indexes": ["id"]
}
]
Пример 1
Запрос возвращает клиентов по имени Ivan
с id
больше 40:
repository.find(
"Client",
{{"first_name", "==", "Ivan"},
{"id", ">", 40}})
В запросе указаны:
фильтр по индексу
id
– первичный ключ, по которому ведется сканирование;фильтр по полю
first_name
– дополнительное условие поиска.
Пример 2
Запрос возвращает клиентов по имени Ivan
, у которых первый паспорт имеет указанную серию:
repository.find(
"Client",
{{"first_name", "==", "Ivan"},
{"passports.1.passport_series", "==", "012345"}})
В запросе указаны два фильтра по полю. При этом поле passport_series
– часть составного индекса passport
.
Сканирование идет по индексу passport
.
Пример 3
Запрос возвращает клиентов, у которых истек срок действия первого паспорта:
repository.find(
"Client",
{{"first_name", "==", "Ivan"}
{"last_name", "==", "Petrov"},
{"passports.1.expired_flag", "==", "false"}})
Среди условий нет подходящего индекса (в том числе составного), так что начинается полное сканирование по первичному ключу.
Оптимистичные блокировки¶
Внесение параллельных изменений из разных обработчиков в один и тот же объект может вызвать конфликты.
Чтобы избежать конфликта, задайте один из двух параметров в аргументе запроса options
:
only_if_version
– механизм оптимистичных блокировок, основанный на версиях объектов. Запрос выполнится, только если данная версия объекта является последней и совпадает с заданной в запросе.repository.put( "Client", {id = "42", first_name = "Ivan", last_name = "Petrov"}, {version = 6, only_if_version = 5})
Запрос в примере выполняет поиск по первичному ключу
id
. Если объект с такимid
найден, он обновляется, только если версия объекта в системе на момент исполнения совпадает со значением в параметреonly_if_version
. После успешного исполнения запроса последняя версия объекта станет равна6
.if_not_exists
– проверка на наличие дубликата объекта перед вставкой. Параметр доступен при вставке новых объектов (repository.put()) или массивов (repository.put_batch()), а также при подсчете количества объектов (repository.count()). Если задано значениеtrue
, система проверяет, существует ли уже такой объект. Если такого объекта еще нет, новый объект добавляется в хранилище.
Примечание
Параметры only_if_version
и if_not_exists
взаимоисключающие.
При использовании параметров вместе в одном запросе система выдаст ошибку.
Справочник по Repository API¶
- repository.find(type_name, filter[, options])¶
Возвращает объекты, соответствующие заданным условиям. Если тип объекта поддерживает версионирование, метод возвращает указанную версию объекта.
- Параметры
type_name (string) – тип объекта
filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа
options (table) –
параметры для управления запросом. Доступные параметры:
first
– количество возвращаемых элементов. Значение по умолчанию: 10;after
– курсор пагинации на первый элемент;all_versions
– поиск по всем версиям объекта, если задано значениеtrue
. Параметр применяется только при включенном версионировании. По умолчанию:false
;version
– версия объекта, которая будет возвращена. Параметр применяется только при включенном версионировании. Если параметр задан, возвращается указанная версия объекта. Если такой версии не существует, возвращается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия. Если вместе с этим параметром задан параметрall_versions
, то обрабатываются все версии меньше или равные заданной;mode
– целевой экземпляр для выполнения запроса. Возможные значения:read
иwrite
. Если заданоwrite
, целью будет мастер;prefer_replica
– целевой экземпляр для выполнения запроса. Возможные значения:true
иfalse
. Если заданоtrue
, то предпочитаемая цель – одна из реплик. Если доступной реплики нет, то целью будет мастер. Опция полезна для ресурсозатратных функций, чтобы избежать замедления работы мастера;balance
– управление балансировкой нагрузки. Возможные значения:true
иfalse
. Если заданоtrue
, добавится балансировка нагрузки – запросы на чтение распределяются по всем узлам набора реплик по кругу. Если при этом параметрprefer_replica
определен какtrue
, предпочтение отдается репликам.
- Результат
таблица объектов, соответствующих заданным условиям
- Тип результата
table
Пример
repository.find( "Client", {{"first_name", "==", "Ivan"}, {"last_name", "==", "Petrov"}})
- repository.get(type_name, pkey[, options])¶
Получает объект по первичному ключу. Если тип объекта поддерживает версионирование, метод возвращает указанную версию объекта.
- Параметры
type_name (string) – тип объекта
pkey (any) – первичный ключ
options (table) –
параметры для управления запросом. Доступные параметры:
version
– версия объекта, которая будет получена. Параметр применяется только при включенном версионировании. Если параметр задан, возвращается указанная версия объекта. Если такой версии не существует, возвращается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия;mode
– целевой экземпляр для выполнения запроса. Возможные значения:read
иwrite
. Если заданоwrite
, целью будет мастер;prefer_replica
– целевой экземпляр для выполнения запроса. По умолчанию:false
. Если заданоtrue
, то предпочитаемая цель – одна из реплик. Если доступной реплики нет, то целью будет мастер. Опция полезна для ресурсозатратных функций, чтобы избежать замедления работы мастера;balance
– управление балансировкой нагрузки. По умолчанию:false
. Если заданоtrue
, добавится балансировка нагрузки – запросы на чтение распределяются по всем узлам набора реплик по кругу. Если при этом параметрprefer_replica
определен какtrue
, предпочтение отдается репликам.
- Результат
объект
- Тип результата
table
Пример
repository.get("Client", 42)
- repository.put(type_name, object[, options])¶
Вставляет новый или заменяет существующий объект. Поддерживает оптимистичные блокировки. Если тип объекта поддерживает версионирование, метод вставляет новую версию объекта или заменяет существующую.
- Параметры
type_name (string) – тип объекта
object (table) – объект для вставки
options (table) –
параметры для управления запросом. Доступные параметры:
version
– версия объекта, которая будет добавлена или заменена. Параметр применяется только при включенном версионировании. Если параметр задан, заменяется указанная версия объекта. Если такой версии не существует, заменяется ближайшая предшествующая версия. Объект при этом сохраняется с той же версией. Если параметр не задан, запрос получает последнюю версию объекта и вставляет новую версию объекта. Значение по умолчанию: целое монотонно возрастающее число;only_if_version
– проверка имеющейся версии перед вставкой. Параметр применяется только при включенном версионировании. При указанном параметре запрос добавляет или заменяет объект, только если последняя версия объекта совпадает с указанной;if_not_exists
– проверка имеющегося объекта перед вставкой. По умолчанию:false
. Если задано значениеtrue
, система проверяет, существует ли уже такой объект в хранилище. Новый объект будет добавлен, если его еще нет в хранилище;skip_result
– при значенииtrue
возвращает пустой массив, а не сами измененные объекты. По умолчанию:false
.
- Результат
измененный объект
- Тип результата
table
Пример
Запрос добавляет объект с первичным ключом
id
:repository.put("Client", {id = "42", first_name = "Ivan", last_name = "Petrov"})
Если версионирование отключено:
новый объект добавляется в хранилище;
объект c уже существующим
id
заменяет собой старый такой объект.
Если версионирование включено:
новый объект добавляется в хранилище,
version
равно последней версии;для объекта c уже существующим
id
добавляется новая версия объекта.
- repository.put_batch(type_name, array[, options])¶
Вставляет массив из новых объектов или заменяет существующие. Поддерживает оптимистичные блокировки. Если тип объекта поддерживает версионирование, метод вставляет новую версию объекта или заменяет существующую.
- Параметры
type_name (string) – тип объекта
array (table) – массив объектов для вставки
options (table) –
параметры для управления запросом. Доступные параметры:
version
– версия объекта, которая будет добавлена или заменена. Параметр применяется только при включенном версионировании. Если параметр задан, заменяется указанная версия объекта. Если такой версии не существует, заменяется ближайшая предшествующая версия. Объект при этом сохраняется с той же версией. Если параметр не задан, запрос получает последнюю версию объекта и вставляет новую версию объекта. Значение по умолчанию: целое монотонно возрастающее число;only_if_version
– проверка имеющейся версии перед вставкой. Параметр применяется только при включенном версионировании. При указанном параметре запрос добавляет или заменяет объект, только если последняя версия объекта совпадает с указанной;if_not_exists
– проверка имеющегося массива объектов перед вставкой. По умолчанию:false
. Если задано значениеtrue
, система проверяет, существуют ли уже такие объекты в хранилище. Новые объекты будет добавлены, если их еще нет в хранилище;skip_result
– при значенииtrue
возвращает пустой массив, а не сами измененные объекты. По умолчанию:false
.
- Результат
таблица с измененными объектами
- Тип результата
table
Пример
Запрос вставляет массив объектов:
array = {} batch_count = 1000 for i = 1, batch_count do array[i] = {id = tostring(i), old_field = tostring(i)} end repository.put_batch("Client", array)
Если версионирование отключено:
новые объекты добавляются в хранилище;
объекты c уже существующими
id
заменяют собой старые такие объекты.
Если версионирование включено:
новые объекты добавляются в хранилище,
version
равно последней версии;для объектов c уже существующими
id
добавляются новые версии объектов.
- repository.update(type_name, filter, updaters[, options])¶
Обновляет объекты, соответствующие заданным условиям. Запрос выполняется в две стадии:
исполнение запроса на каждом хранилище, которое может содержать объекты по условию в аргументе
filter
;сбор результатов на роутере.
Если тип объекта поддерживает версионирование, метод сохраняет новую версию объекта или обновляет существующую.
- Параметры
type_name (string) – тип объекта
filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа
updaters (table) –
список обновлений для объекта, состоящий из списка мутаторов
{{mutator, path, new_value}, ...}
, где:mutator
– имя мутатора, например:set
– устанавливает значение;add
– увеличивает значение на указанное число;sub
– уменьшает значение на указанное число;
path
– строковый путь до поля объекта с точкой-разделителем (.
). Путь до объекта(ов) массива должен включать индекс массива или символ*
для захвата всех вложенных объектов;new_value
– новое значение;
options (table) –
параметры для управления запросом. Доступные параметры:
first_n_on_storage
– количество возвращаемых элементов;after
– курсор пагинации на первый элемент;version
– версия объекта, которая будет изменена. Параметр применяется только при включенном версионировании. Если параметр задан, обновляется указанная версия объекта. Если такой версии не существует, обновляется ближайшая предшествующая версия. Объект обновляется, и результат сохраняется с той же версией. Если параметр не задан, запрос получает последнюю версию объекта и сохраняет новую версию объекта. Значение по умолчанию: целое монотонно возрастающее число;only_if_version
– проверка имеющейся версии перед обновлением. Параметр применяется только при включенном версионировании. При указанном параметре объект обновляется, только если последняя версия объекта совпадает с указанной;indexed_by
– индекс, по которому выполняется поиск. Используется, если необходимо явным образом указать индекс;skip_result
– при значенииtrue
возвращает пустой массив, а не сами обновленные объекты. По умолчанию:false
.
- Результат
таблица с обновленными объектами
- Тип результата
table
Примеры
Запрос обновляет имя клиента с
id = 42
:repository.update( "Client", {{"id", "==", 42}}, {{"set", "first_name", "Ivan"}, {"set", "last_name", "Petrov"}})
Если у клиента истек срок действия первого паспорта и необходимо обновить соответствующее поле
expired_flag
, можно использовать следующий запрос:repository.update( "Client", {{"id", "==", 42}}, {{"set", "passports.1.expired_flag", "true"}})
где
.1.
– индекс массива, содержащего экземпляры сущностиPassport
объектаClient
, то есть первый паспорт клиента.
- repository.update_batch(type_name, updates_list[, options])¶
Обновляет объекты, соответствующие заданным условиям. Вызывает несколько обновлений в одном запросе. Если тип объекта поддерживает версионирование, метод сохраняет новую версию объекта или обновляет существующую.
- Параметры
type_name (string) – тип объекта
updates_list (table) –
список обновлений, которые необходимо применить. Для каждого обновления в списке задаются вложенные элементы:
таблица, содержащая список условий-предикатов для выбора (фильтрации) объектов указанного типа;
список мутаторов
{{mutator, path, new_value}, ...}
(список обновлений для объекта), где:mutator
– имя мутатора, например:set
– устанавливает значение;add
– увеличивает значение на указанное число;sub
– уменьшает значение на указанное число;
path
– строковый путь до поля объекта с точкой-разделителем (.
). Путь до объекта(ов) массива должен включать индекс массива или символ*
для захвата всех вложенных объектов;new_value
– новое значение;
options (table) –
параметры для управления запросом. Доступные параметры:
first_n_on_storage
– количество возвращаемых элементов;after
– курсор пагинации на первый элемент;version
– версия объекта, которая будет изменена. Параметр применяется только при включенном версионировании. Если параметр задан, обновляется указанная версия объекта. Если такой версии не существует, обновляется ближайшая предшествующая версия. Объект обновляется, и результат сохраняется с той же версией. Если параметр не задан, запрос получает последнюю версию объекта и сохраняет новую версию объекта. Значение по умолчанию: целое монотонно возрастающее число;only_if_version
– проверка имеющейся версии перед обновлением. Параметр применяется только при включенном версионировании. При указанном параметре объект обновляется, только если последняя версия объекта совпадает с указанной;indexed_by
– индекс, по которому выполняется поиск. Используется, если необходимо явным образом указать индекс;skip_result
– при значенииtrue
возвращает пустой массив, а не сами обновленные объекты. По умолчанию:false
.
- Результат
таблица с обновленными объектами
- Тип результата
table
Пример
Запрос обновляет имена клиентов с
id = 40
иid = 41
:repository.update_batch( "Client", { { {{"id", "==", 40}}, {{"set", "first_name", "Maria"}, {"set", "last_name", "Ivanova"}}, }, { {{"id", "==", 41}}, {{"set", "first_name", "Anna"}, {"set", "last_name", "Ivanova"}} } })
- repository.delete(type_name, filter[, options])¶
Удаляет объекты, соответствующие заданным условиям. Поддерживает оптимистичные блокировки. Если тип объекта поддерживает версионирование, метод удаляет указанную версию объекта.
- Параметры
type_name (string) – тип объекта
filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа
options (table) –
параметры для управления запросом. Доступные параметры:
first_n_on_storage
– количество возвращаемых элементов;after
– курсор пагинации на первый элемент;version
– версия объекта для удаления. Параметр применяется только при включенном версионировании. Если параметр задан, удаляется указанная версия объекта. Если такой версии не существует, удаляется ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия;only_if_version
– проверка имеющейся версии перед удалением. Параметр применяется только при включенном версионировании. При указанном параметре объект удаляется, только если последняя версия объекта совпадает с указанной;indexed_by
– индекс, по которому выполняется поиск. Используется, если необходимо явным образом указать индекс;skip_result
– при значенииtrue
возвращает пустой массив, а не сами удаленные объекты. По умолчанию:false
.
- Результат
таблица с удаленными объектами
- Тип результата
table
Пример
Запрос удаляет клиентов с заданной фамилией:
repository.delete( "Client", {{"last_name", "==", "Petrov"}})
В результате запроса все объекты, удовлетворяющие условию, дополняются новой версией (используется значение по умолчанию).
- repository.count(type_name, filter[, options])¶
Вычисляет количество объектов, соответствующих заданным условиям. Если тип объекта поддерживает версионирование, метод обрабатывает указанную версию объекта.
- Параметры
type_name (string) – тип объекта
filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа
options (table) –
параметры для управления запросом. Доступные параметры:
first
– количество элементов. Значение по умолчанию: 10;after
– курсор пагинации на первый элемент;version
– версия объекта. Параметр применяется только при включенном версионировании. Если параметр задан, обрабатывается указанная версия объекта. Если такой версии не существует, обрабатывается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия. Если вместе с этим параметром задан параметрall_versions
, то обрабатываются все версии меньше или равные заданной;all_versions
– поиск по всем версиям объекта, если задано значениеtrue
. Параметр применяется только при включенном версионировании. По умолчанию:false
;only_if_version
– проверка имеющейся версии перед обработкой. Параметр применяется только при включенном версионировании. При указанном параметре объект обрабатывается, только если последняя версия объекта совпадает с указанной;if_not_exists
– проверка имеющегося объекта перед обработкой. По умолчанию:false
. Если задано значениеtrue
, система проверяет, существует ли уже такой объект в хранилище;indexed_by
– индекс, по которому выполняется поиск. Используется, если необходимо явным образом указать индекс;skip_result
– при значенииtrue
возвращает пустой массив, а не сами обновленные объекты. По умолчанию:false
.
- Результат
количество объектов, соответствующих фильтру
- Тип результата
number
- repository.pairs(type_name, filter[, options])¶
Создает итератор. Используется для чтения большого объема данных. Сигнатура функции аналогична repository.find(), но в
pairs()
нет параметраfirst
, пагинация применяется автоматически. Если тип объекта поддерживает версионирование, метод обрабатывает указанную версию объекта.- Параметры
type_name (string) – тип объекта
filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа
options (table) –
параметры для управления запросом. Доступные параметры:
after
– курсор пагинации на первый элемент;version
– версия объекта. Параметр применяется только при включенном версионировании. Если параметр задан, обрабатывается указанная версия объекта. Если такой версии не существует, обрабатывается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия. Если вместе с этим параметром задан параметрall_versions
, то обрабатываются все версии меньше или равные заданной;all_versions
– поиск по всем версиям объекта, если задано значениеtrue
. Параметр применяется только при включенном версионировании. По умолчанию:false
;mode
– целевой экземпляр для выполнения запроса. Возможные значения:read
иwrite
. Если заданоwrite
, целью будет мастер;prefer_replica
– целевой экземпляр для выполнения запроса. По умолчанию:false
. Если заданоtrue
, то предпочитаемая цель – одна из реплик. Если доступной реплики нет, то целью будет мастер. Опция полезна для ресурсозатратных функций, чтобы избежать замедления работы мастера;balance
– управление балансировкой нагрузки. По умолчанию:false
. Если заданоtrue
, добавится балансировка нагрузки – запросы на чтение распределяются по всем узлам набора реплик по кругу. Если при этом параметрprefer_replica
определен какtrue
, предпочтение отдается репликам;timeout
– время ожидания выполнения запроса, секунды. Значение не должно быть больше, чем значение параметра конфигурации vshard_timeout.
- Результат
итератор
Пример
В примере таблица заполняется результатами вызова
repository.pairs()
и затем печатается:local res = {} for _, object in repository.pairs("Client",{{"first_name", "==", "Ivan"}}) do table.insert(res, object) end print(res)
- repository.call_on_storage(type_name, index_name, value, func_name[, func_args, options])¶
Вызывает функцию на экземпляре с ролью
storage
. Файл с функцией должен храниться в директорииsrc
в корневой директории TDG.- Параметры
type_name (string) – тип объекта
index_name (string) – имя индекса
value (any) – значение ключа поиска
func_name (string) – имя вызываемой функции
func_args (table) – аргументы, которые передаются в вызываемую функцию
options (table) –
параметры для управления запросом. Доступные параметры:
timeout
– время ожидания выполнения запроса, секунды. Значение не должно быть больше, чем значение параметра конфигурации vshard_timeout;mode
– целевой экземпляр для выполнения запроса. Возможные значения:read
иwrite
. Если заданоwrite
, целью будет мастер;prefer_replica
– целевой экземпляр для выполнения запроса. По умолчанию:false
. Если заданоtrue
, то предпочитаемая цель – одна из реплик. Если доступной реплики нет, то целью будет мастер. Опция полезна для ресурсозатратных функций, чтобы избежать замедления работы мастера;balance
– управление балансировкой нагрузки. По умолчанию:false
. Если заданоtrue
, добавится балансировка нагрузки – запросы на чтение распределяются по всем узлам набора реплик по кругу. Если при этом параметрprefer_replica
определен какtrue
, предпочтение отдается репликам.
- Результат
результат выполнения функции
- Тип результата
any
Пример
Запрос вызывает функцию
on_storage.call
для объекта сid = 42
, в функцию переданы аргументы2
и4
:repository.call_on_storage('Data', 'id', '42', 'on_storage.call', {2, 4}, { timeout = 0.1 })
- repository.call_on_storage_batch(type_name, arguments_list[, options])¶
Группирует и вызывает несколько функций на экземплярах с ролью
storage
. Файлы с функциями должны храниться в директорииsrc
в корневой директории TDG.- Параметры
type_name (string) – тип объекта
arguments_list (table) –
список (map) c парами
key-value
, гдеkey
– ключ с идентификатором вызова, аvalue
– таблица из следующих элементов:имя индекса;
значение индекса;
имя вызываемой функции;
таблица с аргументами, которые передаются в вызываемую функцию.
options (table) –
параметры для управления запросом. Доступные параметры:
timeout
– время ожидания выполнения запроса, секунды. Значение не должно быть больше, чем значение параметра конфигурации vshard_timeout;mode
– целевой экземпляр для выполнения запроса. Возможные значения:read
иwrite
. Если заданоwrite
, целью будет мастер;prefer_replica
– целевой экземпляр для выполнения запроса. По умолчанию:false
. Если заданоtrue
, то предпочитаемая цель – одна из реплик. Если доступной реплики нет, то целью будет мастер. Опция полезна для ресурсозатратных функций, чтобы избежать замедления работы мастера;balance
– управление балансировкой нагрузки. По умолчанию:false
. Если заданоtrue
, добавится балансировка нагрузки – запросы на чтение распределяются по всем узлам набора реплик по кругу. Если при этом параметрprefer_replica
определен какtrue
, предпочтение отдается репликам.
- Результат
результаты выполнения функций
- Тип результата
table
Пример
Запрос вызывает функцию
on_storage.call
для объектов сid
от 1 до 3, в функцию переданы аргументыfn_arg1
иfn_arg2
:repository.call_on_storage_batch( 'Data', { {on_storage1 = {'id', '1', 'on_storage.call', {'fn_arg1', 'fn_arg2'}}}, {on_storage2 = {'id', '2', 'on_storage.call', {'fn_arg1', 'fn_arg2'}}}, {on_storage3 = {'id', '3', 'on_storage.call', {'fn_arg1', 'fn_arg2'}}} })
- repository.push_job(name, args)¶
Асинхронный запуск задач и функций.
- Параметры
name (string) – имя функции, определенное в файле конфигурации
args (table) – аргументы функции
- Результат
true
при успешном запуске задачи- Тип результата
boolean
- repository.map_reduce(type_name, filter, map_fn_name, combine_fn_name, reduce_fn_name, options)¶
Запрос на обработку всех данных кластером по модели
MapReduce
. Выполняется на всех экземплярах типаstorage
. Состоит из трех этапов:Map
– выполняется на экземплярах с рольюstorage
;Combine
– выполняется на экземплярах с рольюstorage
;Reduce
— выполняется на экземпляре, где была вызвана функцияmap_reduce
.
Если тип объекта поддерживает версионирование, метод обрабатывает указанную версию объекта.
- Параметры
type_name (string) – тип объекта
filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа
map_fn_name (string) – указатель на функцию для этапа Map
combine_fn_name (string) – указатель на функцию для этапа Combine
reduce_fn_name (string) – указатель на функцию для этапа Reduce
options (table) –
параметры для управления запросом. Доступные параметры:
map_args
– дополнительные аргументы для этапа Map;combine_args
– дополнительные аргументы для этапа Combine;combine_initial_state
– исходное состояние для этапа Combine;reduce_args
– дополнительные аргументы для этапа Reduce;reduce_initial_state
— исходное состояние для этапа Reduce;version
– версия объекта, которая будет обработана. Параметр применяется только при включенном версионировании. Если параметр задан, обрабатывается указанная версия объекта. Если такой версии не существует, обрабатывается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия;mode
– целевой экземпляр для выполнения запроса. Возможные значения:read
иwrite
. Если заданоwrite
, целью будет мастер;prefer_replica
– целевой экземпляр для выполнения запроса. По умолчанию:false
. Если заданоtrue
, то предпочитаемая цель – одна из реплик. Если доступной реплики нет, то целью будет мастер. Опция полезна для ресурсозатратных функций, чтобы избежать замедления работы мастера;balance
– управление балансировкой нагрузки. По умолчанию:false
. Если заданоtrue
, добавится балансировка нагрузки – запросы на чтение распределяются по всем узлам набора реплик по кругу. Если при этом параметрprefer_replica
определен какtrue
, предпочтение отдается репликам;timeout
– время ожидания выполнения запроса, секунды. Значение не должно быть больше, чем значение параметра конфигурации vshard_timeout.
- Результат
результат выполнения
reduce_fn_name
- Тип результата
any
Этап Map
На каждом экземпляре c ролью
storage
вызывается функцияmap_fn_name
. Функция вызывается столько раз, сколько на этом экземпляре будет найдено объектов, соответствующих типуtype_name
и условиямfilter
. Функцияmap_fn_name
применяется к каждому найденному кортежу.local map_res, err = map_fn(tuple, options.map_args)
Функция может вернуть любые данные или
nil
. Если возвращены данные, на следующем этапе они будут использованы для запуска функцииcombine_fn_name
.combine_fn_name
будет вызвана столько раз, сколько раз вызовыMap
вернут данные.Этап Combine (опционально)
Нужен для уменьшения количества данных, полученных на стадии Map, перед их передачей по сети и дальнейшей обработкой. Результат каждого вызова
map_fn_name
передаётся вcombine_fn_name
. Далее каждый вызовcombine_fn_name
осуществляется с передачей исходного состояния, равного результату предыдущего вызоваcombine_fn_name
. Для первого вызова исходное состояние равноcombine_initial_state
, либо равно пустой таблице, если этот параметр не задан.local combine_res = options.combine_initial_state or {} local combine_res, err = combine_fn_name(combine_res, map_res, options.combine_args)
Функция
combine_fn
также выполняется на ролиstorage
.Результат выполнения
combine_fn
накапливается в переменнойcombine_res
и передается на ту роль, откуда был вызванmap_reduce
– в функциюreduce_fn_name
.Этап Reduce
Этап предназначен для завершения обработки данных со всего кластера. Данные передаются по сети на экземпляр, на котором была вызвана функция
map_reduce
. Там вызывается функцияreduce_fn_name
. Функция будет вызвана столько раз, сколько экземпляров типаstorage
в кластере найдут подходящие объекты и, соответственно, вернут результат вcombine_res
. Результатreduce_fn_name
возвращается как результат всегоmap_reduce
.local reduce_res, err = reduce_fn_name(combine_res, options.reduce_initial_state, options.reduce_args)