Module key_def

The key_def module has a function for defining the field numbers and types of a tuple. The definition is usually used 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 contain the attributes `type` and `fieldno`/`field`. Other attributes are optional.
Returns:	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}})

Since version 3.2.0, you can use the standard lua operator # (__len metamethod) to check the key_def length (parts count).

Example

function is_full_pkey(space, key) return #space.index[0].parts == #key end 

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 defined for the `key_def` object

Example #1:

-- Suppose 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 the item is a tuple in a space with -- an index on field #3 plus field #1. -- We can use key_def.new with the index definition -- instead of filling it out (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 could be deleted -- using a unique index. This code should be a 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 with the key fields of tuple_2. It is a tuple-by-tuple comparison so users do not have to write code that compares one 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 with 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:

-- Returns 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:

-- Returns 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()¶

Returns a table containing the fields of 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:

-- Returns a table with type = 'string', fieldno = 3 key_def = require('key_def') k = key_def.new({{type = 'string', fieldno = 3}}) k:totable() 

key_def_object:validate_key(key)¶

Since version 3.1.0

Validates all parts of the specified key match the key definition. Partial keys are considered valid. Returns nothing on success.

If the key fails the validation, a box.error type exception is raised.

Example:

-- Create a rule: key = {1 ('unsigned'), 2 (string)} -- Validate key {1001} (only id data type). Returns nothing -- Validate key {'x'}. ER_KEY_PART_TYPE is raised -- Validate key ({1000, 2000}). ER_KEY_PART_TYPE is raised -- Validate key ({1000, 'abc', 'xyz'}). ER_KEY_PART_COUNT is raised tarantool> key_def = require('key_def').new({{fieldno = 1, type = 'unsigned'}, > {fieldno = 2, type = 'string'}}) --- ... tarantool> key_def:validate_key({1001}) --- ... tarantool> key_def:validate_key({'x'}) --- - error: 'Supplied key type of part 0 does not match index part type: expected unsigned' ... tarantool> key_def:validate_key({1000, 2000}) --- - error: 'Supplied key type of part 1 does not match index part type: expected string' ... tarantool> key_def:validate_key({1000, 'abc', 'xyz'}) --- - error: 'Invalid key part count: (expected [0..2], got 3) ... 

key_def_object:validate_full_key(key)¶

Since version 3.1.0

Validates whether they input key contains all fields and mathces the rules of the key definition object. Returns nothing on success.

If the key fails the validation, a box.error type exception is raised.

Example:

-- Create a rule: key = {1 ('unsigned'), 2 (string)} -- Validate key {100, "Testuser"}. Returns nothing -- Validate key ({100}). ER_EXACT_MATCH is raised tarantool> key_def = require('key_def').new({{fieldno = 1, type = 'unsigned'}, > {fieldno = 2, type = 'string'}}) --- ... tarantool> key_def:validate_full_key({100, "Testuser"}) --- ... tarantool> key_def:validate_full_key({100}) --- - error: 'Invalid key part count in an exact match: (expected 2, got 1) ... 

key_def_object:validate_tuple(tuple)¶

Since version 3.1.0

Validates whether the tuple matches the rules of the key definition object Returns nothing on success.

If the key fails the validation, a box.error type exception is raised.

Example:

-- Create a rule: tuple = {id (number), name (string), age (number)} -- Validate tuple {1001, "Testuser", 28}. Returns nothing tarantool> key_def = require('key_def').new({ > {fieldno = 1, type = 'number'}, > {fieldno = 2, type = 'string'}, > {fieldno = 3, type = 'number'}) --- ... tarantool> key_def:validate_tuple({1001, "Testuser", 28}) --- ... 

key_def_object:compare_keys(key_a, key_b)¶

Since version 3.1.0

Compares two keys against each other and according to the key definition object. On success, returns:

<0 if key_a parts are less than key_b parts
0 if key_a parts are equal to key_b parts
>0 if key_a parts are greater than key_b parts

If any key does not match the key definition rules, a box.error type exception is raised.

Example:

-- Create a rule: key = {1 ('unsigned'), 2 (string)} -- Validate keys ({1000, 'x'}, {1000, 'y'}). Returns -1 -- Validate keys ({1000, 'x'}, {1000, 'x'}). Returns 0 -- Validate keys ({1000, 'x'}, {1000}). Returns 0 -- Validate keys ({2000, 'x'}, {1000, 'x'}). Returns 1 tarantool> key_def = require('key_def').new({{fieldno = 1, type = 'unsigned'}, > {fieldno = 2, type = 'string'}}) --- ... tarantool> key_def:compare_keys({1000, 'x'}, {1000, 'y'}) --- - -1 ... tarantool> key_def:compare_keys({1000, 'x'}, {1000, 'x'}) --- - 0 ... tarantool> key_def:compare_keys({1000, 'x'}, {1000}) --- - 0 ... tarantool> key_def:compare_keys({2000, 'x'}, {1000, 'x'}) --- - 1 ... 

Version:

Module key_def