TDB Documentation portal logo
Помощь
Обновлена 30 июня 2026 г. в 07:00

Начало работы с модулем dictionary

Tarantool DB поддерживает два способа работы со словарями:

  • доступ через API модуля dictionary;
  • прямой доступ к данным словарей через спейс dictionary_data.

В этом разделе описано, как настроить Tarantool DB для каждого из этих способов работы, а также приведено несколько примеров использования словарей.

Содержание:

Управление доступом

Чтобы работать с данными словарей через API модуля dictionary, назначьте пользователю роль dictionary_api_executor. Это можно сделать в файле config.yml, используя опцию credentials.users.<username>.roles. В примере ниже роль dictionary_api_executor задана пользователю dictionary_user:

credentials:  users:    dictionary_user:      password: '123456'      roles: [ dictionary_api_executor ]

Узнать больше об управлении пользователями и ролями можно в документации Tarantool.

Чтобы получить прямой доступ к данным словарей через спейс dictionary_data:

  1. Назначьте пользователю роль dictionary_api_executor.

  2. Выдайте пользователю права на чтение спейса dictionary_data и запись данных в него, используя опцию конфигурации credentials.users.<username>.privileges:

    credentials:  users:    dictionary_user:      password: '123456'      roles: [ dictionary_api_executor ]      privileges:        - permissions: [ read, write ]          spaces: [ dictionary_data, dictionary_vclock ]        - permissions: [ execute ]          universe: true

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

Определение конфигурации словарей

Когда доступ к данным для пользователя настроен, задайте в файле config.yml:

  • технологические роли roles.dictionary-router и roles.dictionary-storage. Их можно включить в секциях groups.routers.roles и groups.storages.roles соответственно (см. опцию roles). Пример:

    groups:routers:  replication:    failover: manual  sharding:    roles: [router]  roles:    - roles.crud-router    - roles.metrics-export    - roles.dictionary-router    - roles.dictionary-storage

    Узнать больше: Включение и настройка ролей.

  • конфигурацию ролей dictionary для роутера и хранилищ. Ее можно задать с помощью опции roles_cfg. Пример:

    roles_cfg:  roles.dictionary-router:    update_instances_list_period: 300  roles.dictionary-storage:    batch_size: 1000    worker_sleep_in_second: 60    update_instances_list_period: 300    connect_timeout: 3

    Узнать больше про настройку конфигурации ролей можно в документации Tarantool в разделе Настройка ролей. Полный список поддерживаемых опций конфигурации dictionary приведен в разделе roles.dictionary-<router_or_storage>.

Работа со словарями через API

Для работы используются методы встроенного модуля dictionary. Полный список поддерживаемых методов приведен в разделе Модуль dictionary. Подробный пример работы со словарями через API приведен в разделе Запись и получение данных в словаре.

В примере ниже в словарь записывается элемент с помощью метода dictionary_set(). Затем записанные данные элемента словаря проверяются с помощью dictionary_get():

if dictionary_set('categories', '1', 'Food') then    local value = dictionary_get('categories', '1')end

В примере ниже работа со словарем выполняется в транзакции:

dictionary_set('categories', '1', {})box.begin()local data = dictionary_get('categories', '1')data.list= 'Food'if dictionary_set('categories', '1', data) then    box.commit()    dictionary_try_sync()else    box.rollback()end

Прямой доступ к данным словарей

Данные словарей хранятся в спейсе dictionary_data. Этот спейс содержит следующие поля:

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

Кроме того, спейс dictionary_data содержит служебные поля, которые автоматически рассчитываются перед записью.

Спейс dictionary_data можно использовать напрямую для записи и чтения данных, все изменения при этом будут переданы на другие узлы. Удаление данных при работе напрямую с dictionary_data не поддерживаются.

В примере в спейс dictionary_data добавляется кортеж, а затем записанные данные словаря проверяются и записываются в переменную value:

box.space.dictionary_data:replace({'categories', '1', 'Food'})local value = box.space.dictionary_data:get({'categories', '1'})

Импорт данных

Данные словарей можно загрузить напрямую в спейс dictionary_data из файла .csv. Для импорта требуются три поля:

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

Пример файла для импорта (import_example.csv):

entity_name,key,valuecategories,1,Foodcategories,2,Housecategories,3,Transportcategories,4,Clothescategories,5,Shoescategories,6,Giftscategories,7,Travel

Загрузить данные из файла можно в любой экземпляр с ролью roles.dictionary-storage, используя команду tt import:

tt import admin:test-cluster-cookie@localhost:3101 import_example.csv:dictionary_data --header

После загрузки данные распространяются по другим узлам за время, примерно равное значению опции dictionary.worker_sleep_in_second.

Команда tt import позволяет явно указать столбцы, которые нужно импортировать. Это полезно в таких случаях:

  • в загружаемом файле больше столбцов, чем нужно для загрузки;
  • нужные столбцы имеют названия, отличные от названий полей (entity_name,key, value). нужные.

Пример файла для импорта (test.csv), для которого потребуется явно указать столбцы:

csv_dict,csv_key,csv_value,writer_uid,dt,fingerprintcategories,1,Food,bbbbbbbb-0000-0000-0000-000000000001,1710759004038591461,36d105b8b513422c33677dd59d0be27ecategories,2,House,bbbbbbbb-0000-0000-0000-000000000001,1710759004039152609,6fb4851069662836519d660a7a59ed09categories,3,Transport,bbbbbbbb-0000-0000-0000-000000000001,1710759004039490086,dc6c35589f567f7683dfda8567949b5bcategories,4,Clothes,bbbbbbbb-0000-0000-0000-000000000001,1710759004039879589,c69658a6989824a428a2b01df21c2721categories,5,Shoes,bbbbbbbb-0000-0000-0000-000000000001,1710759004040017977,c149a6d5b1667c05c3853ee9f873b361categories,6,Gifts,bbbbbbbb-0000-0000-0000-000000000001,1710759004040344064,3b722413b54c323207e5f787cb5dc63ccategories,7,Travel,bbbbbbbb-0000-0000-0000-000000000001,1710759004040469779,135a471b56847a908ef5d0d1ff4c1244

Чтобы загрузить первые три столбца из файла выше (csv_dict,csv_key,csv_value), вызовите команду tt import с опцией --match:

tt import \	admin:test-cluster-cookie@localhost:3101 \	test.csv:dictionary_data \	--header \	--match "entity_name=csv_dict;key=csv_key;value=csv_value"

Экспорт данных

Выгрузить содержимое спейса dictionary_data можно с помощью команды tt export:

tt export admin:test-cluster-cookie@localhost:3101 dictionary_data:out.csv --header

Пример выгруженного файла out.csv:

entity_name,key,value,writer_uid,dt,fingerprintcategories,1,Food,bbbbbbbb-0000-0000-0000-000000000001,1710759004038591461,36d105b8b513422c33677dd59d0be27ecategories,2,House,bbbbbbbb-0000-0000-0000-000000000001,1710759004039152609,6fb4851069662836519d660a7a59ed09categories,3,Transport,bbbbbbbb-0000-0000-0000-000000000001,1710759004039490086,dc6c35589f567f7683dfda8567949b5bcategories,4,Clothes,bbbbbbbb-0000-0000-0000-000000000001,1710759004039879589,c69658a6989824a428a2b01df21c2721categories,5,Shoes,bbbbbbbb-0000-0000-0000-000000000001,1710759004040017977,c149a6d5b1667c05c3853ee9f873b361categories,6,Gifts,bbbbbbbb-0000-0000-0000-000000000001,1710759004040344064,3b722413b54c323207e5f787cb5dc63ccategories,7,Travel,bbbbbbbb-0000-0000-0000-000000000001,1710759004040469779,135a471b56847a908ef5d0d1ff4c1244

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