1.3. Программный интерфейс репозитория¶

1.3.5.1. Выборка по полям объектов одного типа (find)¶

Синтаксис

repository.find(type_name, filter, options, context)

где:

• type_name — тип объекта;

• filter — список условий-предикатов для выбора (фильтрации) объектов указанного типа;

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

  • first — количество элементов;

  • after — курсор пагинации на первый элемент;

  • version — версия объекта;

  • all_versions — указатель для поиска по всем версиям объекта, если задано значение true;

  • mode — определяет целевой экземпляр для выполнения запроса. Возможные значения: read и write. Если задано write, целью будет мастер;

  • prefer_replica — определяет целевой экземпляр для выполнения запроса. Возможные значения: true и false. Если задано true, то предпочитаемая цель — одна из реплик. Если доступной реплики нет, то целью будет мастер. Опция полезна для ресурсозатратных функций, чтобы избежать замедления работы мастера;

  • balance — управление балансировкой нагрузки. Возможные значения: true и false. Если задано true, добавится балансировка нагрузки — запросы на чтение распределяются по всем узлам набора реплик по кругу. Если при этом параметр prefer_replica определен как true, предпочтение отдается репликам;

• context — контекст выполнения запроса:

  • tenant — тенант.

Пример

repository.find(
  "Client",
  {{"$id", "==", 42}}
)

1.3.5.2. Выборка по индексу (get)¶

Синтаксис

repository.get(type_name, index_name, value, options, context)

где:

• type_name — тип объекта;

• index_name — имя индекса;

• value — значение ключа поиска;

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

  • first — количество элементов;

  • after — курсор пагинации на первый элемент;

  • version — версия объекта;

  • all_versions — указатель для поиска по всем версиям объекта, если задано значение true;

  • mode — определяет целевой экземпляр для выполнения запроса. Возможные значения: read и write. Если задано write, целью будет мастер;

  • prefer_replica — определяет целевой экземпляр для выполнения запроса. Возможные значения: true и false. Если задано true, то предпочитаемая цель — одна из реплик. Если доступной реплики нет, то целью будет мастер. Опция полезна для ресурсозатратных функций, чтобы избежать замедления работы мастера;

  • balance — управление балансировкой нагрузки. Возможные значения: true и false. Если задано true, добавится балансировка нагрузки — запросы на чтение распределяются по всем узлам набора реплик по кругу. Если при этом параметр prefer_replica определен как true, предпочтение отдается репликам;

• context — контекст выполнения запроса:

  • tenant — тенант.

Пример

repository.get("Client", "id", 42)

1.3.5.3. Запрос на добавление данных (put)¶

Запрос put позволяет вставить новые данные или заменить существующие. Он поддерживает версионирование и оптимистичные блокировки.

Если отсутствует параметр version, то используется значение по умолчанию (большое целое монотонно возрастающее число).

При заданном параметре version запрос выполняет добавление или замену объекта с заданной версией (обычно используется целое число).

При указанном параметре only_if_version запрос добавляет или заменяет объект только в том случае, если последняя версия объекта совпадает с указанной.

Синтаксис

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

repository.put(type_name, object, options, context)

где:

• type_name — тип объекта;

• object — объект для вставки;

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

  • version — версия объекта;

  • only_if_version — проверка имеющейся версии перед вставкой;

• context — контекст выполнения запроса:

  • tenant — тенант.

Пример

repository.put("users", {id = "100500", name = "Kirito777"})

Данный запрос из примера добавит новый объект с первичным ключом id, равным 100500, если таковой ещё не существует. При этом значение параметра version будет равным значению по умолчанию (большое целое монотонно возрастающее число). Если объект с таким первичным ключом уже есть, то будет добавлена новая версия объекта со значением параметра version, равным значению по умолчанию.

1.3.5.4. Запрос на обновление данных (update)¶

Запрос на обновление данных (update) поддерживает версионирование и выполняется в две стадии:

• исполнение запроса на каждом хранилище, которое может содержать объекты по условию, передаваемому аргументом filter;

• сбор результатов на роутере.

Синтаксис

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

repository.update(type_name, filter, updaters, options, context)

где:

• type_name — тип объекта;

• filter — список условий-предикатов для выбора (фильтрации) объектов указанного типа;

• updaters — список обновлений для объекта, состоящий из списка мутаторов {{mutator, path, new_value}, ...}, где:

  • mutator — имя мутатора, например:

    • set — устанавливает значение;

    • add — увеличивает значение на указанное число;

    • sub — уменьшает значение на указанное число;

  • path — строковый путь до поля объекта с точкой-разделителем (.).

    Путь до объекта(ов) массива должен включать индекс массива или символ * для захвата всех подобъектов;

  • new_value` — новое значение;

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

  • first — количество элементов для обновления;

  • after — курсор пагинации на первый элемент;

  • version — версия объекта;

  • only_if_version — проверка имеющейся версии перед вставкой;

  • dont_skip_deleted — использовать в поиске удаленные версии объектов;

• context — контекст выполнения запроса:

  • tenant — тенант.

Примеры

Для модели, рассмотренной в примере:

• Чтобы обновить имя клиента с идентификатором 42, используйте следующий запрос:

  repository.update(
   "Client",
   {{"$id", "==", 42}},
   {{"set", "first_name", "John"},
    {"set", "last_name", "Doe"}})
  

• Если у того же клиента истек срок действия первого паспорта и необходимо обновить соответствующее поле expired_flag, используйте следующий запрос:

  repository.update(
   "Client",
   {{"$id", "==", 42}},
   {{"set", "passports.1.expired_flag", "true"}}
  

  где .1. — индекс массива, содержащего экземпляры сущности Passport агрегата Client, т.е. первый паспорт клиента.

1.3.5.5. Запрос на удаление объектов (delete)¶

Чтобы прозрачно и удобно исключить объект из потенциальных результатов запросов, используйте запрос на удаление (delete). Он помещает объект или его версию в «удаленное состояние» (добавляя флаг delete:true), что исключает его из выборки.

Запрос на удаление поддерживает версионирование и оптимистичные блокировки.

Синтаксис

Чтобы удалить объект, используйте следующий запрос:

repository.delete(type_name, filter, options, context)

где:

• type_name — имя типа объекта для удаления;

• filter — список условий-предикатов для выбора (фильтрации) объектов указанного типа;

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

  • first — количество элементов для удаления;

  • after — курсор пагинации на первый элемент;

  • version — версия объекта для копирования в удаленное состояние;

  • only_if_version — проверка имеющейся версии перед вставкой;

  • all-versions — этот флаг для функции удаления (delete) нельзя использовать без флага permanent_delete;

  • permanent_delete — при установленном флаге (значение True) происходит физическое удаление информации об объекте из TDG. Используется вместе с флагом all-versions;

• context — контекст выполнения запроса:

  • tenant — тенант.

Пример

Чтобы удалить клиентов с именем «QWERTY» для модели из примера, используйте следующий запрос:

repository.delete(
 "Client",
 {{"$first_name", "==", "QWERTY"}})

В результате такого запроса все объекты, удовлетворяющие условию (first name равное QWERTY), будут дополнены новой версией (значение версии по умолчанию) с флагом delete:true.

1.3.5.6. Вызов функции на экземпляре с ролью storage (call_on_storage)¶

Синтаксис

repository.call_on_storage(type_name, index_name, value, func_name, func_args, options, context)

где:

• type_name — тип объекта;

• index_name — имя индекса;

• value — значение ключа поиска;

• func_name — имя вызываемой функции;

• func_args — аргументы, которые передаются в вызываемую функцию;

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

  • timeout — время ожидания выполнения запроса, секунды. Значение не должно быть больше, чем значение параметра конфигурации vshard_timeout;

  • mode — определяет целевой экземпляр для выполнения запроса. Возможные значения: read и write. Если задано write, целью будет мастер;

  • prefer_replica — определяет целевой экземпляр для выполнения запроса. Возможные значения: true и false. Если задано true, то предпочитаемая цель — одна из реплик. Если доступной реплики нет, то целью будет мастер. Опция полезна для ресурсозатратных функций, чтобы избежать замедления работы мастера;

  • balance — управление балансировкой нагрузки. Возможные значения: true и false. Если задано true, добавится балансировка нагрузки — запросы на чтение распределяются по всем узлам набора реплик по кругу. Если при этом параметр prefer_replica определен как true, предпочтение отдается репликам;

• context — контекст выполнения запроса:

  • tenant — тенант.

1.3.5.7. Асинхронный запуск задач/функций (push_job)¶

Синтаксис

repository.push_job(name, arguments, options, context)

где:

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

• arguments — аргументы функции;

• options — параметры для управления запросом (не используется);

• context — контекст выполнения запроса (не используется).