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

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

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

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

credentials:
  users:
    replicator:
      password: 'secret'
      roles:
        - replication
        - dictionary_api_service

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

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

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

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

   credentials:
     users:
       sampleuser:
         password: '123456'
         roles: [ dictionary_api_executor ]
         privileges:
         - permissions: [ read, write ]
           spaces: [ dictionary_data ]
   

В частности, такие права на чтение и запись необходимы для импорта и экспорта данных через утилиту 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,value
categories,1,Food
categories,2,House
categories,3,Transport
categories,4,Clothes
categories,5,Shoes
categories,6,Gifts
categories,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,fingerprint
categories,1,Food,bbbbbbbb-0000-0000-0000-000000000001,1710759004038591461,36d105b8b513422c33677dd59d0be27e
categories,2,House,bbbbbbbb-0000-0000-0000-000000000001,1710759004039152609,6fb4851069662836519d660a7a59ed09
categories,3,Transport,bbbbbbbb-0000-0000-0000-000000000001,1710759004039490086,dc6c35589f567f7683dfda8567949b5b
categories,4,Clothes,bbbbbbbb-0000-0000-0000-000000000001,1710759004039879589,c69658a6989824a428a2b01df21c2721
categories,5,Shoes,bbbbbbbb-0000-0000-0000-000000000001,1710759004040017977,c149a6d5b1667c05c3853ee9f873b361
categories,6,Gifts,bbbbbbbb-0000-0000-0000-000000000001,1710759004040344064,3b722413b54c323207e5f787cb5dc63c
categories,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,fingerprint
categories,1,Food,bbbbbbbb-0000-0000-0000-000000000001,1710759004038591461,36d105b8b513422c33677dd59d0be27e
categories,2,House,bbbbbbbb-0000-0000-0000-000000000001,1710759004039152609,6fb4851069662836519d660a7a59ed09
categories,3,Transport,bbbbbbbb-0000-0000-0000-000000000001,1710759004039490086,dc6c35589f567f7683dfda8567949b5b
categories,4,Clothes,bbbbbbbb-0000-0000-0000-000000000001,1710759004039879589,c69658a6989824a428a2b01df21c2721
categories,5,Shoes,bbbbbbbb-0000-0000-0000-000000000001,1710759004040017977,c149a6d5b1667c05c3853ee9f873b361
categories,6,Gifts,bbbbbbbb-0000-0000-0000-000000000001,1710759004040344064,3b722413b54c323207e5f787cb5dc63c
categories,7,Travel,bbbbbbbb-0000-0000-0000-000000000001,1710759004040469779,135a471b56847a908ef5d0d1ff4c1244