space_object:format()
-
object
space_object
-
space_object:
format
([format-clause]) Объявление имен и типов полей.
Параметры: - space_object (space_object) – ссылка на объект
- format-clause (table) – список имен и типов полей
возвращает: nil, если не указан оператор формата
Возможные ошибки:
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
может бытьtrue
илиfalse
(такое же требование, как для «Параметров для space_object:create_index»). См. также предупреждение в разделе Разрешение использования нулевых значений для индексируемого ключа.
В кортежах недопустимы значения неправильного типа; например, после
box.space.tester:format({{' ',type='number'}})
(тип = число) запросbox.space.tester:insert{'строка-которая-не-является-числом'}
вызовет ошибку.В кортежах недопустимы нулевые значения, если
is_nullable=false
, что задано по умолчанию; например, послеbox.space.tester:format({{' ',type='number',is_nullable=false}})
запросbox.space.tester:insert{nil,2}
вызовет ошибку.It is legal for tuples to have more fields than are described by a format clause. The way to constrain the number of fields is to specify a space’s field_count member.
В кортежах может быть меньше полей, чем описано в операторе формата, если пропущенные завершающие поля описаны с помощью
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
может вызвать перестроение и привести к ошибке, если уже есть кортежи с нулевыми значениями.Пример:
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({{'x'}}) box.space.tester:format({{'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({{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}] ...
Names specified with the format clause can be used in space_object:get() and in space_object:create_index() and in tuple_object[field-name] and in tuple_object[field-path].
Если оператор формата не указан, то вернется таблица, которая использовалась при предыдущем вызове
объект-спейса:format(оператор-формата)
. Например, послеbox.space.tester:format({{'x','scalar'}})
,box.space.tester:format()
вернет[{'name': 'x', 'type': 'scalar'}]
.Formatting or reformatting a large space will cause occasional yields so that other requests will not be blocked. If the other requests cause an illegal situation such as a field value of the wrong type, the formatting or reformatting will fail.
Примечание про движок базы данных: vinyl поддерживает форматирование не пустых спейсов. Определение первичного индекса форматировать нельзя.
-