format

Задайте имена полей и типы.

Параметры:

• space_object (space_object) — ссылка на объект
• format-clause (table) — список имен и типов полей

Возвращает

nil, если только оператор format-clause не опущен

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

• space_object не существует
• дублируются имена полей
• недопустимый тип

Обычно Tarantool допускает неименованные и нетипизированные поля. Но с помощью format можно, например, задокументировать, что N-е поле является полем фамилии и должно содержать строки. Также формат-условие можно указать в box.schema.space.create().

Формат-условие содержит для каждого поля определение в фигурных скобках: {name='...',type='...'[,is_nullable=...]}, где:

• Значение name может быть любой строкой при условии, что два поля не имеют одинакового имени.
• Значение type может быть любым из допустимых типов: any | unsigned | string | integer | number | varbinary | boolean | double | decimal | uuid | array | map | scalar, но для создания индекса используйте только индексируемые поля;
• (Необязательно) Логическое значение is_nullable определяет, может ли nil использоваться в качестве значения поля. См. также: key_part.is_nullable.
• (Необязательно) Строковое значение collation задает правило сортировки, используемое для сравнения значений полей. См. также: key_part.collation.
• (Необязательно) Таблица constraint задает ограничения, которым должно соответствовать значение поля.
• (Необязательно) Таблица foreign_key задает внешние ключи для поля.
• (Необязательно) Значение default задает явное значение по умолчанию для поля или аргумент функции по умолчанию, если указан default_func.
• (Необязательно) Строковое значение default_func задает имя функции по умолчанию для поля. Чтобы передать аргумент функции по умолчанию, добавьте параметр default.

Кортежи не могут содержать значения недопустимого типа. Пример ниже вызовет ошибку:

 
--Этот пример вызовет ошибку.box.space.tester:format({{' ',type='number'}})box.space.tester:insert{'string-which-is-not-a-number'}

Кортежи не могут содержать значения nil, если is_nullable=false (значение по умолчанию). Пример ниже вызовет ошибку:

 
--Этот пример вызовет ошибку.box.space.tester:format({{' ',type='number',is_nullable=false}})box.space.tester:insert{nil,2}

Кортежи могут содержать больше полей, чем описано в формат-условии. Чтобы ограничить количество полей, укажите параметр спейса field_count.

Кортежи могут содержать меньше полей, чем описано в формат-условии, если пропущенные завершающие поля описаны с is_nullable=true. Например, запрос ниже не вызовет ошибку, связанную с форматом:

 
box.space.tester:format({{'a',type='number'},{'b',type='number',is_nullable=true}})box.space.tester:insert{2}

Допустимо применять format к спейсу, у которого уже есть формат — это заменит предыдущие определения при условии отсутствия конфликтов с существующими данными или определениями индексов.

Допустимо использовать format для изменения флага is_nullable. Пример ниже не вызовет ошибку и не приведет к перестроению спейса.

 
box.space.tester:format({{' ',type='scalar',is_nullable=false}})box.space.tester:format({{' ',type='scalar',is_nullable=true}})

Но обратное изменение is_nullable с true на false может привести к перестроению спейса и вызвать ошибку, если в существующих кортежах есть значения nil.

Пример:

 
box.space.tester:format({{name='surname',type='string'},{name='IDX',type='array'}})box.space.tester:format({{name='surname',type='string',is_nullable=true}})

Существуют допустимые варианты формат-условия:

• без указания 'name=' и 'type=',
• без указания только 'type=',
• с дополнительными фигурными скобками.

В следующем примере иллюстрируются все варианты: первый — для поля с именем 'x', второй — для двух полей с именами 'x' и 'y'.

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

В следующем примере показано, как создать спейс, отформатировать его всеми возможными типами и вставить в него данные.

 
tarantool> box.schema.space.create('t')---- engine: memtx  before_replace: 'function: 0x4019c488'  on_replace: 'function: 0x4019c460'  ck_constraint:   field_count: 0  temporary: false  index:   is_local: false  enabled: false  name: t  id: 534- created...tarantool> ffi = require('ffi')---...tarantool> decimal = require('decimal')---...tarantool> uuid = require('uuid')---...tarantool> box.space.t:format({{name = '1', type = 'any'},         >                     {name = '2', type = 'unsigned'},         >                     {name = '3', type = 'string'},         >                     {name = '4', type = 'number'},         >                     {name = '5', type = 'double'},         >                     {name = '6', type = 'integer'},         >                     {name = '7', type = 'boolean'},         >                     {name = '8', type = 'decimal'},         >                     {name = '9', type = 'uuid'},         >                     {name = 'a', type = 'scalar'},         >                     {name = 'b', type = 'array'},         >                     {name = 'c', type = 'map'}})---...tarantool> box.space.t:create_index('i',{parts={2, type = 'unsigned'}})---- unique: true  parts:  - type: unsigned    is_nullable: false    fieldno: 2  id: 0  space_id: 534  type: TREE  name: i...tarantool> box.space.t:insert{{'a'}, -- any         >                    1, -- unsigned         >                    'W?', -- string         >                    5.5, -- number         >                    ffi.cast('double', 1), -- double         >                    -0, -- integer         >                    true, -- boolean         >                    decimal.new(1.2), -- decimal         >                    uuid.new(), -- uuid         >                    true, -- scalar         >                    {{'a'}}, -- array         >                    {val=1}} -- map---- [['a'], 1, 'W?', 5.5, 1, 0, true, 1.2, 1f41e7b8-3191-483d-b46e-1aa6a4b14557, true, [['a']], {'val': 1}]...

Имена, заданные с помощью формат-условия, можно использовать в /reference/reference_lua/box_space/get и в /reference/reference_lua/box_space/create_index и в /reference/reference_lua/box_tuple/field_name и в /reference/reference_lua/box_tuple/field_path.

Если формат-условие опущено, возвращаемым значением будет таблица, использованная в предыдущем вызове {space_object}:format({format-clause}). Например, после box.space.tester:format({{'x','scalar'}}), вызов box.space.tester:format() вернет [{'name': 'x', 'type': 'scalar'}].

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

Примечание относительно движка хранения: vinyl поддерживает форматирование непустых спейсов. Определение первичного индекса не подлежит форматированию.