space_object:create_index()

object space_object

space_object:create_index(index-name[, options])

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

тип возвращаемого значения:
Параметры:	space_object (space_object) – ссылка на объект index_name (string) – имя индекса, которое должно соответствовать правилам именования объектов options (table) – см. «Параметры для space_object:create_index()» ниже
возвращает:	объект индекса
	index_object

Параметры для space_object:create_index()

Имя	Описание	Тип	Значение по умолчанию
type	тип индекса	string („HASH“, или „TREE“, или „BITSET“, или „RTREE“) Примечание про движок базы данных: vinyl поддерживает только „TREE“	„TREE“
id	уникальный идентификатор	number	идентификатор последнего индекса +1
unique	индекс уникален	boolean	`true`
if_not_exists	ошибки нет, если имя дублируется	boolean	`false`
parts	номера поля + типы	{field_no, „unsigned“ или „string“, или „integer“, или „number“, или „boolean“, или „array“, или „scalar“, возможна сортировка, возможно значение is_nullable}	`{1, 'unsigned'}`
dimension	только для RTREE	number	2
distance	только для RTREE	строка („euclid“, то есть Евклидова метрика; или „manhattan“, то есть расстояние городских кварталов)	„euclid“
bloom_fpr	только для vinyl	number	`vinyl_bloom_fpr`
page_size	только для vinyl	number	`vinyl_page_size`
range_size	только для vinyl	number	`vinyl_range_size`
run_count_per_level	только для vinyl	number	`vinyl_run_count_per_level`
run_size_ratio	только для vinyl	number	`vinyl_run_size_ratio`
sequence	см. раздел об указании последовательности для create_index()	строка или число	отсутствует

Параметры из вышеприведенной таблицы также могут использоваться в index_object:alter().

Примечание про движок базы данных: в vinyl’е есть дополнительные параметры, которые по умолчанию основаны на конфигурационных параметрах vinyl_bloom_fpr, vinyl_page_size, vinyl_range_size, vinyl_run_count_per_level и vinyl_run_size_ratio – см. описание этих параметров. Текущие значения можно увидеть, сделав выборку из box.space._index.

Возможные ошибки:

слишком много частей;
индекс „…“ уже существует;
первичный ключ должен быть уникальным.

tarantool> s = box.space.tester
---
...
tarantool> s:create_index('primary', {unique = true, parts = { {field = 1, type = 'unsigned'}, {field = 2, type = 'string'}} })
---
...

Подробнее о типах полей индекса:

unsigned: беззнаковые целые числа от 0 до 18 446 744 073 709 551 615, т.е. около18 квинтиллионов. Также может называться „uint“ или „num“, но „num“ объявлен устаревшим. Используется в индексах типа TREE или HASH в memtx’е, и в TREE-индексах в vinyl’е.
string: строка, то есть любая последовательность октетов до максимальной длины. Также может называться „str“. Используется в индексах типа TREE, HASH или BITSET в memtx’е и в TREE-индексах в vinyl’е. В строке может быть сортировка.
integer: целые числа от -9 223 372 036 854 775 808 до 18 446 744 073 709 551 615. Также может называться „int“. Используется в индексах типа TREE или HASH в memtx’е и в TREE-индексах в vinyl’е.
number: целые числа от -9 223 372 036 854 775 808 до 18 446 744 073 709 551 615, числа с плавающей запятой с одинарной точностью или с двойной точностью. Используется в индексах типа TREE или HASH в memtx’е и в TREE-индексах в vinyl’е.
boolean: логическое значение, true (правда) или false (ложь). Используется в индексах типа TREE или HASH в memtx’е и в TREE-индексах в vinyl’е.
array: массив чисел. Используется в RTREE-индексах в memtx’е.
scalar: логические значения (true или false), целые числа от integers between -9 223 372 036 854 775 808 до 18 446 744 073 709 551 615, числа с плавающей запятой с одинарной точностью или с двойной точностью или строки. При использовании нескольких типов, порядок ключей должен быть следующим: логические значения, затем числа, затем строки. Используется в индексах типа TREE или HASH в memtx’е и в TREE-индексах в vinyl’е.

Кроме того, допускается нулевое значение nil для любого типа поля, если указана такая возможность is_nullable=true.

Типы полей в индексах для использования в space_object:create_index()

Тип поля для индексирования	Чем может быть	Где может использоваться	Примеры
unsigned	целые числа от 0 до 18 446 744 073 709 551 615	индексы типа TREE или HASH в memtx’е, TREE-индексы в vinyl’е	123456
string	строки – любой набор октетов	индексы типа TREE или HASH в memtx’е TREE-индексы в vinyl’е	„A B C“ „\65 \66 \67“
integer	целые числа от -9 223 372 036 854 775 808 до 18 446 744 073 709 551 615	индексы типа TREE или HASH в memtx’е, TREE-индексы в vinyl’е	-2^63
number	целые числа от -9 223 372 036 854 775 808 до 18 446 744 073 709 551 615, числа с плавающей запятой с одинарной точностью или с двойной точностью	индексы типа TREE или HASH в memtx’е, TREE-индексы в vinyl’е	1.234 -44 1.447e+44
boolean	true или false	индексы типа TREE или HASH в memtx’е, TREE-индексы в vinyl’е	false true
array	массив целых чисел от -9 223 372 036 854 775 808 до 9 223 372 036 854 775 807	RTREE-индексы в memtx’е	{10, 11} {3, 5, 9, 10}
scalar	логические значения (true или false), целые числа от -9 223 372 036 854 775 808 до 18 446 744 073 709 551 615, числа с плавающей запятой с одинарной точностью или с двойной точностью, строки	индексы типа TREE или HASH в memtx’е, TREE-индексы в vinyl’е	true -1 1.234 „“ „ру“

Разрешение использования нулевых значений для индексируемого ключа: /Если тип индекса – TREE, и индекс не является первичным, то оператор parts={...} может включать в себя is_nullable=true или is_nullable=false (по умолчанию). Если значение параметра is_nullable – true, то можно вставлять nil или аналогичное значение, например msgpack.NULL (или можно не вставлять вообще ничего в завершающие ненулевые поля). В рамках индекса такие нулевые значения считаются равными другим нулевым значениям и всегда меньше ненулевых значений. Нулевые значения могут встречаться несколько раз даже в уникальном индексе. Например:

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

Предупреждение

Можно создать множество индексов для одного и того же поля с различными значениями is_nullable или вызвать space_object:format() со значением is_nullable, отличным от используемого для индекса. При наличии несоответствий правило такое: запрещается использовать null кроме случаев, когда 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'}}})

Примечание про движок базы данных: vinyl поддерживает только TREE-индексы, и следует создать в vinyl’е вторичные индексы до вставки кортежей.

Версия:

space_object:create_index()