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 - оператор сравнения: ">", ">=", "==", "<=", "<", LIKE, ILIKE.

  Начиная с версии 2.19.0, для метода repository.find() также поддерживаются операторы ниже:

  • != - исключает записи, в которых значение поля совпадает с заданным шаблоном;
  • !=CI - исключает записи, в которых значение поля совпадает с заданным шаблоном без учета регистра. Оператор принимает на вход только строку.

  Оба оператора являются фильтрами post-scan и могут применяться к обычным полям и составным индексам.

• right - правая часть выражения. Содержит один из двух вариантов:

  • полный путь к полю объекта (Customer.first_name);
  • строковое значение, численное значение, булево значение или таблица.

Если в предикате несколько условий, по умолчанию они объединяются логической операцией and (конъюнкцией).

Примеры предикатов:

 
{{"id", ">", 10}}{{"id", ">", 10}, {"id", "<", 100}}{{'Customer.first_name', '!=CI', 'ivan'}}{{"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, система проверяет, существует ли уже такой объект. Если такого объекта еще нет, новый объект добавляется в хранилище.

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

Параметры:

• type_name (string) — тип объекта

• filter (table) — список условий-предикатов для выбора (фильтрации) объектов указанного типа. Начиная с версии 2.19.0, для метода repository.find() также поддерживаются операторы ниже:

  • != - исключает записи, в которых значение поля совпадает с заданным шаблоном;
  • !=CI - исключает записи, в которых значение поля совпадает с заданным шаблоном без учета регистра. Оператор принимает на вход только строку.

  Оба оператора являются фильтрами post-scan и могут применяться к обычным полям и составным индексам.

• 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, предпочтение отдается репликам;
  • fields - список запрашиваемых полей. Доступно с версии 2.11.3. По умолчанию возвращаются все поля объекта.

Возвращает

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

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

table

Пример

 
repository.find(  "Client",  {{"first_name", "==", "Ivan"},  {"last_name", "==", "Petrov"}})

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

Параметры:

• type_name (string) — тип объекта

• pkey (any) — первичный ключ

• options (table) — параметры для управления запросом. Доступные параметры:

  • version - версия объекта, которая будет получена. Параметр применяется только при включенном версионировании. Если параметр задан, возвращается указанная версия объекта. Если такой версии не существует, возвращается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия;
  • mode - целевой экземпляр для выполнения запроса. Возможные значения: read и write. Если задано write, целью будет мастер;
  • prefer_replica - целевой экземпляр для выполнения запроса. По умолчанию: false. Если задано true, то предпочитаемая цель - одна из реплик. Если доступной реплики нет, то целью будет мастер. Опция полезна для ресурсозатратных функций, чтобы избежать замедления работы мастера;
  • balance - управление балансировкой нагрузки. По умолчанию: false. Если задано true, добавится балансировка нагрузки - запросы на чтение распределяются по всем узлам набора реплик по кругу. Если при этом параметр prefer_replica определен как true, предпочтение отдается репликам;
  • fields - список запрашиваемых полей. Доступно с версии 2.18.0. По умолчанию возвращаются все поля объекта.

Возвращает

объект

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

table

Пример

 
repository.get("Client", 42)

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

Параметры:

• 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 добавляется новая версия объекта.

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

Параметры:

• type_name (string) — тип объекта

• array (table) — массив объектов для вставки

• options (table) — параметры для управления запросом. Доступные параметры:

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

Возвращает

таблица с измененными объектами

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

table

Пример

Запрос вставляет массив объектов:

 
array = {}batch_count = 1000for i = 1, batch_count do  array[i] = {id = tostring(i), old_field = tostring(i)}endrepository.put_batch("Client", array)

Если версионирование отключено:

• новые объекты добавляются в хранилище;
• объекты c уже существующими id заменяют собой старые такие объекты.

Если версионирование включено:

• новые объекты добавляются в хранилище, version равно последней версии;
• для объектов c уже существующими id добавляются новые версии объектов.

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

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

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

Параметры:

• 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"}}  } })

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

Параметры:

• 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"}})

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

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

Параметры:

• 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.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)endprint(res)

Вызывает функцию на экземпляре с ролью 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 })

Группирует и вызывает несколько функций на экземплярах с ролью 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'}}}  })

Асинхронный запуск задач и функций.

Параметры:

• name (string) — имя функции, определенное в файле конфигурации

• args (table) — аргументы функции

Возвращает

true при успешном запуске задачи

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

boolean

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)