From f17772b7e202e34511544f5debe77a8dc32e46bb Mon Sep 17 00:00:00 2001 From: "a.ardeev" Date: Mon, 26 May 2025 16:34:32 +0300 Subject: [PATCH 1/4] Adds description of new ```key_def``` functions comparing data against the ```key_def``` object rules Since 3.1.0, new functions are added to ```key_def``` module. ```validate_key(key)``` - validates input key against the rules ```validate_full_key(key)``` - validates input key's all fields against the rules ```compare_keys(key_a, key_b)``` - Compares two keys against each other and the rules ```validate_tuple(tuple)``` - validates the tuple against the rules Fixes #4111 --- doc/reference/reference_lua/key_def.rst | 96 +++++++++++++++++++++++++ 1 file changed, 96 insertions(+) diff --git a/doc/reference/reference_lua/key_def.rst b/doc/reference/reference_lua/key_def.rst index d84369e94b..60c44d0094 100644 --- a/doc/reference/reference_lua/key_def.rst +++ b/doc/reference/reference_lua/key_def.rst @@ -221,3 +221,99 @@ to extract or compare the index key values. key_def = require('key_def') k = key_def.new({{type = 'string', fieldno = 3}}) k:totable() + + .. _key_validate_key: + + .. method:: validate_key(key) + + Since version :doc:`3.1.0 ` + Validates whether the input ``key`` (partially or completely) 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:** + + .. code-block:: lua + + local key_def = require('key_def') + -- Create a rule: key = {id (number), name (string)} + local rules = key_def.new({ + {fieldno = 1, type = 'number'}, + {fieldno = 2, type = 'string'} + }) + -- Validate key {1001} (only id data type). Returns nothing: + local ok, err = rules:validate_key({1001}) + + .. _key_validate_full_key: + + .. method:: validate_full_key(key) + + Since version :doc:`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:** + + .. code-block:: lua + + local key_def = require('key_def') + -- Create a rule: full key = {id, name} + local rules = key_def.new({ + {fieldno = 1, type = 'number'}, + {fieldno = 2, type = 'string'} + }) + -- Validate full key {1001, "Testuser"}. Returns nothing: + local ok, err = rules:validate_full_key({1001, "Testuser"}) + + .. _key_validate_tuple: + + .. method:: validate_tuple(tuple) + + Since version :doc:`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:** + + .. code-block:: lua + + local key_def = require('key_def') + -- Create a rule: tuple = {id (number), name (string), age (number)} + local rules = key_def.new({ + {fieldno = 1, type = 'number'}, + {fieldno = 2, type = 'string'}, + {fieldno = 3, type = 'number'} + }) + -- Validate tuple {1001, "Testuser", 28}. Returns nothing: + local ok, err = rules:validate_tuple({1001, "Testuser", 28}) + + .. _key_compare_keys: + + .. method:: compare_keys(key_a, key_b) + + Since version :doc:`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:** + + .. code-block:: lua + + local key_def = require('key_def') + -- Create rules: key = {timestamp (number), user_id (number)} + local rules = key_def.new({ + {fieldno = 1, type = 'number'}, + {fieldno = 2, type = 'number'} + }) + -- Compare keys. Returns -1 + local result = rules:compare_keys( + {1748266198238, 1001}, -- 2025-05-26, user_id=1001 + {1748266198239, 1002} -- 2025-05-26, user_id=1002 + ) \ No newline at end of file From ea5c0c7dbc3bef0dd8edadc1d7686bfc10a270de Mon Sep 17 00:00:00 2001 From: "a.ardeev" Date: Mon, 26 May 2025 16:58:18 +0300 Subject: [PATCH 2/4] Fix typos & rst syntax --- doc/reference/reference_lua/key_def.rst | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/doc/reference/reference_lua/key_def.rst b/doc/reference/reference_lua/key_def.rst index 60c44d0094..9dfa9f747f 100644 --- a/doc/reference/reference_lua/key_def.rst +++ b/doc/reference/reference_lua/key_def.rst @@ -227,8 +227,10 @@ to extract or compare the index key values. .. method:: validate_key(key) Since version :doc:`3.1.0 ` + Validates whether the input ``key`` (partially or completely) 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:** @@ -248,9 +250,11 @@ to extract or compare the index key values. .. method:: validate_full_key(key) - Since version :doc:`3.1.0 ` + Since version :doc:`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:** @@ -270,9 +274,11 @@ to extract or compare the index key values. .. method:: validate_tuple(tuple) - Since version :doc:`3.1.0 ` + Since version :doc:`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:** @@ -293,12 +299,14 @@ to extract or compare the index key values. .. method:: compare_keys(key_a, key_b) - Since version :doc:`3.1.0 ` + Since version :doc:`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 + + * ``<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. From 99f5f0845e7c386fc39e6e88e8817aaa32f13406 Mon Sep 17 00:00:00 2001 From: "a.ardeev" Date: Tue, 27 May 2025 13:11:13 +0300 Subject: [PATCH 3/4] Updates by comments --- doc/reference/reference_lua/key_def.rst | 127 ++++++++++++++++-------- 1 file changed, 87 insertions(+), 40 deletions(-) diff --git a/doc/reference/reference_lua/key_def.rst b/doc/reference/reference_lua/key_def.rst index 9dfa9f747f..6f682243bf 100644 --- a/doc/reference/reference_lua/key_def.rst +++ b/doc/reference/reference_lua/key_def.rst @@ -228,23 +228,44 @@ to extract or compare the index key values. Since version :doc:`3.1.0 ` - Validates whether the input ``key`` (partially or completely) matches the rules of the key definition object. + 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:** - .. code-block:: lua + .. code-block:: tarantoolsession - local key_def = require('key_def') - -- Create a rule: key = {id (number), name (string)} - local rules = key_def.new({ - {fieldno = 1, type = 'number'}, - {fieldno = 2, type = 'string'} - }) - -- Validate key {1001} (only id data type). Returns nothing: - local ok, err = rules:validate_key({1001}) + -- 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_validate_full_key: @@ -259,16 +280,19 @@ to extract or compare the index key values. **Example:** - .. code-block:: lua + .. code-block:: tarantoolsession - local key_def = require('key_def') - -- Create a rule: full key = {id, name} - local rules = key_def.new({ - {fieldno = 1, type = 'number'}, - {fieldno = 2, type = 'string'} - }) - -- Validate full key {1001, "Testuser"}. Returns nothing: - local ok, err = rules:validate_full_key({1001, "Testuser"}) + -- Create a rule: key = {1 ('unsigned'), 2 (string)} + -- Validate key {100, "Testuser"}. Returns nothing + + tarantool> key_def = require('key_def').new({{fieldno = 1, type = 'unsigned'}, + > {fieldno = 2, type = 'string'}}) + --- + ... + + tarantool> key_def:validate_full_key({100, "Testuser"}) + --- + ... .. _key_validate_tuple: @@ -283,17 +307,21 @@ to extract or compare the index key values. **Example:** - .. code-block:: lua + .. code-block:: tarantoolsession - local key_def = require('key_def') -- Create a rule: tuple = {id (number), name (string), age (number)} - local rules = key_def.new({ - {fieldno = 1, type = 'number'}, - {fieldno = 2, type = 'string'}, - {fieldno = 3, type = 'number'} - }) - -- Validate tuple {1001, "Testuser", 28}. Returns nothing: - local ok, err = rules:validate_tuple({1001, "Testuser", 28}) + -- 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_compare_keys: @@ -312,16 +340,35 @@ to extract or compare the index key values. **Example:** - .. code-block:: lua + .. code-block:: tarantoolsession + + -- 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 + ... - local key_def = require('key_def') - -- Create rules: key = {timestamp (number), user_id (number)} - local rules = key_def.new({ - {fieldno = 1, type = 'number'}, - {fieldno = 2, type = 'number'} - }) - -- Compare keys. Returns -1 - local result = rules:compare_keys( - {1748266198238, 1001}, -- 2025-05-26, user_id=1001 - {1748266198239, 1002} -- 2025-05-26, user_id=1002 - ) \ No newline at end of file + tarantool> key_def:compare_keys({2000, 'x'}, {1000, 'x'}) + --- + - 1 + ... \ No newline at end of file From 1c612647f284d11cdf010e5e8dbb306a8003d150 Mon Sep 17 00:00:00 2001 From: "a.ardeev" Date: Tue, 27 May 2025 15:09:42 +0300 Subject: [PATCH 4/4] Updates by comments --- doc/reference/reference_lua/key_def.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/doc/reference/reference_lua/key_def.rst b/doc/reference/reference_lua/key_def.rst index 6f682243bf..44be34ddb9 100644 --- a/doc/reference/reference_lua/key_def.rst +++ b/doc/reference/reference_lua/key_def.rst @@ -264,7 +264,7 @@ to extract or compare the index key values. tarantool> key_def:validate_key({1000, 'abc', 'xyz'}) --- - - error: Invalid key part count (expected [0..2], got 3) + - error: 'Invalid key part count: (expected [0..2], got 3) ... .. _key_validate_full_key: @@ -284,6 +284,7 @@ to extract or compare the index key values. -- 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'}}) @@ -294,6 +295,11 @@ to extract or compare the index key values. --- ... + tarantool> key_def:validate_full_key({100}) + --- + - error: 'Invalid key part count in an exact match: (expected 2, got 1) + ... + .. _key_validate_tuple: .. method:: validate_tuple(tuple)