Модуль dictionary

Модуль dictionary предоставляет методы для работы со словарями и используется на узлах с включенной технологической ролью roles.dictionary-router или roles.dictionary-storage.

Каждый метод в списке ниже может быть вызван как с роутера, так и с хранилища. При вызове с роутера вызов перенаправляется на один из доступных узлов с ролью roles.dictionary-storage. При вызове с хранилища метод выполняется сразу.

Разрешения на запуск методов собраны в пользовательскую роль dictionary_api_executor.

Вызвать метод в новом формате через утилиту tt CLI или в веб-интерфейсе TCM во вкладке Terminal (TT Connect) можно через box.schema.func.call, например:

 
box.schema.func.call('dictionary_router_set', 'categories', '1', 'Shops')

Вызвать метод в старом формате можно напрямую, например:

 
dictionary_router.set('categories', '1', 'Shops')

• dictionary_get(entity_name, key)
• dictionary_set(entity_name, key, value[, opt])
• dictionary_del(entity_name, key[, opt])
• dictionary_get_keys(entity_name[, opt])
• dictionary_get_entity(entity_name[, opt])
• dictionary_get_batch(entity_name, key_list)
• dictionary_set_batch(entity_name, key_value)
• dictionary_del_entity(entity_name)
• dictionary_check_consistency()
• dictionary_check_key_consistency()
• dictionary_wait_key_consistency(entity_name, key)
• dictionary_notify_neighbors()
• dictionary_try_sync()

 
local value = dictionary_router_get(entity_name, key) — вызов на роутереlocal value = dictionary_get(entity_name, key) — вызов на хранилище

Получить значение элемента с одного из доступных узлов со словарем.

Параметры:

• entity_name (string) — название словаря. Если названия нет, укажите пустую строку;
• key (string) — идентификатор элемента словаря.

Возвращает:

• value (any) — данные элемента словаря по идентификатору, или nil, если данных с таким идентификатором нет.

 
local ok, error_message = dictionary_router_set(entity_name, key, value, opt) — вызов на роутереlocal ok, error_message = dictionary_set(entity_name, key, value, opt) — вызов на хранилище

Сохранить значение элемента в один из доступных узлов со словарем.

Параметры:

• entity_name (string) — название словаря. Если названия нет, укажите пустую строку;
• key (string) — идентификатор элемента словаря;
• value (any) — данные элемента словаря;
• opt (table) — дополнительные параметры вызова:
  • wait_consistency (boolean) — ждать окончания репликации по всем узлам. Все узлы при этом должны быть рабочими (healthy). Запрещено использовать внутри транзакции. Опция гарантирует, что при следующем чтении с любого узла будут получены актуальные данные;
  • wait_consistency_timeout (number) — максимальное время ожидания репликации по всем узлам в секундах. Значение по умолчанию: 3 секунды.

Возвращает:

• ok (boolean) — true, если операция выполнена успешно;
• error_message (string) — информация об ошибке, если она произошла, иначе nil.

 
local ok, error_message = dictionary_router_del(entity_name, key, opt) — вызов на роутереlocal ok, error_message = dictionary_del(entity_name, key, opt) — вызов на хранилище

Удалить значение элемента в одном из доступных узлов со словарем.

Параметры:

• entity_name (string) — название словаря. Если названия нет, укажите пустую строку;
• key (string) — идентификатор удаляемого элемента словаря;
• opt (table) — дополнительные параметры вызова:
  • wait_consistency (boolean) — ждать окончания репликации по всем узлам. Все узлы при этом должны быть рабочими (healthy). Запрещено использовать внутри транзакции. Опция гарантирует, что при следующем чтении с любого узла будут получены актуальные данные;
  • wait_consistency_timeout (number) — максимальное время ожидания репликации по всем узлам в секундах. Значение по умолчанию: 3 секунды.

Возвращает:

• ok (boolean) — true, если операция выполнена успешно;
• error_message (string) — информация об ошибке, если она произошла, иначе nil.

 
local key_list = dictionary_router_get_keys(entity_name, opt) — вызов на роутереlocal key_list = dictionary_get_keys(entity_name, opt) — вызов на хранилище

Получить все ключи для словаря.

Параметры:

• entity_name (string) — название словаря;
• opt (table) — дополнительные параметры вызова:
  • limit (number) — максимальное число ключей в ответе. Значение по умолчанию: 5000;
  • yield (number) — количество ключей до следующей передачи управления. Значение по умолчанию: 1000.

Возвращает:

• key_list (table) — список ключей.

 
local data = dictionary_router_get_entity(entity_name, opt) — вызов на роутереlocal data = dictionary_get_entity(entity_name, opt) — вызов на хранилище

Получить все данные словаря.

Параметры:

• entity_name (string) — название словаря;
• opt (table) — дополнительные параметры вызова:
  • limit (number) — максимальное число ключей в ответе. Значение по умолчанию: 1000;
  • yield (number) — количество ключей до следующей передачи управления. Значение по умолчанию: 1000.

Возвращает:

• key_value (table) — ассоциативный массив ключ-значение;
• qty (number) — число прочитанных строк.

 
local key_value = dictionary_router_get_batch(entity_name, key) — вызов на роутереlocal key_value = dictionary_get_batch(entity_name, key) — вызов на хранилище

Получить значения словаря по списку ключей.

Параметры:

• entity_name (string) — название словаря;
• key (table) — список ключей.

Возвращает:

• key_value (table) — ассоциативный массив ключ-значение.

 
local res = dictionary_router_set_batch(entity_name, key_value) — вызов на роутереlocal res = dictionary_set_batch(entity_name, key_value) — вызов на хранилище

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

Параметры:

• entity_name (string) — название словаря;
• key_value (table) — ассоциативный массив ключ-значение.

Возвращает:

• res (boolean) — true, если операция выполнена успешно.

 
local res = dictionary_router_del_entity(entity_name) — вызов на роутереlocal res = dictionary_del_entity(entity_name) — вызов на хранилище

Удалить все значения словаря.

Параметры:

• entity_name (string) — название словаря.

Возвращает:

• res (boolean) — true, если операция выполнена успешно.

 
local res, error_message = dictionary_router_check_consistency() — вызов на роутереlocal res, error_message = dictionary_check_consistency() — вызов на хранилище

Для каждого узла со словарем вычислить хэш всех его данных. При вычислении учитываются поля:

• название словаря (entity_name);
• ключ (key);
• значение (value).

Для успешного выполнения все узлы со словарями должны быть рабочими (healthy).

Параметры: нет

Возвращает:

• result (table) — структура, содержащая поля:
  • consistency (boolean) — true, если на всех узлах одинаковый хэш данных словаря;
  • hash_map (table) — справочная таблица, которая содержит перечень узлов со словарями и их хэши данных;
• error_message (string) — информация об ошибке, если она произошла, иначе nil.

 
local res, error_message = dictionary_router_check_key_consistency(entity_name, key) — вызов на роутереlocal res, error_message = dictionary_check_key_consistency(entity_name, key) — вызов на хранилище

Для каждого узла со словарем вычислить хэш одного ключа. При вычислении учитываются поля:

• название словаря (entity_name);
• ключ (key);
• значение (value).

Для успешного выполнения все узлы со словарями должны быть рабочими (healthy).

Параметры:

• entity_name (string) — название словаря;
• key (string) — идентификатор элемента словаря.

Возвращает:

• result (table) — структура, содержащая поля:
  • consistency (bool) — true, если на всех узлах одинаковый хэш данных словаря;
  • hash_map (table) — справочная таблица, содержащая перечень узлов со словарями с хэшем выбранного ключа;
• error_message (string) — информация об ошибке, если она произошла, иначе nil.

 
local res, error_message = dictionary_router_wait_key_consistency(entity_name, key) — вызов на роутереlocal res, error_message = dictionary_wait_key_consistency(entity_name, key) — вызов на хранилище

Ждать наступления момента, когда данные по ключу на всех узлах со словарями станут одинаковыми. Для успешного выполнения все узлы со словарями должны быть рабочими (healthy).

Параметры:

• entity_name (string) — название словаря;
• key (string) — идентификатор элемента словаря;
• timeout (number) — время ожидания в секундах. Значение по умолчанию: 3.

Возвращает:

• error_message (string) — информация об ошибке, если она произошла, иначе nil.

 
dictionary_router_notify_neighbors() — вызов на роутереdictionary_notify_neighbors() — вызов на хранилище

Выполнить асинхронную попытку оповестить ближайший доступный экземпляр о новых данных.

Параметры: нет

Возвращает: нет

 
local ok, error_message = dictionary_router_try_sync() — вызов на роутереlocal ok, error_message = dictionary_try_sync() — вызов на хранилище

Запустить принудительно обмен данными с соседними экземплярами. При таком обмене данных экземпляр:

• запрашивает новые данные с других экземпляров;
• оповещает соседние экземпляры о своих новых данных.

При работе со словарями попытка обмена данными с другими узлами происходит в двух случаях:

• при выполнении операции сохранения (set) или удаления (del) не в транзакции;
• по таймеру, периодичность которого регулируется опцией конфигурации dictionary.worker_sleep_in_second.

Если операции set или del выполняются в транзакции, библиотека не начинает синхронизацию с другими узлами. В этом случае в логике клиентской функции можно принудительно вызвать обмен данными после окончания транзакции, чтобы не дожидаться срабатывания таймера.

Параметры: нет

Возвращает:

• ok (boolean) – true, если операция выполнена успешно;
• error_message (string) – информация об ошибке, если она произошла, иначе nil.