Module key_def
The key_def module has a function for making a definition of the field numbers and types of a tuple. The definition is usually used in conjunction with an index definition to extract or compare the index key values.
-
key_def.
new
(parts) Create a new key_def instance.
Parameters: - parts (table) – field numbers and types. There must be at least one part and it must have at least fieldno and type.
Returns: key_def-object a key_def object
The parts table has components which are the same as the
parts
option in Options for space_object:create_index().fieldno (integer) for example fieldno = 1. It is legal to say field instead of fieldno.
type (string) for example type = ‘string’.
Other components are optional.
Example:
key_def.new({{type = 'unsigned', fieldno = 1}})
Example:
key_def.new({{type = 'string', collation = 'unicode', field = 2}})
-
object
key_def_object
A key_def object is an object returned by key_def.new(). It has methods extract_key(), compare(), compare_with_key(), merge(), totable().
-
key_def_object:
extract_key
(tuple) Return a tuple containing only the fields of the key_def object.
Parameters: - tuple (table) – tuple or Lua table with field contents
Return: the fields that were defined for the key_def object
Example #1:
-- Suppose that an item has five fields -- 1, 99.5, 'X', nil, 99.5 -- and the fields that we care about are -- #3 (a string) and #1 (an integer). -- We can define those fields with k = key_def.new -- and extract the values with k:extract_key. tarantool> key_def = require('key_def') --- ... tarantool> k = key_def.new({{type = 'string', fieldno = 3}, > {type = 'unsigned', fieldno =1 }}) --- ... tarantool> k:extract_key({1, 99.5, 'X', nil, 99.5}) --- - ['X', 1] ...
Example #2
-- Now suppose that the item is a tuple in a space which -- has an index on field #3 plus field #1. -- We can use key_def.new with the index definition -- instead of filling it out as we did with Example #1. -- The result will be the same. key_def = require('key_def') box.schema.space.create('T') i = box.space.T:create_index('I',{parts={3,'string',1,'unsigned'}}) box.space.T:insert{1, 99.5, 'X', nil, 99.5} k = key_def.new(i.parts) k:extract_key(box.space.T:get({'X', 1}))
Example #3
-- Iterate through the tuples in a secondary non-unique index. -- extracting the tuples' primary-key values so they can be deleted -- using a unique index. This code should be part of a Lua function. local key_def_lib = require('key_def') local s = box.schema.space.create('test') local pk = s:create_index('pk') local sk = s:create_index('test', {unique = false, parts = { {2, 'number', path = 'a'}, {2, 'number', path = 'b'}}}) s:insert{1, {a = 1, b = 1}} s:insert{2, {a = 1, b = 2}} local key_def = key_def_lib.new(pk.parts) for _, tuple in sk:pairs({1})) do local key = key_def:extract_key(tuple) pk:delete(key) end
-
key_def_object:
compare
(tuple_1, tuple_2) Compare the key fields of tuple_1 to the key fields of tuple_2. This is a tuple-by-tuple comparison so users do not have to write code which compares a field at a time. Each field’s type and collation will be taken into account. In effect it is a comparison of extract_key(tuple_1) with extract_key(tuple_2).
Parameters: Return: > 0 if tuple_1 key fields > tuple_2 key fields, = 0 if tuple_1 key fields = tuple_2 key fields, < 0 if tuple_1 key fields < tuple_2 key fields
Example:
-- This will return 0 key_def = require('key_def') k = key_def.new({{type='string',fieldno=3,collation='unicode_ci'}, {type='unsigned',fieldno=1}}) k:compare({1, 99.5, 'X', nil, 99.5}, {1, 99.5, 'x', nil, 99.5})
-
key_def_object:
compare_with_key
(tuple_1, tuple_2) Compare the key fields of tuple_1 to all the fields of tuple_2. This is the same as key_def_object:compare() except that tuple_2 contains only the key fields. In effect it is a comparison of extract_key(tuple_1) with tuple_2.
Parameters: Return: > 0 if tuple_1 key fields > tuple_2 fields, = 0 if tuple_1 key fields = tuple_2 fields, < 0 if tuple_1 key fields < tuple_2 fields
Example:
-- This will return 0 key_def = require('key_def') k = key_def.new({{type='string',fieldno=3,collation='unicode_ci'}, {type='unsigned',fieldno=1}}) k:compare_with_key({1, 99.5, 'X', nil, 99.5}, {'x', 1})
-
key_def_object:
merge
(other_key_def_object) Combine the main key_def_object with other_key_def_object. The return value is a new key_def_object containing all the fields of the main key_def_object, then all the fields of other_key_def_object which are not in the main key_def_object.
Parameters: - other_key_def_object (key_def_object) – definition of fields to add
Return: key_def_object
Example:
-- This will return a key definition with fieldno=3 and fieldno=1. key_def = require('key_def') k = key_def.new({{type = 'string', fieldno = 3}}) k2= key_def.new({{type = 'unsigned', fieldno = 1}, {type = 'string', fieldno = 3}}) k:merge(k2)
-
key_def_object:
totable
() Return a table containing what is in the key_def_object. This is the reverse of
key_def.new()
:key_def.new()
takes a table and returns a key_def object,key_def_object:totable()
takes a key_def object and returns a table.
This is useful for input to
_serialize
methods.Return: table Example:
-- This will return a table with type='string', fieldno=3 key_def = require('key_def') k = key_def.new({{type = 'string', fieldno = 3}}) k:totable()
-