space_object:create_index()

Описание типов индексируемых полей

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

Использование null в ключе индекса

box.space.tester:create_index('I', {unique = true, parts = {{field = 2, type = 'number', is_nullable = true}}})

Создание индекса с использованием имен полей вместо номеров полей

create_index() может использовать имена полей и / или номера полей, которые описаны в необязательном операторе space_object:format().

В следующем примере мы покажем использование format() для спейса с двумя столбцами „x“ и „y“, а затем — пять вариантов использования оператора parts={} в create_index() сначала для столбца „x“, затем для столбцов „x“ и „y“. Эти варианты включают в себя пропуск типа, использование чисел и дополнительных скобок.

box.space.tester:format({{name = 'x', type = 'scalar'}, {name = 'y', type = 'integer'}})

box.space.tester:create_index('I2', {parts = {{'x', 'scalar'}}})
box.space.tester:create_index('I3', {parts = {{'x', 'scalar'}, {'y', 'integer'}}})

box.space.tester:create_index('I4', {parts = {{1, 'scalar'}}})
box.space.tester:create_index('I5', {parts = {{1, 'scalar'}, {2, 'integer'}}})

box.space.tester:create_index('I6', {parts = {1}})
box.space.tester:create_index('I7', {parts = {1, 2}})

box.space.tester:create_index('I8', {parts = {'x'}})
box.space.tester:create_index('I9', {parts = {'x', 'y'}})

box.space.tester:create_index('I10', {parts = {{'x'}}})
box.space.tester:create_index('I11', {parts = {{'x'}, {'y'}}})

Создание индекса с использованием пути для полей с ассоциативными массивами (индексы по пути JSON)

Чтобы создать индекс для поля, которое представляет собой ассоциативный массив (строка с путем и скалярное значение), укажите строку c путем во время создания индекса:

parts = {field-number, 'data-type', path = 'path-name'}

Тип индекса должен быть TREE или HASH, а содержимое поля — всегда ассоциативный массив с одним и тем же путем.

Пример 1 — Простое использование пути:

tarantool> box.schema.space.create('T')
tarantool> box.space.T:create_index('I',{parts = {{field = 1, type = 'scalar', path = 'age'}}})
tarantool> box.space.T:insert({{age = 44}})
tarantool> box.space.T:select(44)
---
- [{'age': 44}]

Пример 2 — для большей наглядности используем path вместе с format() и JSON-синтаксисом:

tarantool> my_space = box.schema.space.create('T')
tarantool> format = {{'id', 'unsigned'}, {'data', 'map'}}
tarantool> my_space:format(format)
tarantool> parts = {{'data.FIO["firstname"]', 'str'}, {'data.FIO["surname"]', 'str'}}
tarantool> my_index = my_space:create_index('info', {parts = parts})
tarantool> my_space:insert({1, {FIO = {firstname = 'Ahmed', surname = 'Xi'}}})
---
- [1, {'FIO': {'surname': 'Xi', 'firstname': 'Ahmed'}}]

Note regarding storage engine: vinyl supports only the TREE index type, and vinyl secondary indexes must be created before tuples are inserted.

Создание индекса по массивам (multikey) с использованием опции path с символом [*]

Строка в параметре пути может содержать символ [*], который называется заменителем индекса массива. Описанные так индексы используются для JSON-документов, у которых одинаковая структура.

Например, при создании индекса по полю №2 для документа со строками, который будет начинаться с {'data': [{'name': '...'}, {'name': '...'}], раздел parts в запросе на создание индекса будет выглядеть так:

parts = {{field = 2, type = 'str', path = 'data[*].name'}}

Тогда кортежи с именами можно быстро получить с помощью index_object:select({key-value}).

На самом деле в одном поле может быть несколько ключей, как в примере ниже, который выводит один и тот же кортеж дважды, потому что оба ключа „A“ и „B“ соответствуют запросу:

my_space = box.schema.space.create('json_documents')
my_space:create_index('primary')
multikey_index = my_space:create_index('multikey', {parts = {{field = 2, type = 'str', path = 'data[*].name'}}})
my_space:insert({1,
         {data = {{name = 'A'},
                  {name = 'B'}},
          extra_field = 1}})
multikey_index:select({''}, {iterator = 'GE'})

Результат выборки будет выглядеть так:

tarantool> multikey_index:select({''},{iterator='GE'})
---
- - [1, {'data': [{'name': 'A'}, {'name': 'B'}], 'extra_field': 1}]
- [1, {'data': [{'name': 'A'}, {'name': 'B'}], 'extra_field': 1}]
...

Есть некоторые ограничения:

• символ [*] должен стоять отдельно или в конце имени в пути.
• символ [*] не должен повторяться в пути.
• Если в индексе есть путь с x[*], то в никаком другом индексе не может быть пути с x.компонентом,
• [*] нельзя указывать в пути первичного ключа.
• Если индекс должен быть уникальным (unique=true) и в нем есть путь с символом [*], то запрещается использовать дублирующиеся ключи в разных кортежах, но в в одном кортеже можно использовать дублирующиеся ключи.
• Структура значения поля должна соответствовать стуктуре, заданной в определении пути, или значение поля должно быть nil (nil не индексируется)
• В спейсе с индексами по массивам можно хранить не более ~8000 элементов, проиндексированных таким образом.

Создание функционального индекса

Функциональные индексы — это индексы, которые вызывают пользовательскую функцию для формирования ключа индекса, в отличие от других типов индексов, где ключ формирует сам Tarantool. Функциональные индексы используют для сжатия, усечения или реверсирования или любого другого изменения индекса по желанию пользователя.

Ниже приведены рекомендации по созданию функциональных индексов:

• Функция должна принимать кортеж с содержимым полей на момент запроса на изменение данных и возвращать кортеж с содержимым, которое будет фактически помещено в индекс.
• Описание create_index должно включать в себя определение всех частей ключа, а пользовательская функция должна возвращать таблицу, которая содержит то же количество частей ключа с теми же типами.
• Спейс должен быть на движке memtx.
• Функция должна быть персистентной и детерминированной (см. Создание функции с телом).
• Части ключа не должны зависеть от JSON-путей.
• Функция должна получать доступ к значениям частей ключа по индексу, а не по имени поля.
• Функциональные индексы не должны быть по первичному ключу.
• Нельзя изменить ни функциональные индексы, ни функцию, если она используется для индекса, то есть единственный способ изменить их — это удалить индекс и создать его заново.
• Только функции, запущенные из песочницы, могут использоваться в функциональных индексах.

Пример:

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

1. Создайте спейс. В спейсе должно быть поле с первичным ключом, которое не будет полем для функционального индекса:

   box.schema.space.create('tester', {engine = 'memtx'})
   box.space.tester:create_index('i',{parts={{field = 1, type = 'string'}}})
   

2. Создайте функцию. Функция принимает кортеж. В этом примере она работает на кортеже tuple[2], поскольку источник ключа — поле номер 2, в которое мы вставляем данные. Используйте string.sub() из модуля string, чтобы получить первый символ:

   lua_code = [[function(tuple) return {string.sub(tuple[2],1,1)} end]]
   

3. Сделайте функцию персистентной с помощью box.schema.create:

   box.schema.func.create('my_func',
       {body = lua_code, is_deterministic = true, is_sandboxed = true})
   

4. Создайте функциональный индекс. Укажите поля, значения которых будут передаваться в функцию. Укажите функцию:

   box.space.tester:create_index('func_idx',{parts={{field = 1, type = 'string'}},func = 'my_func'})
   

5. Проверьте, как это работает. Вставьте несколько кортежей. Сделайте выборку, используя только первую букву, — сработает, потому что это и есть ключ. Или выберите, используя ту же функцию, что была использована для вставки:

   box.space.tester:insert({'a', 'wombat'})
   box.space.tester:insert({'b', 'rabbit'})
   box.space.tester.index.func_idx:select('w')
   box.space.tester.index.func_idx:select(box.func.my_func:call({{'tester', 'wombat'}}));
   

   Результаты двух запросов select будут выглядеть так:

   tarantool> box.space.tester.index.func_idx:select('w')
   ---
   - - ['a', 'wombat']
   ...
   tarantool> box.space.tester.index.func_idx:select(box.func.my_func:call({{'tester','wombat'}}));
   ---
   - - ['a', 'wombat']
   ...
   

Вот пример кода полностью:

box.schema.space.create('tester', {engine = 'memtx'})
box.space.tester:create_index('i',{parts={{field = 1, type = 'string'}}})
lua_code = [[function(tuple) return {string.sub(tuple[2],1,1)} end]]
box.schema.func.create('my_func',
    {body = lua_code, is_deterministic = true, is_sandboxed = true})
box.space.tester:create_index('func_idx',{parts={{field = 1, type = 'string'}},func = 'my_func'})
box.space.tester:insert({'a', 'wombat'})
box.space.tester:insert({'b', 'rabbit'})
box.space.tester.index.func_idx:select('w')
box.space.tester.index.func_idx:select(box.func.my_func:call({{'tester', 'wombat'}}));

Функции для функциональных индексов могут возвращать множество ключей. Такие функции называют «мультиключевыми» (multikey).

To create a multikey function, the options of box.schema.func.create() must include is_multikey = true. The return value must be a table of tuples. If a multikey function returns N tuples, then N keys will be added to the index.

Пример:

s = box.schema.space.create('withdata')
s:format({{name = 'name', type = 'string'},
          {name = 'address', type = 'string'}})
pk = s:create_index('name', {parts = {{field = 1, type = 'string'}}})
lua_code = [[function(tuple)
               local address = string.split(tuple[2])
               local ret = {}
               for _, v in pairs(address) do
                 table.insert(ret, {utf8.upper(v)})
               end
               return ret
             end]]
box.schema.func.create('address',
                        {body = lua_code,
                         is_deterministic = true,
                         is_sandboxed = true,
                         is_multikey = true})
idx = s:create_index('addr', {unique = false,
                              func = 'address',
                              parts = {{field = 1, type = 'string',
                                      collation = 'unicode_ci'}}})
s:insert({"James", "SIS Building Lambeth London UK"})
s:insert({"Sherlock", "221B Baker St Marylebone London NW1 6XE UK"})
idx:select('Uk')
-- Both tuples will be returned.