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. Every part must have the attributes type and fieldno/field. Other attributes are optional.
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 use 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:	tuple1 (table) – tuple or Lua table with field contents tuple2 (table) – tuple or Lua table with field contents
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:	tuple1 (table) – tuple or Lua table with field contents tuple2 (table) – tuple or Lua table with field contents
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()