From a1b055d0239ca532c8d51bbd2dd6464b11fa346e Mon Sep 17 00:00:00 2001
From: bigbes <bigbes@gmail.com>
Date: Fri, 3 Apr 2015 20:45:36 +0300
Subject: [PATCH] Changes in box.space/box.index documentation
---
doc/sphinx/book/app_c_lua_tutorial.rst | 2 +-
doc/sphinx/book/box/box_index.rst | 864 ++++++++++----------
doc/sphinx/book/box/box_schema.rst | 2 +-
doc/sphinx/book/box/box_space.rst | 1024 ++++++++++++------------
4 files changed, 957 insertions(+), 935 deletions(-)
diff --git a/doc/sphinx/book/app_c_lua_tutorial.rst b/doc/sphinx/book/app_c_lua_tutorial.rst
index 80e91273d8..b04ccdd21f 100644
--- a/doc/sphinx/book/app_c_lua_tutorial.rst
+++ b/doc/sphinx/book/app_c_lua_tutorial.rst
@@ -511,7 +511,7 @@ that are declared in line 1, because all of them are for use only within the fun
LINE 3: WHY "PAIRS()". Our job is to go through all the rows and there are two
ways to do it: with ``box.space.space-name:pairs()`` or with
-:func:`index.iterator <box.space.space-name.index[.index-name]:pairs>`.
+:func:`index.iterator <index_object.pairs>`.
We preferred ``pairs()`` because it is simpler.
LINE 4: WHY "PCALL". If we simply said "``lua_table = json.decode(t[2]))``", then
diff --git a/doc/sphinx/book/box/box_index.rst b/doc/sphinx/book/box/box_index.rst
index 899ee23d44..481d5a8a36 100644
--- a/doc/sphinx/book/box/box_index.rst
+++ b/doc/sphinx/book/box/box_index.rst
@@ -10,478 +10,480 @@ API is a direct binding to corresponding methods of index objects of type
.. module:: box.index
-.. data:: box.space.space-name.index.index-name.unique
-
- true if the index is unique.
-
- :rtype: boolean
-
-.. data:: box.space.space-name.index.index-name.type
-
- Index type, 'TREE' or 'HASH' or 'BITSET' or 'RTREE'.
-
- :rtype: string
-
-.. data:: box.space.space-name.index.index-name.parts
-
- An array describing index key fields.
-
- :rtype: table
-
- .. code-block:: lua
-
- tarantool> box.space.tester.index.primary
- ---
- unique: true
- parts:
- 0:
- type: NUM
- fieldno: 1
- id: 0
- space_id: 513
- name: primary
- type: TREE
- ...
-
-.. function:: box.space.space-name.index[.index-name]:pairs(bitset-value | field-value..., iterator-type)
-
- This method provides iteration support within an index. Parameter type is
- used to identify the semantics of iteration. Different index types support
- different iterators. The remaining arguments of the function are varying
- and depend on the iteration type. For example, a TREE index maintains a
- strict order of keys and can return all tuples in ascending or descending
- order, starting from the specified key. Other index types, however, do not
- support ordering.
-
- To understand consistency of tuples returned by an iterator, it's essential
- to know the principles of the Tarantool transaction processing subsystem. An
- iterator in Tarantool does not own a consistent read view. Instead, each
- procedure is granted exclusive access to all tuples and spaces until it
- encounters a "context switch": by causing a write to disk, network, or by an
- explicit call to :func:`fiber.yield`. When the execution flow returns
- to the yielded procedure, the data set could have changed significantly.
- Iteration, resumed after a yield point, does not preserve the read view,
- but continues with the new content of the database.
-
- :param type: iteration strategy as defined in tables below
- :return: this method returns an iterator closure, i.e. a function which can
- be used to get the next value on each invocation
- :rtype: function, tuple
-
- :except: Selected iteration type is not supported in the subject index type,
- or supplied parameters do not match iteration type.
-
- Complexity Factors: Index size, Index type, Number of tuples accessed.
-
- .. container:: table
-
- **TREE iterator types**
-
- +---------------+-----------+---------------------------------------------+
- | Type | Arguments | Description |
- +===============+===========+=============================================+
- | box.index.ALL | none | Iterate over all tuples in an index. Tuples |
- | or 'ALL' | | are returned in ascending order of the key. |
- +---------------+-----------+---------------------------------------------+
- | box.index.EQ | field | Equality iterator: iterate over all tuples |
- | or 'EQ' | values | where field values = key values. Parts of a |
- | | | multi-part key need to be separated by |
- | | | commas. |
- | | | |
- | | | If the number of field values is less than |
- | | | the number of parts of a multi-part key, |
- | | | the missing field values are considered to |
- | | | be matching. |
- | | | |
- | | | If there are multiple matches, then tuples |
- | | | are returned in ascending order by key. |
- +---------------+-----------+---------------------------------------------+
- | box.index.GT | field | Keys match if key values are greater than |
- | or 'GT' | values | field values. If the number of field values |
- | | | is less than the number of parts of a |
- | | | multi-part key, the missing field values |
- | | | are considered to be matching. If the field |
- | | | value is ``nil``, iteration starts from the |
- | | | smallest key in the index. Tuples are |
- | | | returned in ascending order by key. |
- +---------------+-----------+---------------------------------------------+
- | box.index.REQ | field | Reverse equality iterator. Matching is |
- | or 'REQ' | values | determined in the same way as for |
- | | | ``box.index.EQ``, but, if there are multiple|
- | | | matches, then tuples are returned in |
- | | | descending order by key, |
- +---------------+-----------+---------------------------------------------+
- | box.index.GE | field | Keys match if key values are greater than |
- | or 'GE' | values | or equal to field values. Tuples are |
- | | | returned in ascending order by key. If the |
- | | | field value is ``nil``, iteration starts |
- | | | from the first key in the index. |
- +---------------+-----------+---------------------------------------------+
- | box.index.LT | field | Keys match if key values are less than |
- | or 'LT' | values | field values. Tuples are returned in |
- | | | descending order by key. If the field value |
- | | | is ``nil``, iteration starts from the last |
- | | | key in the index. |
- +---------------+-----------+---------------------------------------------+
- | box.index.LE | field | Keys match if key values are less than or |
- | or 'LE' | values | equal to field values. Tuples are returned |
- | | | in descending order by key. If the field |
- | | | value is ``nil``, iteration starts from |
- | | | the last key in the index. |
- +---------------+-----------+---------------------------------------------+
-
- **HASH iterator types**
-
- +---------------+-----------+---------------------------------------------+
- | Type | Arguments | Description |
- +===============+===========+=============================================+
- | box.index.ALL | none | Iterate over all tuples in an index. Tuples |
- | or 'ALL' | | are returned in ascending order of the key. |
- +---------------+-----------+---------------------------------------------+
- | box.index.EQ | field | Equality iterator: iterate over all tuples |
- | or 'EQ' | values | matching the key. Parts of a multi-part |
- | | | key need to be separated by commas. |
- | | | |
- | | | A HASH index only supports exact match: |
- | | | all parts of a key participating in the |
- | | | index must be provided. |
- | | | |
- | | | HASH indexes are always unique. |
- +---------------+-----------+---------------------------------------------+
- | box.index.GT | field | Keys match if hashed key values are greater |
- | or 'GT' | values | than hashed field values. If the number of |
- | | | field values is less than the number of |
- | | | parts of a multi-part key, the result is an |
- | | | error. Tuples are returned in ascending |
- | | | order by hashed key, so the order will |
- | | | appear to be random. Provided that the |
- | | | space is not being updated, the 'GT' |
- | | | iterator can be used to retrieve all |
- | | | tuples piece by piece, by supplying the |
- | | | last returned value from the previous |
- | | | range as the start field value for an |
- | | | iterator over the next range. |
- +---------------+-----------+---------------------------------------------+
-
- **BITSET iterator types**
-
- +----------------------------+-----------+---------------------------------------------+
- | Type | Arguments | Description |
- +============================+===========+=============================================+
- | box.index.ALL | none | Iterate over all tuples in an index. Tuples |
- | or 'ALL' | | are returned in ascending order of the |
- | | | key's bitset, and so will appear to be |
- | | | unordered. |
- +----------------------------+-----------+---------------------------------------------+
- | box.index.EQ | field | Equality iterator: iterate over all tuples |
- | or 'EQ' | values | matching the field values. If there are |
- | | | multiple field values, they need to be |
- | | | separated by commas. |
- | | | |
- | | | BITSET indexes are always unique. |
- +----------------------------+-----------+---------------------------------------------+
- | box.index.BITS_ALL_SET | field | Keys match if all of the bits specified in |
- | | values | 'bit mask' are set. |
- +----------------------------+-----------+---------------------------------------------+
- | box.index.BITS_ANY_SET | field | Keys match if any of the bits specified in |
- | | values | 'bit mask' is set. |
- +----------------------------+-----------+---------------------------------------------+
- | box.index.BITS_ALL_NOT_SET | field | Keys match if none of the bits specified in |
- | | values | 'bit mask' is set. |
- +----------------------------+-----------+---------------------------------------------+
-
- .. _rtree-iterator:
-
- **RTREE iterator types**
-
- +--------------------+-----------+---------------------------------------------+
- | Type | Arguments | Description |
- +====================+===========+=============================================+
- | box.index.ALL | none | All keys match. Tuples are returned in |
- | or 'ALL' | | ascending order of the primary key. |
- +--------------------+-----------+---------------------------------------------+
- | box.index.EQ | field | Keys match if the rectangle defined by the |
- | or 'EQ' | values | field values is the same as the rectangle |
- | | | defined by the key -- where "key" means |
- | | | "the key in the RTREE index" and |
- | | | "rectangle" means "rectangle as explained |
- | | | in section RTREE_. |
- +--------------------+-----------+---------------------------------------------+
- | box.index.GT | field | Keys match if all points of the rectangle |
- | or 'GT' | values | defined by the field values are within the |
- | | | rectangle defined by the key. |
- +--------------------+-----------+---------------------------------------------+
- | box.index.GE | field | Keys match if all points of the rectangle |
- | or 'GE' | values | defined by the field values are within, or |
- | | | at the side of, the rectangle defined by |
- | | | the key. |
- +--------------------+-----------+---------------------------------------------+
- | box.index.LT | field | Keys match if all points of the rectangle |
- | or 'LT' | values | defined by the key are within the rectangle |
- | | | defined by the field values. |
- +--------------------+-----------+---------------------------------------------+
- | box.index.LE | field | Keys match if all points of the rectangle |
- | or 'LE' | values | defined by the key are within, or at the |
- | | | side of, the rectangle defined by the field |
- | | | values. |
- +--------------------+-----------+---------------------------------------------+
- | box.index.OVERLAPS | field | Keys match if all points of the rectangle |
- | or 'OVERLAPS' | values | defined by the key are within, or at the |
- | | | side of, the rectangle defined by the field |
- | | | values. |
- +--------------------+-----------+---------------------------------------------+
- | box.index.NEIGHBOR | field | Keys match if all points of the rectangle |
- | or 'NEIGHBOR' | values | defined by the key are within, or at the |
- | | | side of, the rectangle defined by the field |
- | | | values. |
- +--------------------+-----------+---------------------------------------------+
-
- .. code-block:: lua
-
- tarantool> s = box.schema.space.create('space17')
- ---
- ...
- tarantool> s:create_index('primary', {parts = {1, 'STR', 2, 'STR'}})
- ---
- ...
- tarantool> s:insert{'C', 'C'}
- ---
- - ['C', 'C']
- ...
- tarantool> s:insert{'B', 'A'}
- ---
- - ['B', 'A']
- ...
- tarantool> s:insert{'C', '!'}
- ---
- - ['C', '!']
- ...
- tarantool> s:insert{'A', 'C'}
- ---
- - ['A', 'C']
- ...
- tarantool> console = require('console'); console.delimiter('!')
- ---
- ...
- tarantool> function example()
- > for _, tuple in
- > s.index.primary:pairs(nil, {iterator = box.index.ALL}) do
- > print(tuple)
- > end
- > end!
- ---
- ...
- tarantool> console.delimiter('')!
- ---
- ...
- tarantool> example()
- ['A', 'C']
- ['B', 'A']
- ['C', '!']
- ['C', 'C']
- ---
- ...
- tarantool> s:drop()
- ---
- ...
-
-.. function:: box.space.space-name[.index.index-name]:select({[field-value [, field-value ...]]}, {[option [, option ...]]})
-
- This is is an alternative to box.space...select() which goes via a
- particular index and can make use of additional parameters that specify the
- iterator type, and the limit (that is, the maximum number of tuples to
- return) and the offset (that is, which tuple to start with in the list).
-
- :param lua-value field-value(s): values to be matched against the index key.
- :param lua-value option(s): any or all of iterator=iterator-type
- limit=maximum-number-of-tuples,
- offset=start-tuple-number.
-
- :return: the tuple or tuples that match the field values.
- :rtype: tuple set as a Lua table
-
- .. code-block:: lua
-
- -- Create a space named tester.
- -- Create a unique index 'primary', which won't be needed for this example.
- -- Create a non-unique index 'secondary' with an index on the second field.
- -- Insert three tuples, values in field[2] equal to 'X', 'Y', and 'Z'.
- -- Select all tuples where the secondary index keys are greater than 'X'.
- box.schema.space.create('tester')
- box.space.tester:create_index('primary', {parts = {1, 'NUM' }})
- box.space.tester:create_index('secondary', {type = 'tree', unique = false, parts = {2, 'STR'}})
- box.space.tester:insert{1,'X','Row with field[2]=X'}
- box.space.tester:insert{2,'Y','Row with field[2]=Y'}
- box.space.tester:insert{3,'Z','Row with field[2]=Z'}
- box.space.tester.index.secondary:select({'X'}, {iterator = 'GT', limit = 1000})
-
- The result will be a table of tuple and will look like this:
-
- .. code-block:: yaml
-
- ---
- - - [2, 'Y', 'Row with field[2]=Y']
- - [3, 'Z', 'Row with field[2]=Z']
- ...
-
- .. NOTE::
-
- [.index.index-name] is optional. If it is omitted, then the assumed
- index is the first (primary-key) index. Therefore, for the example
- above, ``box.space.tester:select({1}, {iterator = 'GT'})`` would have
- returned the same two rows, via the 'primary' index.
-
- .. NOTE::
-
- ``iterator = iterator type`` is optional. If it is omitted, then
- ``iterator = 'EQ'`` is assumed.
-
- .. NOTE::
-
- ``field-value [, field-value ...]`` is optional. If it is omitted,
- then every key in the index is considered to be a match, regardless of
- iterator type. Therefore, for the example above,
- ``box.space.tester:select{}`` will select every tuple in the tester
- space via the first (primary-key) index.
-
- .. NOTE::
-
- ``box.space.space-name.index.index-name:select(...)[1]``. can be
- replaced by ``box.space.space-name.index.index-name:get(...)``.
- That is, get can be used as a convenient shorthand to get the first
- tuple in the tuple set that would be returned by select. However,
- if there is more than one tuple in the tuple set, then get returns
- an error.
-
-.. function:: box.space.space-name.index.index-name:min([key-value])
+.. class:: index_object
+
+ .. data:: unique
+
+ true if the index is unique.
+
+ :rtype: boolean
+
+ .. data:: type
+
+ Index type, 'TREE' or 'HASH' or 'BITSET' or 'RTREE'.
+
+ :rtype: string
+
+ .. data:: parts
+
+ An array describing index key fields.
+
+ :rtype: table
+
+ .. code-block:: lua
+
+ tarantool> box.space.tester.index.primary
+ ---
+ unique: true
+ parts:
+ 0:
+ type: NUM
+ fieldno: 1
+ id: 0
+ space_id: 513
+ name: primary
+ type: TREE
+ ...
+
+ .. function:: pairs(bitset-value | field-value..., iterator-type)
+
+ This method provides iteration support within an index. Parameter type is
+ used to identify the semantics of iteration. Different index types support
+ different iterators. The remaining arguments of the function are varying
+ and depend on the iteration type. For example, a TREE index maintains a
+ strict order of keys and can return all tuples in ascending or descending
+ order, starting from the specified key. Other index types, however, do not
+ support ordering.
+
+ To understand consistency of tuples returned by an iterator, it's essential
+ to know the principles of the Tarantool transaction processing subsystem. An
+ iterator in Tarantool does not own a consistent read view. Instead, each
+ procedure is granted exclusive access to all tuples and spaces until it
+ encounters a "context switch": by causing a write to disk, network, or by an
+ explicit call to :func:`fiber.yield`. When the execution flow returns
+ to the yielded procedure, the data set could have changed significantly.
+ Iteration, resumed after a yield point, does not preserve the read view,
+ but continues with the new content of the database.
+
+ :param type: iteration strategy as defined in tables below
+ :return: this method returns an iterator closure, i.e. a function which can
+ be used to get the next value on each invocation
+ :rtype: function, tuple
+
+ :except: Selected iteration type is not supported in the subject index type,
+ or supplied parameters do not match iteration type.
+
+ Complexity Factors: Index size, Index type, Number of tuples accessed.
+
+ .. container:: table
+
+ **TREE iterator types**
+
+ +---------------+-----------+---------------------------------------------+
+ | Type | Arguments | Description |
+ +===============+===========+=============================================+
+ | box.index.ALL | none | Iterate over all tuples in an index. Tuples |
+ | or 'ALL' | | are returned in ascending order of the key. |
+ +---------------+-----------+---------------------------------------------+
+ | box.index.EQ | field | Equality iterator: iterate over all tuples |
+ | or 'EQ' | values | where field values = key values. Parts of a |
+ | | | multi-part key need to be separated by |
+ | | | commas. |
+ | | | |
+ | | | If the number of field values is less than |
+ | | | the number of parts of a multi-part key, |
+ | | | the missing field values are considered to |
+ | | | be matching. |
+ | | | |
+ | | | If there are multiple matches, then tuples |
+ | | | are returned in ascending order by key. |
+ +---------------+-----------+---------------------------------------------+
+ | box.index.GT | field | Keys match if key values are greater than |
+ | or 'GT' | values | field values. If the number of field values |
+ | | | is less than the number of parts of a |
+ | | | multi-part key, the missing field values |
+ | | | are considered to be matching. If the field |
+ | | | value is ``nil``, iteration starts from the |
+ | | | smallest key in the index. Tuples are |
+ | | | returned in ascending order by key. |
+ +---------------+-----------+---------------------------------------------+
+ | box.index.REQ | field | Reverse equality iterator. Matching is |
+ | or 'REQ' | values | determined in the same way as for |
+ | | | ``box.index.EQ``, but, if there are multiple|
+ | | | matches, then tuples are returned in |
+ | | | descending order by key, |
+ +---------------+-----------+---------------------------------------------+
+ | box.index.GE | field | Keys match if key values are greater than |
+ | or 'GE' | values | or equal to field values. Tuples are |
+ | | | returned in ascending order by key. If the |
+ | | | field value is ``nil``, iteration starts |
+ | | | from the first key in the index. |
+ +---------------+-----------+---------------------------------------------+
+ | box.index.LT | field | Keys match if key values are less than |
+ | or 'LT' | values | field values. Tuples are returned in |
+ | | | descending order by key. If the field value |
+ | | | is ``nil``, iteration starts from the last |
+ | | | key in the index. |
+ +---------------+-----------+---------------------------------------------+
+ | box.index.LE | field | Keys match if key values are less than or |
+ | or 'LE' | values | equal to field values. Tuples are returned |
+ | | | in descending order by key. If the field |
+ | | | value is ``nil``, iteration starts from |
+ | | | the last key in the index. |
+ +---------------+-----------+---------------------------------------------+
+
+ **HASH iterator types**
+
+ +---------------+-----------+---------------------------------------------+
+ | Type | Arguments | Description |
+ +===============+===========+=============================================+
+ | box.index.ALL | none | Iterate over all tuples in an index. Tuples |
+ | or 'ALL' | | are returned in ascending order of the key. |
+ +---------------+-----------+---------------------------------------------+
+ | box.index.EQ | field | Equality iterator: iterate over all tuples |
+ | or 'EQ' | values | matching the key. Parts of a multi-part |
+ | | | key need to be separated by commas. |
+ | | | |
+ | | | A HASH index only supports exact match: |
+ | | | all parts of a key participating in the |
+ | | | index must be provided. |
+ | | | |
+ | | | HASH indexes are always unique. |
+ +---------------+-----------+---------------------------------------------+
+ | box.index.GT | field | Keys match if hashed key values are greater |
+ | or 'GT' | values | than hashed field values. If the number of |
+ | | | field values is less than the number of |
+ | | | parts of a multi-part key, the result is an |
+ | | | error. Tuples are returned in ascending |
+ | | | order by hashed key, so the order will |
+ | | | appear to be random. Provided that the |
+ | | | space is not being updated, the 'GT' |
+ | | | iterator can be used to retrieve all |
+ | | | tuples piece by piece, by supplying the |
+ | | | last returned value from the previous |
+ | | | range as the start field value for an |
+ | | | iterator over the next range. |
+ +---------------+-----------+---------------------------------------------+
+
+ **BITSET iterator types**
+
+ +----------------------------+-----------+---------------------------------------------+
+ | Type | Arguments | Description |
+ +============================+===========+=============================================+
+ | box.index.ALL | none | Iterate over all tuples in an index. Tuples |
+ | or 'ALL' | | are returned in ascending order of the |
+ | | | key's bitset, and so will appear to be |
+ | | | unordered. |
+ +----------------------------+-----------+---------------------------------------------+
+ | box.index.EQ | field | Equality iterator: iterate over all tuples |
+ | or 'EQ' | values | matching the field values. If there are |
+ | | | multiple field values, they need to be |
+ | | | separated by commas. |
+ | | | |
+ | | | BITSET indexes are always unique. |
+ +----------------------------+-----------+---------------------------------------------+
+ | box.index.BITS_ALL_SET | field | Keys match if all of the bits specified in |
+ | | values | 'bit mask' are set. |
+ +----------------------------+-----------+---------------------------------------------+
+ | box.index.BITS_ANY_SET | field | Keys match if any of the bits specified in |
+ | | values | 'bit mask' is set. |
+ +----------------------------+-----------+---------------------------------------------+
+ | box.index.BITS_ALL_NOT_SET | field | Keys match if none of the bits specified in |
+ | | values | 'bit mask' is set. |
+ +----------------------------+-----------+---------------------------------------------+
+
+ .. _rtree-iterator:
+
+ **RTREE iterator types**
+
+ +--------------------+-----------+---------------------------------------------+
+ | Type | Arguments | Description |
+ +====================+===========+=============================================+
+ | box.index.ALL | none | All keys match. Tuples are returned in |
+ | or 'ALL' | | ascending order of the primary key. |
+ +--------------------+-----------+---------------------------------------------+
+ | box.index.EQ | field | Keys match if the rectangle defined by the |
+ | or 'EQ' | values | field values is the same as the rectangle |
+ | | | defined by the key -- where "key" means |
+ | | | "the key in the RTREE index" and |
+ | | | "rectangle" means "rectangle as explained |
+ | | | in section RTREE_. |
+ +--------------------+-----------+---------------------------------------------+
+ | box.index.GT | field | Keys match if all points of the rectangle |
+ | or 'GT' | values | defined by the field values are within the |
+ | | | rectangle defined by the key. |
+ +--------------------+-----------+---------------------------------------------+
+ | box.index.GE | field | Keys match if all points of the rectangle |
+ | or 'GE' | values | defined by the field values are within, or |
+ | | | at the side of, the rectangle defined by |
+ | | | the key. |
+ +--------------------+-----------+---------------------------------------------+
+ | box.index.LT | field | Keys match if all points of the rectangle |
+ | or 'LT' | values | defined by the key are within the rectangle |
+ | | | defined by the field values. |
+ +--------------------+-----------+---------------------------------------------+
+ | box.index.LE | field | Keys match if all points of the rectangle |
+ | or 'LE' | values | defined by the key are within, or at the |
+ | | | side of, the rectangle defined by the field |
+ | | | values. |
+ +--------------------+-----------+---------------------------------------------+
+ | box.index.OVERLAPS | field | Keys match if all points of the rectangle |
+ | or 'OVERLAPS' | values | defined by the key are within, or at the |
+ | | | side of, the rectangle defined by the field |
+ | | | values. |
+ +--------------------+-----------+---------------------------------------------+
+ | box.index.NEIGHBOR | field | Keys match if all points of the rectangle |
+ | or 'NEIGHBOR' | values | defined by the key are within, or at the |
+ | | | side of, the rectangle defined by the field |
+ | | | values. |
+ +--------------------+-----------+---------------------------------------------+
+
+ .. code-block:: lua
+
+ tarantool> s = box.schema.space.create('space17')
+ ---
+ ...
+ tarantool> s:create_index('primary', {parts = {1, 'STR', 2, 'STR'}})
+ ---
+ ...
+ tarantool> s:insert{'C', 'C'}
+ ---
+ - ['C', 'C']
+ ...
+ tarantool> s:insert{'B', 'A'}
+ ---
+ - ['B', 'A']
+ ...
+ tarantool> s:insert{'C', '!'}
+ ---
+ - ['C', '!']
+ ...
+ tarantool> s:insert{'A', 'C'}
+ ---
+ - ['A', 'C']
+ ...
+ tarantool> console = require('console'); console.delimiter('!')
+ ---
+ ...
+ tarantool> function example()
+ > for _, tuple in
+ > s.index.primary:pairs(nil, {iterator = box.index.ALL}) do
+ > print(tuple)
+ > end
+ > end!
+ ---
+ ...
+ tarantool> console.delimiter('')!
+ ---
+ ...
+ tarantool> example()
+ ['A', 'C']
+ ['B', 'A']
+ ['C', '!']
+ ['C', 'C']
+ ---
+ ...
+ tarantool> s:drop()
+ ---
+ ...
+
+ .. function:: select(key, options)
+
+ This is is an alternative to box.space...select() which goes via a
+ particular index and can make use of additional parameters that specify the
+ iterator type, and the limit (that is, the maximum number of tuples to
+ return) and the offset (that is, which tuple to start with in the list).
+
+ :param lua-table or scalar key: values to be matched against the index key.
+ :param lua-table options: table with any or all of iterator=iterator-type
+ limit=maximum-number-of-tuples,
+ offset=start-tuple-number.
+
+ :return: the tuple or tuples that match the field values.
+ :rtype: tuple set as a Lua table
+
+ .. code-block:: lua
+
+ -- Create a space named tester.
+ -- Create a unique index 'primary', which won't be needed for this example.
+ -- Create a non-unique index 'secondary' with an index on the second field.
+ -- Insert three tuples, values in field[2] equal to 'X', 'Y', and 'Z'.
+ -- Select all tuples where the secondary index keys are greater than 'X'.
+ box.schema.space.create('tester')
+ box.space.tester:create_index('primary', {parts = {1, 'NUM' }})
+ box.space.tester:create_index('secondary', {type = 'tree', unique = false, parts = {2, 'STR'}})
+ box.space.tester:insert{1,'X','Row with field[2]=X'}
+ box.space.tester:insert{2,'Y','Row with field[2]=Y'}
+ box.space.tester:insert{3,'Z','Row with field[2]=Z'}
+ box.space.tester.index.secondary:select({'X'}, {iterator = 'GT', limit = 1000})
+
+ The result will be a table of tuple and will look like this:
+
+ .. code-block:: yaml
+
+ ---
+ - - [2, 'Y', 'Row with field[2]=Y']
+ - [3, 'Z', 'Row with field[2]=Z']
+ ...
+
+ .. NOTE::
+
+ [.index.index-name] is optional. If it is omitted, then the assumed
+ index is the first (primary-key) index. Therefore, for the example
+ above, ``box.space.tester:select({1}, {iterator = 'GT'})`` would have
+ returned the same two rows, via the 'primary' index.
+
+ .. NOTE::
+
+ ``iterator = iterator type`` is optional. If it is omitted, then
+ ``iterator = 'EQ'`` is assumed.
+
+ .. NOTE::
+
+ ``field-value [, field-value ...]`` is optional. If it is omitted,
+ then every key in the index is considered to be a match, regardless of
+ iterator type. Therefore, for the example above,
+ ``box.space.tester:select{}`` will select every tuple in the tester
+ space via the first (primary-key) index.
+
+ .. NOTE::
+
+ ``box.space.space-name.index.index-name:select(...)[1]``. can be
+ replaced by ``box.space.space-name.index.index-name:get(...)``.
+ That is, get can be used as a convenient shorthand to get the first
+ tuple in the tuple set that would be returned by select. However,
+ if there is more than one tuple in the tuple set, then get returns
+ an error.
+
+ .. function:: min([key-value])
- Find the minimum value in the specified index.
+ Find the minimum value in the specified index.
- :return: the tuple for the first key in the index. If optional
- ``key-value`` is supplied, returns the first key which
- is greater than or equal to ``key-value``.
- :rtype: tuple
- :except: index is not of type 'TREE'.
+ :return: the tuple for the first key in the index. If optional
+ ``key-value`` is supplied, returns the first key which
+ is greater than or equal to ``key-value``.
+ :rtype: tuple
+ :except: index is not of type 'TREE'.
- Complexity Factors: Index size, Index type.
+ Complexity Factors: Index size, Index type.
- .. code-block:: lua
+ .. code-block:: lua
- tarantool> box.space.tester.index.primary:min()
- ---
- - ['Alpha!', 55, 'This is the first tuple!']
- ...
+ tarantool> box.space.tester.index.primary:min()
+ ---
+ - ['Alpha!', 55, 'This is the first tuple!']
+ ...
-.. function:: box.space.space-name.index.index-name:max([key-value])
+ .. function:: max([key-value])
- Find the maximum value in the specified index.
+ Find the maximum value in the specified index.
- :return: the tuple for the last key in the index. If optional ``key-value``
- is supplied, returns the last key which is less than or equal to
- ``key-value``.
- :rtype: tuple
- :except: index is not of type 'TREE'.
+ :return: the tuple for the last key in the index. If optional ``key-value``
+ is supplied, returns the last key which is less than or equal to
+ ``key-value``.
+ :rtype: tuple
+ :except: index is not of type 'TREE'.
- Complexity Factors: Index size, Index type.
+ Complexity Factors: Index size, Index type.
- .. code-block:: lua
+ .. code-block:: lua
- tarantool> box.space.tester.index.primary:max()
- ---
- - ['Gamma!', 55, 'This is the third tuple!']
- ...
+ tarantool> box.space.tester.index.primary:max()
+ ---
+ - ['Gamma!', 55, 'This is the third tuple!']
+ ...
-.. function:: box.space.space-name.index.index-name:random(random-value)
+ .. function:: random(random-value)
- Find a random value in the specified index. This method is useful when it's
- important to get insight into data distribution in an index without having
- to iterate over the entire data set.
+ Find a random value in the specified index. This method is useful when it's
+ important to get insight into data distribution in an index without having
+ to iterate over the entire data set.
- :param integer random-value: an arbitrary non-negative integer.
- :return: the tuple for the random key in the index.
- :rtype: tuple
+ :param integer random-value: an arbitrary non-negative integer.
+ :return: the tuple for the random key in the index.
+ :rtype: tuple
- Complexity Factors: Index size, Index type.
+ Complexity Factors: Index size, Index type.
- .. code-block:: lua
+ .. code-block:: lua
- tarantool> box.space.tester.index.secondary:random(1)
- ---
- - ['Beta!', 66, 'This is the second tuple!']
- ...
+ tarantool> box.space.tester.index.secondary:random(1)
+ ---
+ - ['Beta!', 66, 'This is the second tuple!']
+ ...
-.. function:: box.space.space-name.index.index-name:count(key-value, options)
+ .. function:: count(key-value, options)
- Iterate over an index, counting the number of
- tuples which equal the provided search criteria.
+ Iterate over an index, counting the number of
+ tuples which equal the provided search criteria.
- :param lua-value key-value: the value which must match the key(s) in the
- specified index. The type may be a list of
- field-values, or a tuple containing only
- the field-values.
+ :param lua-value key-value: the value which must match the key(s) in the
+ specified index. The type may be a list of
+ field-values, or a tuple containing only
+ the field-values.
- :return: the number of matching index keys. The ``index`` function
- is only applicable for the memtx storage engine.
- :rtype: number
+ :return: the number of matching index keys. The ``index`` function
+ is only applicable for the memtx storage engine.
+ :rtype: number
- .. code-block:: lua
+ .. code-block:: lua
- tarantool> box.space.tester.index.primary:count(999)
- ---
- - 0
- ...
- tarantool> box.space.tester.index.primary:count('Alpha!', { iterator = 'LE' })
- ---
- - 1
- ...
+ tarantool> box.space.tester.index.primary:count(999)
+ ---
+ - 0
+ ...
+ tarantool> box.space.tester.index.primary:count('Alpha!', { iterator = 'LE' })
+ ---
+ - 1
+ ...
-.. function:: box.space.space-name.index.index-name:alter{options}
+ .. function:: alter({options})
- Alter an index.
+ Alter an index.
- :param table options: options list for create_index().
- :return: nil
+ :param table options: options list for create_index().
+ :return: nil
- :except: If index-name doesn't exist.
- :except: The first index cannot be changed to {unique = false}.
- :except: The alter function is only applicable for the memtx storage engine.
+ :except: If index-name doesn't exist.
+ :except: The first index cannot be changed to {unique = false}.
+ :except: The alter function is only applicable for the memtx storage engine.
- .. code-block:: lua
+ .. code-block:: lua
- tarantool> box.space.space55.index.primary:alter({type = 'HASH'})
- ---
- ...
+ tarantool> box.space.space55.index.primary:alter({type = 'HASH'})
+ ---
+ ...
-.. function:: space-name.index.index-name:drop()
+ .. function:: drop()
- Drop an index. Dropping a primary-key index has
- a side effect: all tuples are deleted.
+ Drop an index. Dropping a primary-key index has
+ a side effect: all tuples are deleted.
- :return: nil.
- :except: If index-name doesn't exist.
+ :return: nil.
+ :except: If index-name doesn't exist.
- .. code-block:: lua
+ .. code-block:: lua
- tarantool> box.space.space55.index.primary:drop()
- ---
- ...
+ tarantool> box.space.space55.index.primary:drop()
+ ---
+ ...
-.. function:: space-name.index.index-name:rename(index-name)
+ .. function:: rename(index-name)
- Rename an index.
+ Rename an index.
- :param string index-name: new name for index.
- :return: nil
- :except: If index-name doesn't exist.
+ :param string index-name: new name for index.
+ :return: nil
+ :except: If index-name doesn't exist.
- .. code-block:: lua
+ .. code-block:: lua
- tarantool> box.space.space55.index.primary:rename('secondary')
- ---
- ...
+ tarantool> box.space.space55.index.primary:rename('secondary')
+ ---
+ ...
- Complexity Factors: Index size, Index type, Number of tuples accessed.
+ Complexity Factors: Index size, Index type, Number of tuples accessed.
===========================================================
diff --git a/doc/sphinx/book/box/box_schema.rst b/doc/sphinx/book/box/box_schema.rst
index 8b6bdebc74..ce26ff70c6 100644
--- a/doc/sphinx/book/box/box_schema.rst
+++ b/doc/sphinx/book/box/box_schema.rst
@@ -55,6 +55,6 @@ The ``box.schema`` package has one data-definition function: ``space.create()``.
...
After a space is created, usually the next step is to
-:func:`create an index <box.space.space-name.create_index>` for it,
+:func:`create an index <space_object.create_index>` for it,
and then it is available for insert, select, and all the other :mod:`box.space`
functions.
diff --git a/doc/sphinx/book/box/box_space.rst b/doc/sphinx/book/box/box_space.rst
index 0ba777a62b..8fa06ed36d 100644
--- a/doc/sphinx/book/box/box_space.rst
+++ b/doc/sphinx/book/box/box_space.rst
@@ -13,566 +13,586 @@ is available in file
A list of all ``box.space`` functions follows, then comes a list of all
``box.space`` members.
-.. function:: box.space.space-name:create_index(index-name [, {options} ])
-
- Create an index. It is **mandatory** to create an index for a tuple set
- before trying to insert tuples into it, or select tuples from it. The
- first created index, which will be used as the primary-key index, must be
- **unique**.
-
- :param string index-name: name of index, which should not be a number and
- should not contain special characters;
- :param table options:
-
- :return: index object
- :rtype: userdata
-
- .. container:: table
-
- **Options for box.space...create_index**
-
- +---------------+--------------------+-----------------------------+---------------------+
- | Name | Effect | Type | Default |
- +===============+====================+=============================+=====================+
- | type | type of index | string | 'TREE' |
- | | | ('HASH', 'TREE', | |
- | | | 'BITSET', 'RTREE') | |
- | | | | |
- | | | | |
- | | | | |
- +---------------+--------------------+-----------------------------+---------------------+
- | id | unique identifier | number | last index's id, +1 |
- +---------------+--------------------+-----------------------------+---------------------+
- | unique | index is unique | boolean | true |
- +---------------+--------------------+-----------------------------+---------------------+
- | if_not_exists | no error if | boolean | false |
- | | duplicate name | | |
- +---------------+--------------------+-----------------------------+---------------------+
- | parts | field-numbers + | ``{field_no, 'NUM'|'STR'}`` | ``{1, 'NUM'}`` |
- | | types | | |
- +---------------+--------------------+-----------------------------+---------------------+
-
- Possible errors: too many parts. A type options other than TREE, or a
- unique option other than unique, or a parts option with more than one
- field component, is only applicable for the memtx storage engine.
+.. class:: space_object
- .. code-block:: lua
+ .. function:: create_index(index-name [, {options} ])
- tarantool> s = box.space.space55
- ---
- ...
- tarantool> s:create_index('primary', {unique = true, parts = {1, 'NUM', 2, 'STR'}})
- ---
- ...
+ Create an index. It is **mandatory** to create an index for a tuple set
+ before trying to insert tuples into it, or select tuples from it. The
+ first created index, which will be used as the primary-key index, must be
+ **unique**.
-.. function:: box.space.space-name:insert{field-value [, field-value ...]}
+ :param string index-name: name of index, which should not be a number and
+ should not contain special characters;
+ :param table options:
- Insert a tuple into a space.
+ :return: index object
+ :rtype: index_object
- :param userdata space-name:
- :param lua-value field-value(s): fields of the new tuple.
- :return: the inserted tuple
- :rtype: tuple
+ .. container:: table
- :except: If a tuple with the same unique-key value already exists,
- returns ``ER_TUPLE_FOUND``.
+ **Options table**
- .. code-block:: lua
-
- box.space.tester:insert{5000,'tuple number five thousand'}
+ +---------------+--------------------+-----------------------------+---------------------+
+ | Name | Effect | Type | Default |
+ +===============+====================+=============================+=====================+
+ | type | type of index | string | 'TREE' |
+ | | | ('HASH', 'TREE', | |
+ | | | 'BITSET', 'RTREE') | |
+ | | | | |
+ | | | | |
+ | | | | |
+ +---------------+--------------------+-----------------------------+---------------------+
+ | id | unique identifier | number | last index's id, +1 |
+ +---------------+--------------------+-----------------------------+---------------------+
+ | unique | index is unique | boolean | true |
+ +---------------+--------------------+-----------------------------+---------------------+
+ | if_not_exists | no error if | boolean | false |
+ | | duplicate name | | |
+ +---------------+--------------------+-----------------------------+---------------------+
+ | parts | field-numbers + | ``{field_no, 'NUM'|'STR'}`` | ``{1, 'NUM'}`` |
+ | | types | | |
+ +---------------+--------------------+-----------------------------+---------------------+
-.. function:: box.space.space-name:select{field-value [, field-value ...]}
+ Possible errors: too many parts. A type options other than TREE, or a
+ unique option other than unique, or a parts option with more than one
+ field component, is only applicable for the memtx storage engine.
- Search for a tuple or a set of tuples in the given space.
+ .. code-block:: lua
- :param userdata space-name:
- :param lua-value field-value(s): values to be matched against the index
- key, which may be multi-part.
+ tarantool> s = box.space.space55
+ ---
+ ...
+ tarantool> s:create_index('primary', {unique = true, parts = {1, 'NUM', 2, 'STR'}})
+ ---
+ ...
- :return: the tuples whose primary-key fields are equal to the passed
- field-values. If the number of passed field-values is less
- than the number of fields in the primary key, then only the
- passed field-values are compared, so ``select{1,2}`` will match
- a tuple whose primary key is ``{1,2,3}``.
- :rtype: tuple
+ .. function:: insert(tuple)
- :except: No such space; wrong type.
+ Insert a tuple into a space.
- Complexity Factors: Index size, Index type.
+ :param space_object space-object:
+ :param lua-table,box.tuple tuple: tuple to be inserted.
+ :return: the inserted tuple
+ :rtype: tuple
- .. code-block:: lua
+ Possible errors: If a tuple with the same unique-key value already exists,
+ returns :errcode:`ER_TUPLE_FOUND`.
- tarantool> s = box.schema.space.create('tmp', {temporary=true})
- ---
- ...
- tarantool> s:create_index('primary',{parts = {1,'NUM', 2, 'STR'}})
- ---
- ...
- tarantool> s:insert{1,'A'}
- ---
- - [1, 'A']
- ...
- tarantool> s:insert{1,'B'}
- ---
- - [1, 'B']
- ...
- tarantool> s:insert{1,'C'}
- ---
- - [1, 'C']
- ...
- tarantool> s:insert{2,'D'}
- ---
- - [2, 'D']
- ...
- tarantool> -- must equal both primary-key fields
- tarantool> s:select{1,'B'}
- ---
- - - [1, 'B']
- ...
- tarantool> -- must equal only one primary-key field
- tarantool> s:select{1}
- ---
- - - [1, 'A']
- - [1, 'B']
- - [1, 'C']
- ...
- tarantool> -- must equal 0 fields, so returns all tuples
- tarantool> s:select{}
- ---
- - - [1, 'A']
- - [1, 'B']
- - [1, 'C']
- - [2, 'D']
- ...
+ .. code-block:: lua
- For examples of complex ``select`` requests, where one can specify which index to
- search and what condition to use (for example "greater than" instead of
- "equal to") and how many tuples to return, see the later section
- ``box.space.space-name[.index.index-name]:select``.
+ box.space.tester:insert{5000,'tuple number five thousand'}
-.. function:: box.space.space-name:get{field-value [, field-value ...]}
+ .. function:: select(key)
- Search for a tuple in the given space.
+ Search for a tuple or a set of tuples in the given space.
- :param userdata space-name:
- :param lua-value field-value(s): values to be matched against the index
+ :param space_object space-object:
+ :param lua-table,scalar key: key to be matched against the index
key, which may be multi-part.
- :return: the selected tuple.
- :rtype: tuple
-
- :except: If space-name does not exist.
-
- Complexity Factors: Index size, Index type,
- Number of indexes accessed, WAL settings.
-
- .. code-block:: lua
-
- tarantool> box.space.tester:get{1}
-
-.. function:: box.space.space-name:drop()
-
- Drop a space.
-
- :return: nil
- :except: If space-name does not exist.
-
- Complexity Factors: Index size, Index type,
- Number of indexes accessed, WAL settings.
-
- .. code-block:: lua
-
- tarantool> box.space.space_that_does_not_exist:drop()
-
-.. function:: box.space.space-name:rename(space-name)
-
- Rename a space.
-
- :param string space-name: new name for space.
-
- :return: nil
- :except: If space-name does not exist.
-
- .. code-block:: lua
-
- tarantool> box.space.space55:rename('space56')
- ---
- ...
- tarantool> box.space.space56:rename('space55')
- ---
- ...
-
-.. function:: box.space.space-name:replace{field-value [, field-value ...]}
- box.space.space-name:put{field-value [, field-value ...]}
-
- Insert a tuple into a space. If a tuple with the same primary key already
- exists, ``box.space...:replace()`` replaces the existing tuple with a new
- one. The syntax variants ``box.space...:replace()`` and
- ``box.space...:put()`` have the same effect; the latter is sometimes used
- to show that the effect is the converse of ``box.space...:get()``.
-
- :param userdata space-name:
- :param lua-value field-value(s): fields of the new tuple.
-
- :return: the inserted tuple.
- :rtype: tuple
-
- :except: If a different tuple with the same unique-key
- value already exists, returns ``ER_TUPLE_FOUND``.
- (This would only happen if there was a secondary
- index. By default secondary indexes are unique.)
-
- Complexity Factors: Index size, Index type,
- Number of indexes accessed, WAL settings.
-
- .. code-block:: lua
-
- tarantool> box.space.tester:replace{5000, 'New value'}
-
-.. function:: box.space.space-name:update(key, {{operator, field_no, value}, ...})
-
- Update a tuple.
-
- The ``update`` function supports operations on fields — assignment,
- arithmetic (if the field is unsigned numeric), cutting and pasting
- fragments of a field, deleting or inserting a field. Multiple
- operations can be combined in a single update request, and in this
- case they are performed atomically and sequentially. Each operation
- requires specification of a field number. When multiple operations
- are present, the field number for each operation is assumed to be
- relative to the most recent state of the tuple, that is, as if all
- previous operations in a multi-operation update have already been
- applied. In other words, it is always safe to merge multiple update
- invocations into a single invocation, with no change in semantics.
-
- :param userdata space-name:
- :param lua-value key: primary-key field values, must be passed as a Lua
- table if key is multi-part
- :param table {operator, field_no, value}: a group of arguments for each
- operation, indicating what the operation is, what field the
- operation will apply to, and what value will be applied. For
- some operations the field number can be -1, meaning the last
- field in the tuple. Possible operators are: “+†for addition,
- “-†for subtraction, “&†for bitwise AND, “|†for bitwise OR,
- “^†for bitwise exclusive OR (XOR), “:†for string splice, “!â€
- for insert, “#†for delete. Thus in the instruction
- ``s:update(44, {{'+',1,55},{'=',3,'x'}})`` the primary-key
- value is 44, the operators are '+' and '=' meaning "add a value
- to a field and then assign a value to a field", the first
- affected field is field 1 and the value which will be added to
- it is 55, the second affected field is field 3 and the value
- which will be assigned to it is 'x'.
-
- :return: the updated tuple.
- :rtype: tuple
-
- :except: it is illegal to modify a primary-key field.
-
- Complexity Factors: Index size, Index type, number of indexes accessed, WAL
- settings.
-
- .. code-block:: lua
-
- -- Assume that the initial state of the database is ...
- -- tester has one tuple set and one primary key whose type is 'NUM'.
- -- There is one tuple, with field[1] = 999 and field[2] = 'A'.
-
- -- In the following update ...
- -- The first argument is tester, that is, the affected space is tester
- -- The second argument is 999, that is, the affected tuple is identified by
- -- primary key value = 999
- -- The third argument is '=', that is, there is one operation, assignment
- -- to a field
- -- The fourth argument is 2, that is, the affected field is field[2]
- -- The fifth argument is 'B', that is, field[2] contents change to 'B'
- -- Therefore, after the following update, field[1] = 999 and field[2] = 'B'.
- box.space.tester:update(999, {{'=', 2, 'B'}})
-
- -- In the following update, the arguments are the same, except that ...
- -- the key is passed as a Lua table (inside braces). This is unnecessary
- -- when the primary key has only one field, but would be necessary if the
- -- primary key had more than one field.
- -- Therefore, after the following update, field[1] = 999 and field[2] = 'B'
- -- (no change).
- box.space.tester:update({999}, {{'=', 2, 'B'}})
-
- -- In the following update, the arguments are the same, except that ...
- -- The fourth argument is 3, that is, the affected field is field[3].
- -- It is okay that, until now, field[3] has not existed. It gets added.
- -- Therefore, after the following update, field[1] = 999, field[2] = 'B',
- -- field[3] = 1.
- box.space.tester:update({999}, {{'=', 3, 1}})
-
- -- In the following update, the arguments are the same, except that ...
- -- The third argument is '+', that is, the operation is addition rather
- -- than assignment.
- -- Since field[3] previously contained 1, this means we're adding 1 to 1.
- -- Therefore, after the following update, field[1] = 999, field[2] = 'B',
- -- field[3] = 2.
- box.space.tester:update({999}, {{'+', 3, 1}})
-
- -- In the following update ...
- -- The idea is to modify two fields at once.
- -- The formats are '|' and '=', that is, there are two operations, OR and
- -- assignment.
- -- The fourth and fifth arguments mean that field[3] gets ORed with 1.
- -- The seventh and eighth arguments mean that field[2] gets assigned 'C'.
- -- Therefore, after the following update, field[1] = 999, field[2] = 'C',
- -- field[3] = 3.
- box.space.tester:update({999}, {{'|', 3, 1}, {'=', 2, 'C'}})
-
- -- In the following update ...
- -- The idea is to delete field[2], then subtract 3 from field[3], but ...
- -- after the delete, there is a renumbering -- so field[3] becomes field[2]
- -- before we subtract 3 from it, and that's why the seventh argument is 2 not 3.
- -- Therefore, after the following update, field[1] = 999, field[2] = 0.
- box.space.tester:update({999}, {{'-- ', 2, 1}, {'-', 2, 3}})
-
- -- In the following update ...
- -- We're making a long string so that splice will work in the next example.
- -- Therefore, after the following update, field[1] = 999, field[2] = 'XYZ'.
- box.space.tester:update({999}, {{'=', 2, 'XYZ'}})
-
- -- In the following update ...
- -- The third argument is ':', that is, this is the example of splice.
- -- The fourth argument is 2 because the change will occur in field[2].
- -- The fifth argument is 2 because deletion will begin with the second byte.
- -- The sixth argument is 1 because the number of bytes to delete is 1.
- -- The seventh argument is '!!' because '!!' is to be added at this position.
- -- Therefore, after the following update, field[1] = 999, field[2] = 'X!!Z'.
- box.space.tester:update({999}, {{':', 2, 2, 1, '!!'}})
-
-.. function:: box.space.space-name:delete{field-value [, field-value ...]}
-
- Delete a tuple identified by a primary key.
-
- :param userdata space-name:
- :param lua-value field-value(s): values to match against keys
- in the primary index.
-
- :return: the deleted tuple
- :rtype: tuple
-
- Complexity Factors: Index size, Index type
-
- .. code-block:: lua
-
- tarantool> box.space.tester:delete(0)
- ---
- - [0, 'My first tuple']
- ...
- tarantool> box.space.tester:delete(0)
- ---
- ...
- tarantool> box.space.tester:delete('a')
- ---
- - error: 'Supplied key type of part 0 does not match index part type:
- expected NUM'
- ...
-.. data:: space-name.id
+ :return: the tuples whose primary-key fields are equal to the passed
+ field-values. If the number of passed field-values is less
+ than the number of fields in the primary key, then only the
+ passed field-values are compared, so ``select{1,2}`` will match
+ a tuple whose primary key is ``{1,2,3}``.
+ :rtype: tuple
+
+ Possible errors: No such space; wrong type.
- Ordinal space number. Spaces can be referenced by either name or
- number. Thus, if space 'tester' has id = 800, then
- ``box.space.tester:insert{0}`` and ``box.space[800]:insert{0}``
- are equivalent requests.
+ Complexity Factors: Index size, Index type.
- :rtype: number
+ .. code-block:: lua
-.. data:: space-name.enabled
+ tarantool> s = box.schema.space.create('tmp', {temporary=true})
+ ---
+ ...
+ tarantool> s:create_index('primary',{parts = {1,'NUM', 2, 'STR'}})
+ ---
+ ...
+ tarantool> s:insert{1,'A'}
+ ---
+ - [1, 'A']
+ ...
+ tarantool> s:insert{1,'B'}
+ ---
+ - [1, 'B']
+ ...
+ tarantool> s:insert{1,'C'}
+ ---
+ - [1, 'C']
+ ...
+ tarantool> s:insert{2,'D'}
+ ---
+ - [2, 'D']
+ ...
+ tarantool> -- must equal both primary-key fields
+ tarantool> s:select{1,'B'}
+ ---
+ - - [1, 'B']
+ ...
+ tarantool> -- must equal only one primary-key field
+ tarantool> s:select{1}
+ ---
+ - - [1, 'A']
+ - [1, 'B']
+ - [1, 'C']
+ ...
+ tarantool> -- must equal 0 fields, so returns all tuples
+ tarantool> s:select{}
+ ---
+ - - [1, 'A']
+ - [1, 'B']
+ - [1, 'C']
+ - [2, 'D']
+ ...
- Whether or not this space is enabled.
- The value is false if there is no index.
+ For examples of complex ``select`` requests, where one can specify which index to
+ search and what condition to use (for example "greater than" instead of
+ "equal to") and how many tuples to return, see the later section
+ ``box.space.space-name[.index.index-name]:select``.
- :rtype: boolean
+ .. function:: get(key)
-.. data:: space-name.field_count
+ Search for a tuple in the given space.
- The required field count for all tuples in this space. The field_count
- can be set initially with
- ``box.schema.space.create... field_count = new-field-count-value ...``.
- The default value is 0, which means there is no required field count.
+ :param space_object space-object:
+ :param lua-table,scalar key: key to be matched against the index
+ key, which may be multi-part.
+ :return: the selected tuple.
+ :rtype: tuple
+
+ Possible errors: If space-name does not exist.
+
+ Complexity Factors: Index size, Index type,
+ Number of indexes accessed, WAL settings.
+
+ .. code-block:: lua
+
+ tarantool> box.space.tester:get{1}
+
+ .. function:: drop()
+
+ Drop a space.
+
+ :param space_object space-object:
+
+ :return: nil
+
+ Possible errors: If space-name does not exist.
- :rtype: number
+ Complexity Factors: Index size, Index type,
+ Number of indexes accessed, WAL settings.
-.. data:: space-name.index[]
+ .. code-block:: lua
+
+ tarantool> box.space.space_that_does_not_exist:drop()
+
+ .. function:: rename(space-name)
+
+ Rename a space.
+
+ :param space_object space-object:
+ :param string space-name: new name for space.
- A container for all defined indexes. An index is a Lua object of type
- :mod:`box.index` with methods to search tuples and iterate over them in
- predefined order.
+ :return: nil
- :rtype: table
+ Possible errors: ``space-name`` does not exist.
+
+ .. code-block:: lua
+
+ tarantool> box.space.space55:rename('space56')
+ ---
+ ...
+ tarantool> box.space.space56:rename('space55')
+ ---
+ ...
+
+ .. function:: replace(tuple)
+ put(tuple)
+
+ Insert a tuple into a space. If a tuple with the same primary key already
+ exists, ``box.space...:replace()`` replaces the existing tuple with a new
+ one. The syntax variants ``box.space...:replace()`` and
+ ``box.space...:put()`` have the same effect; the latter is sometimes used
+ to show that the effect is the converse of ``box.space...:get()``.
+
+ :param space_object space-object:
+ :param lua-table,box.tuple tuple: tuple to be inserted.
+
+ :return: the inserted tuple.
+ :rtype: tuple
+
+ Possible errors: If a different tuple with the same unique-key
+ value already exists, returns :errcode:`ER_TUPLE_FOUND`. (This
+ would only happen if there was a secondary index. By default
+ secondary indexes are unique)
+
+ Complexity Factors: Index size, Index type,
+ Number of indexes accessed, WAL settings.
- .. code-block: lua
+ .. code-block:: lua
- tarantool> box.space.tester.id
- ---
- - 512
- ...
- tarantool> box.space.tester.field_count
- ---
- - 0
- ...
- tarantool> box.space.tester.index.primary.type
- ---
- - TREE
- ...
+ tarantool> box.space.tester:replace{5000, 'New value'}
-.. function:: box.space.space-name:len()
+ .. function:: update(key, {{operator, field_no, value}, ...})
- .. NOTE::
+ Update a tuple.
- The ``len()`` function is only applicable for the memtx storage engine.
+ The ``update`` function supports operations on fields — assignment,
+ arithmetic (if the field is unsigned numeric), cutting and pasting
+ fragments of a field, deleting or inserting a field. Multiple
+ operations can be combined in a single update request, and in this
+ case they are performed atomically and sequentially. Each operation
+ requires specification of a field number. When multiple operations
+ are present, the field number for each operation is assumed to be
+ relative to the most recent state of the tuple, that is, as if all
+ previous operations in a multi-operation update have already been
+ applied. In other words, it is always safe to merge multiple update
+ invocations into a single invocation, with no change in semantics.
- :return: Number of tuples in the space.
+ Possible operators are:
- .. code-block:: lua
+ * '+' for addition
+ * '-' for substraction
+ * '&' for bitwise AND
+ * '|' for bitwise OR
+ * '^' for butwise :abbr:`XOR(exclusive OR)`
+ * ':' for string splice
+ * '!' for insert
+ * '#' for delete
- tarantool> box.space.tester:len()
- ---
- - 2
- ...
+ :param space_object space-object:
+ :param lua-value key: primary-key field values, must be passed as a Lua
+ table if key is multi-part
+ :param table {operator, field_no, value}: a group of arguments for each
+ operation, indicating what the operation is, what field the
+ operation will apply to, and what value will be applied. For
+ some operations the field number can be -1, meaning the last
+ field in the tuple. Thus in the instruction
-.. function:: box.space.space-name:truncate()
+ :return: the updated tuple.
+ :rtype: tuple
+
+ Possible errors: it is illegal to modify a primary-key field.
+
+ Complexity Factors: Index size, Index type, number of indexes accessed, WAL
+ settings.
+
+ .. code-block:: lua
+
+ s:update(44, {{'+',1,55},{'=',3,'x'}})
+
+ the primary-key value is 44, the operators are '+' and '=' meaning
+ "add a value to a field and then assign a value to a field", the first
+ affected field is field 1 and the value which will be added to it is
+ 55, the second affected field is field 3 and the value which will be
+ assigned to it is 'x'.
+
+ .. code-block:: lua
+
+ -- Assume that the initial state of the database is ...
+ -- tester has one tuple set and one primary key whose type is 'NUM'.
+ -- There is one tuple, with field[1] = 999 and field[2] = 'A'.
+
+ -- In the following update ...
+ -- The first argument is tester, that is, the affected space is tester
+ -- The second argument is 999, that is, the affected tuple is identified by
+ -- primary key value = 999
+ -- The third argument is '=', that is, there is one operation, assignment
+ -- to a field
+ -- The fourth argument is 2, that is, the affected field is field[2]
+ -- The fifth argument is 'B', that is, field[2] contents change to 'B'
+ -- Therefore, after the following update, field[1] = 999 and field[2] = 'B'.
+ box.space.tester:update(999, {{'=', 2, 'B'}})
+
+ -- In the following update, the arguments are the same, except that ...
+ -- the key is passed as a Lua table (inside braces). This is unnecessary
+ -- when the primary key has only one field, but would be necessary if the
+ -- primary key had more than one field.
+ -- Therefore, after the following update, field[1] = 999 and field[2] = 'B'
+ -- (no change).
+ box.space.tester:update({999}, {{'=', 2, 'B'}})
+
+ -- In the following update, the arguments are the same, except that ...
+ -- The fourth argument is 3, that is, the affected field is field[3].
+ -- It is okay that, until now, field[3] has not existed. It gets added.
+ -- Therefore, after the following update, field[1] = 999, field[2] = 'B',
+ -- field[3] = 1.
+ box.space.tester:update({999}, {{'=', 3, 1}})
+
+ -- In the following update, the arguments are the same, except that ...
+ -- The third argument is '+', that is, the operation is addition rather
+ -- than assignment.
+ -- Since field[3] previously contained 1, this means we're adding 1 to 1.
+ -- Therefore, after the following update, field[1] = 999, field[2] = 'B',
+ -- field[3] = 2.
+ box.space.tester:update({999}, {{'+', 3, 1}})
+
+ -- In the following update ...
+ -- The idea is to modify two fields at once.
+ -- The formats are '|' and '=', that is, there are two operations, OR and
+ -- assignment.
+ -- The fourth and fifth arguments mean that field[3] gets ORed with 1.
+ -- The seventh and eighth arguments mean that field[2] gets assigned 'C'.
+ -- Therefore, after the following update, field[1] = 999, field[2] = 'C',
+ -- field[3] = 3.
+ box.space.tester:update({999}, {{'|', 3, 1}, {'=', 2, 'C'}})
+
+ -- In the following update ...
+ -- The idea is to delete field[2], then subtract 3 from field[3], but ...
+ -- after the delete, there is a renumbering -- so field[3] becomes field[2]
+ -- before we subtract 3 from it, and that's why the seventh argument is 2 not 3.
+ -- Therefore, after the following update, field[1] = 999, field[2] = 0.
+ box.space.tester:update({999}, {{'-- ', 2, 1}, {'-', 2, 3}})
+
+ -- In the following update ...
+ -- We're making a long string so that splice will work in the next example.
+ -- Therefore, after the following update, field[1] = 999, field[2] = 'XYZ'.
+ box.space.tester:update({999}, {{'=', 2, 'XYZ'}})
+
+ -- In the following update ...
+ -- The third argument is ':', that is, this is the example of splice.
+ -- The fourth argument is 2 because the change will occur in field[2].
+ -- The fifth argument is 2 because deletion will begin with the second byte.
+ -- The sixth argument is 1 because the number of bytes to delete is 1.
+ -- The seventh argument is '!!' because '!!' is to be added at this position.
+ -- Therefore, after the following update, field[1] = 999, field[2] = 'X!!Z'.
+ box.space.tester:update({999}, {{':', 2, 2, 1, '!!'}})
+
+ .. function:: delete(key)
- Deletes all tuples.
+ Delete a tuple identified by a primary key.
+
+ :param space_object space-object:
+ :param lua-table,scalar key: key to be matched against the index
+ key, which may be multi-part.
+
+ :return: the deleted tuple
+ :rtype: tuple
- Complexity Factors: Index size, Index type, Number of tuples accessed.
+ Complexity Factors: Index size, Index type
- :return: nil
+ .. code-block:: lua
+
+ tarantool> box.space.tester:delete(0)
+ ---
+ - [0, 'My first tuple']
+ ...
+ tarantool> box.space.tester:delete(0)
+ ---
+ ...
+ tarantool> box.space.tester:delete('a')
+ ---
+ - error: 'Supplied key type of part 0 does not match index part type:
+ expected NUM'
+ ...
+
+ .. data:: id
+
+ Ordinal space number. Spaces can be referenced by either name or
+ number. Thus, if space 'tester' has id = 800, then
+ ``box.space.tester:insert{0}`` and ``box.space[800]:insert{0}``
+ are equivalent requests.
+
+ :rtype: number
+
+ .. data:: enabled
+
+ Whether or not this space is enabled.
+ The value is false if there is no index.
+
+ :rtype: boolean
+
+ .. data:: field_count
+
+ The required field count for all tuples in this space. The field_count
+ can be set initially with
+ ``box.schema.space.create... field_count = new-field-count-value ...``.
+ The default value is 0, which means there is no required field count.
+
+ :rtype: number
+
+ .. data:: index
+
+ A container for all defined indexes. An index is a Lua object of type
+ :mod:`box.index` with methods to search tuples and iterate over them in
+ predefined order.
+
+ :rtype: table
- .. code-block:: lua
+ .. code-block: lua
+
+ tarantool> box.space.tester.id
+ ---
+ - 512
+ ...
+ tarantool> box.space.tester.field_count
+ ---
+ - 0
+ ...
+ tarantool> box.space.tester.index.primary.type
+ ---
+ - TREE
+ ...
+
+ .. function:: len()
+
+ .. NOTE::
+
+ The ``len()`` function is only applicable for the memtx storage engine.
+
+ :return: Number of tuples in the space.
+
+ .. code-block:: lua
- tarantool> box.space.tester:truncate()
- ---
- ...
- tarantool> box.space.tester:len()
- ---
- - 0
- ...
+ tarantool> box.space.tester:len()
+ ---
+ - 2
+ ...
-.. function:: box.space.space-name:inc{field-value [, field-value ...]}
+ .. function:: truncate()
- Increments a counter in a tuple whose primary key matches the
- ``field-value(s)``. The field following the primary-key fields
- will be the counter. If there is no tuple matching the
- ``field-value(s)``, a new one is inserted with initial counter
- value set to 1.
+ Deletes all tuples.
- :param userdata space-name:
- :param lua-value field-value(s): values which must match the primary key.
- :return: the new counter value
- :rtype: number
+ Complexity Factors: Index size, Index type, Number of tuples accessed.
- Complexity Factors: Index size, Index type, WAL settings.
+ :return: nil
- .. code-block:: lua
+ .. code-block:: lua
- tarantool> s = box.schema.space.create('forty_second_space')
- ---
- ...
- tarantool> s:create_index('primary', {unique = true, parts = {1, 'NUM', 2, 'STR'}})
- ---
- ...
- tarantool> box.space.forty_second_space:inc{1,'a'}
- ---
- - 1
- ...
- tarantool> box.space.forty_second_space:inc{1,'a'}
- ---
- - 2
- ...
+ tarantool> box.space.tester:truncate()
+ ---
+ ...
+ tarantool> box.space.tester:len()
+ ---
+ - 0
+ ...
-.. function:: box.space.space-name:dec{field-value [, field-value ...]}
+ .. function:: inc(key)
- Decrements a counter in a tuple whose primary key matches the
- ``field-value(s)``. The field following the primary-key fields
- will be the counter. If there is no tuple matching the
- ``field-value(s)``, a new one is not inserted. If the counter value drops
- to zero, the tuple is deleted.
+ Increments a counter in a tuple whose primary key matches the
+ ``key``. The field following the primary-key fields
+ will be the counter. If there is no tuple matching the
+ ``field-value(s)``, a new one is inserted with initial counter
+ value set to 1.
- :param userdata space-name:
- :param lua-value field-value(s): values which must match the primary key.
- :return: the new counter value
- :rtype: number
+ :param space_object space-object:
+ :param lua-table,scalar key: key to be matched against the index
+ key, which may be multi-part.
+ :return: the new counter value
+ :rtype: number
- Complexity Factors: Index size, Index type, WAL settings.
+ Complexity Factors: Index size, Index type, WAL settings.
- .. code-block:: lua
+ .. code-block:: lua
- tarantool> s = box.schema.space.create('space19')
- ---
- ...
- tarantool> s:create_index('primary', {unique = true, parts = {1, 'NUM', 2, 'STR'}})
- ---
- ...
- tarantool> box.space.space19:insert{1,'a',1000}
- ---
- - [1, 'a', 1000]
- ...
- tarantool> box.space.space19:dec{1,'a'}
- ---
- - 999
- ...
- tarantool> box.space.space19:dec{1,'a'}
- ---
- - 998
- ...
-
-.. function:: box.space.space-name:auto_increment{field-value [, field-value ...]}
-
- Insert a new tuple using an auto-increment primary key. The space specified
- by space-name must have a NUM primary key index of type TREE. The
- primary-key field will be incremented before the insert.
-
- :param userdata space-name:
- :param lua-value field-value(s): values for the tuple's fields,
- other than the primary-key field.
-
- :return: the inserted tuple.
- :rtype: tuple
-
- Complexity Factors: Index size, Index type,
- Number of indexes accessed, WAL settings.
-
- :except: index has wrong type or primary-key indexed field is not a number.
-
- .. code-block:: lua
-
- tarantool> box.space.tester:auto_increment{'Fld#1', 'Fld#2'}
- ---
- - [1, 'Fld#1', 'Fld#2']
- ...
- tarantool> box.space.tester:auto_increment{'Fld#3'}
- ---
- - [2, 'Fld#3']
- ...
-
-.. function:: box.space.space-name:pairs()
-
- A helper function to prepare for iterating over all tuples in a space.
-
- :return: function which can be used in a for/end loop. Within the loop, a value is returned for each iteration.
- :rtype: function, tuple
-
- .. code-block:: lua
-
- tarantool> s = box.schema.space.create('space33')
- ---
- ...
- tarantool> -- index 'X' has default parts {1,'NUM'}
- tarantool> s:create_index('X', {})
- ---
- ...
- tarantool> s:insert{0,'Hello my '}; s:insert{1,'Lua world'}
- ---
- ...
- tarantool> tmp = ''; for k, v in s:pairs() do tmp = tmp .. v[2] end
- ---
- ...
- tarantool> tmp
- ---
- - Hello my Lua world
- ...
+ tarantool> s = box.schema.space.create('forty_second_space')
+ ---
+ ...
+ tarantool> s:create_index('primary', {unique = true, parts = {1, 'NUM', 2, 'STR'}})
+ ---
+ ...
+ tarantool> box.space.forty_second_space:inc{1,'a'}
+ ---
+ - 1
+ ...
+ tarantool> box.space.forty_second_space:inc{1,'a'}
+ ---
+ - 2
+ ...
+
+ .. function:: dec(key)
+
+ Decrements a counter in a tuple whose primary key matches the
+ ``field-value(s)``. The field following the primary-key fields
+ will be the counter. If there is no tuple matching the
+ ``field-value(s)``, a new one is not inserted. If the counter value drops
+ to zero, the tuple is deleted.
+
+ :param space_object space-object:
+ :param lua-table,scalar key: key to be matched against the index
+ key, which may be multi-part.
+ :return: the new counter value
+ :rtype: number
+
+ Complexity Factors: Index size, Index type, WAL settings.
+
+ .. code-block:: lua
+
+ tarantool> s = box.schema.space.create('space19')
+ ---
+ ...
+ tarantool> s:create_index('primary', {unique = true, parts = {1, 'NUM', 2, 'STR'}})
+ ---
+ ...
+ tarantool> box.space.space19:insert{1,'a',1000}
+ ---
+ - [1, 'a', 1000]
+ ...
+ tarantool> box.space.space19:dec{1,'a'}
+ ---
+ - 999
+ ...
+ tarantool> box.space.space19:dec{1,'a'}
+ ---
+ - 998
+ ...
+
+ .. function:: auto_increment(tuple)
+
+ Insert a new tuple using an auto-increment primary key. The space specified
+ by space-name must have a NUM primary key index of type TREE. The
+ primary-key field will be incremented before the insert.
+
+ :param space_object space-object:
+ :param lua-table,box.tuple tuple: tuple's fields, other than the primary-key field.
+
+ :return: the inserted tuple.
+ :rtype: tuple
+
+ Complexity Factors: Index size, Index type,
+ Number of indexes accessed, WAL settings.
+
+ Possible errors: index has wrong type or primary-key indexed field is not a number.
+
+ .. code-block:: lua
+
+ tarantool> box.space.tester:auto_increment{'Fld#1', 'Fld#2'}
+ ---
+ - [1, 'Fld#1', 'Fld#2']
+ ...
+ tarantool> box.space.tester:auto_increment{'Fld#3'}
+ ---
+ - [2, 'Fld#3']
+ ...
+
+ .. function:: pairs()
+
+ A helper function to prepare for iterating over all tuples in a space.
+
+ :return: function which can be used in a for/end loop. Within the loop, a value is returned for each iteration.
+ :rtype: function, tuple
+
+ .. code-block:: lua
+
+ tarantool> s = box.schema.space.create('space33')
+ ---
+ ...
+ tarantool> -- index 'X' has default parts {1,'NUM'}
+ tarantool> s:create_index('X', {})
+ ---
+ ...
+ tarantool> s:insert{0,'Hello my '}; s:insert{1,'Lua world'}
+ ---
+ ...
+ tarantool> tmp = ''; for k, v in s:pairs() do tmp = tmp .. v[2] end
+ ---
+ ...
+ tarantool> tmp
+ ---
+ - Hello my Lua world
+ ...
.. data:: _schema
--
GitLab