space_object:format()
-
object
space_object
¶ -
space_object:
format
([format-clause])¶ Объявление имен и типов полей.
Параметры: - space_object (
space_object
) – ссылка на объект - format-clause (
table
) – список имен и типов полей
возвращает: nil
, если не указан оператор форматаВозможные ошибки:
space_object
does not exist- field names are duplicated
- type is not legal
Примечание
Если вам нужно выполнить миграцию схемы, обратитесь к разделу Миграции.
Как правило, Tarantool допускает поля без имен и без указания типа. Но с помощью
format
можно, например, задокументировать, что N-ное поле представляет собой поле для фамилии и должно содержать строковое значение. Также оператор формата можно указать в box.schema.space.create().Оператор формата для каждого поля содержит определение в фигурных скобках:
{name='...',type='...'[,is_nullable=...]}
, где:- The
name
value may be any string, provided that two fields do not have the same name. - The
type
value may be any of allowed types: any | unsigned | string | integer | number | varbinary | boolean | double | decimal | uuid | array | map | scalar, but for creating an index use only indexed fields; - (Optional) The
is_nullable
boolean value specifies whethernil
can be used as a field value. See also: key_part.is_nullable. - (Optional) The
collation
string value specifies the collation used to compare field values. See also: key_part.collation. - (Optional) The
constraint
table specifies the constraints that the field value must satisfy. - (Optional) The
foreign_key
table specifies the foreign keys for the field. - (Optional) The
default
value specifies the explicit default value for the field or the argument of the default function ifdefault_func
is specified. - (Optional) The
default_func
string value specifies the name of the field’s default function. To pass the default function’s argument, add thedefault
parameter.
В кортежах недопустимы значения неправильного типа. Пример ниже вызовет ошибку:
--Этот пример вызовет ошибку. box.space.tester:format({{' ',type='number'}}) box.space.tester:insert{'string-which-is-not-a-number'}
В кортежах недопустимы нулевые значения, если
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
может вызвать перестроение и привести к ошибке, если уже есть кортежи с нулевыми значениями.Пример:
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'}}) -- типы 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}] ...
Имена, указанные с помощью оператора формата, можно использовать в space_object:get(), в space_object:create_index(), в tuple_object[field-name] и в 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.
Note regarding storage engine: vinyl supports formatting of non-empty spaces. Primary index definition cannot be formatted.
- space_object (
-