diff --git a/doc/code_snippets/README.md b/doc/code_snippets/README.md index c5d51490c6..23f5d9108c 100644 --- a/doc/code_snippets/README.md +++ b/doc/code_snippets/README.md @@ -27,19 +27,26 @@ To test all the examples, go to the `doc/code_snippets` folder and execute the ` .rocks/bin/luatest ``` -To run a specific example with tests, use the `luatest` command with the `-c` option, for example: +To test the examples from the specified directory, pass its relative path to the `luatest` command: + +```shell +.rocks/bin/luatest test/transactions +``` + +To test a specific example with the `stdout` output enabled, use the `luatest` command with the `-c` option, for example: ```shell .rocks/bin/luatest -c test/http_client/get_test.lua ``` -You can also run the `httpbin` service locally using Docker: +Note that the HTTP client samples (placed in `test/http_client`) use the `httpbin` service. +You can run `httpbin` locally using Docker to stabilize test results: ```shell docker run -p 80:80 kennethreitz/httpbin ``` -In this case, replace `https://httpbin.org` links with `http://127.0.0.1` to test the examples. +In this case, you need to replace `https://httpbin.org` links with `http://127.0.0.1`. ## Referencing code snippets diff --git a/doc/concepts/data_model/indexes.rst b/doc/concepts/data_model/indexes.rst index 32a6f2c4d2..8b65bf5781 100644 --- a/doc/concepts/data_model/indexes.rst +++ b/doc/concepts/data_model/indexes.rst @@ -52,11 +52,10 @@ while an ``‘integer’`` index contains *any* integer values. The default field type is ``'unsigned'`` and the default index type is TREE. Although ``'nil'`` is not a legal indexed field type, indexes may contain `nil` -:ref:`as a non-default option `. +:ref:`as a non-default option `. To learn more about field types, check the -:ref:`Field type details ` section and the more elaborate -:ref:`Details about index field types ` in the reference. +:ref:`Field type details ` section. .. container:: table @@ -92,7 +91,7 @@ To learn more about field types, check the - TREE, BITSET, or HASH * - ``'varbinary'`` - :ref:`varbinary ` - - TREE, HASH, or BITSET (since version 2.7) + - TREE, HASH, or BITSET (since version :doc:`2.7.1 `) * - ``'uuid'`` - :ref:`uuid ` - TREE or HASH @@ -153,7 +152,7 @@ We give an overview of index features in the following table: - \+ - \+ - * - :ref:`is_nullable ` + * - :ref:`is_nullable ` - \+ - \- - \- diff --git a/doc/concepts/data_model/value_store.rst b/doc/concepts/data_model/value_store.rst index a23c8cf93a..823931a68d 100644 --- a/doc/concepts/data_model/value_store.rst +++ b/doc/concepts/data_model/value_store.rst @@ -188,31 +188,43 @@ Example: ``nil``. .. _index-box_boolean: -**boolean**. A boolean is either ``true`` or ``false``. +**boolean** + +A boolean is either ``true`` or ``false``. + Example: ``true``. .. _index-box_integer: -**integer**. The Tarantool integer type is for integers between +**integer** + +The Tarantool integer type is for integers between -9223372036854775808 and 18446744073709551615, which is about 18 quintillion. This type corresponds to the number type in Lua and to the integer type in MsgPack. + Example: ``-2^63``. .. _index-box_unsigned: -**unsigned**. The Tarantool unsigned type is for integers between +**unsigned** + +The Tarantool unsigned type is for integers between 0 and 18446744073709551615. So it is a subset of integer. + Example: ``123456``. .. _index-box_double: -**double**. The double field type exists +**double** + +The double field type exists mainly to be equivalent to Tarantool/SQL's :ref:`DOUBLE data type `. In `msgpuck.h `_ (Tarantool's interface to MsgPack), the storage type is ``MP_DOUBLE`` and the size of the encoded value is always 9 bytes. In Lua, fields of the double type can only contain non-integer numeric values and cdata values with double floating-point numbers. + Examples: ``1.234``, ``-44``, ``1.447e+44``. To avoid using the wrong kind of values inadvertently, use @@ -222,6 +234,7 @@ For example, instead of use ``ffi = require('ffi') ...`` :samp:`{space_object}:insert`:code:`({ffi.cast('double',`:samp:`{value}`:code:`)})`. + Example: .. code-block:: tarantoolsession @@ -243,7 +256,9 @@ Tarantool/SQL does .. _index-box_number: -**number**. The Tarantool number field may have both +**number** + +The Tarantool number field may have both integer and floating-point values, although in Lua a ``number`` is a double-precision floating-point. @@ -262,15 +277,20 @@ In this case, the number will be stored as `cdata`_. .. _index-box_decimal: -**decimal**. The Tarantool decimal type is stored as a :ref:`MsgPack ext ` (Extension). +**decimal** + +The Tarantool decimal type is stored as a :ref:`MsgPack ext ` (Extension). Values with the decimal type are not floating-point values although they may contain decimal points. They are exact with up to 38 digits of precision. + Example: a value returned by a function in the :ref:`decimal ` module. .. _index-box_datetime: -**datetime**. Introduced in :tarantool-release:`2.10.0`. +**datetime** + +Introduced in :tarantool-release:`2.10.0`. The Tarantool ``datetime`` type facilitates operations with date and time, accounting for leap years or the varying number of days in a month. It is stored as a :ref:`MsgPack ext ` (Extension). @@ -280,7 +300,10 @@ For more information, see :doc:`Module datetime `_, a third-party library. @@ -289,7 +312,9 @@ For more information, see :doc:`Module datetime `. + Example: ``"\65 \66 \67"``. .. _index-box_uuid: -**uuid**. The Tarantool uuid type is used for +**uuid** + +The Tarantool uuid type is used for :ref:`Universally Unique Identifiers `. Since version :doc:`2.4.1 ` Tarantool stores ``uuid`` values as a :ref:`MsgPack ext ` (Extension). @@ -320,31 +351,44 @@ Example: ``64d22e4d-ac92-4a23-899a-e5934af5479``. .. _index-box_array: -**array**. An array is represented in Lua with ``{...}`` (`braces `_). +**array** + +An array is represented in Lua with ``{...}`` (`braces `_). Examples: lists of numbers representing points in geometric figures: ``{10, 11}``, ``{3, 5, 9, 10}``. -**table**. Lua tables with string keys are stored as MsgPack maps; +**table** + +Lua tables with string keys are stored as MsgPack maps; Lua tables with integer keys starting with 1 are stored as MsgPack arrays. Nils may not be used in Lua tables; the workaround is to use :ref:`box.NULL `. + Example: a ``box.space.tester:select()`` request will return a Lua table. -**tuple**. A tuple is a light reference to a MsgPack array stored in the database. +**tuple** + +A tuple is a light reference to a MsgPack array stored in the database. It is a special type (cdata) to avoid conversion to a Lua table on retrieval. A few functions may return tables with multiple tuples. For tuple examples, see :ref:`box.tuple `. .. _index-box_scalar: -**scalar**. Values in a scalar field can be boolean, integer, unsigned, double, +**scalar** + +Values in a scalar field can be boolean, integer, unsigned, double, number, decimal, string, uuid, or varbinary; but not array, map, or tuple. + Examples: ``true``, ``1``, ``'xxx'``. .. _index-box_any: -**any**. Values in a field of this type can be boolean, integer, unsigned, double, +**any** + +Values in a field of this type can be boolean, integer, unsigned, double, number, decimal, string, uuid, varbinary, array, map, or tuple. + Examples: ``true``, ``1``, ``'xxx'``, ``{box.NULL, 0}``. Examples of insert requests with different field types: diff --git a/doc/how-to/db/indexes.rst b/doc/how-to/db/indexes.rst index 3adadfc28b..f503902433 100644 --- a/doc/how-to/db/indexes.rst +++ b/doc/how-to/db/indexes.rst @@ -38,7 +38,7 @@ Be careful! Using ``select()`` for huge spaces hangs your instance. An index definition may also include identifiers of tuple fields and their expected **types**. See allowed indexed field types in section -:ref:`Details about indexed field types `: +:ref:`Details about indexed field types `: .. cssclass:: highlight .. parsed-literal:: diff --git a/doc/overview.rst b/doc/overview.rst index ba968e0888..a6fbb9051e 100644 --- a/doc/overview.rst +++ b/doc/overview.rst @@ -22,7 +22,7 @@ Here are some of Tarantool's key characteristics: * **Advanced indexing**: :ref:`composite indexes `, :ref:`locale support `, - indexing by :ref:`nested fields and arrays ` + indexing by :ref:`nested fields and arrays ` * **Compute close to data**: :ref:`Lua server ` and Just-In-Time compiler on board diff --git a/doc/reference/reference_lua/box_index/parts.rst b/doc/reference/reference_lua/box_index/parts.rst index 0992db35bd..ee531eae2e 100644 --- a/doc/reference/reference_lua/box_index/parts.rst +++ b/doc/reference/reference_lua/box_index/parts.rst @@ -9,7 +9,7 @@ index_object:parts() .. data:: parts An array describing the index fields. To learn more about the index field - types, refer to :ref:`this table `. + types, refer to :ref:`this table `. :rtype: table diff --git a/doc/reference/reference_lua/box_space/create_index.rst b/doc/reference/reference_lua/box_space/create_index.rst index 19c6861be0..4b9c87b250 100644 --- a/doc/reference/reference_lua/box_space/create_index.rst +++ b/doc/reference/reference_lua/box_space/create_index.rst @@ -1,22 +1,12 @@ +.. _box_space-create_index: space_object:create_index() =========================== -On this page: - -* :ref:`create_index() description ` -* :ref:`Details about index field types ` -* :ref:`Allowing null for an indexed key ` -* :ref:`Creating an index using field names instead of field numbers ` -* :ref:`Creating an index using the path option for map fields (JSON-path indexes) ` -* :ref:`Creating a multikey index using the path option with [*] ` -* :ref:`Creating a functional index ` .. class:: space_object - .. _box_space-create_index: - - .. method:: create_index(index-name [, options ]) + .. method:: create_index(index-name [, index_opts ]) Create an :ref:`index `. @@ -28,8 +18,7 @@ On this page: ` :param string index_name: name of index, which should conform to the :ref:`rules for object names ` - :param table options: see "Options for space_object:create_index()", - below + :param table index_opts: index options (see :ref:`index_opts `) :return: index object :rtype: index_object @@ -47,101 +36,6 @@ On this page: such as a duplicate key in a unique index, building or rebuilding such index will fail. - .. _box_space-create_index-options: - - **Options for space_object:create_index()** - - .. container:: table - - .. list-table:: - :widths: 25 30 30 15 - :header-rows: 1 - - * - Name - - Effect - - Type - - Default - * - type - - type of index - - string ('HASH' or 'TREE' or 'BITSET' or 'RTREE'). - Note that vinyl only supports 'TREE'. - - 'TREE' - * - id - - unique identifier - - number - - last index's id + 1 - * - unique - - index is unique - - boolean - - true - * - if_not_exists - - no error if duplicate name - - boolean - - false - * - parts - - field numbers + types - - {field_no, 'unsigned' or 'string' or 'integer' or 'number' or 'double' or - 'decimal' or 'boolean' or 'varbinary' or 'uuid' or 'array' or 'scalar', - and optional collation or is_nullable value or path} - - {1, 'unsigned'} - * - dimension - - affects :ref:`RTREE ` only - - number - - 2 - * - distance - - affects RTREE only - - string ('euclid' or 'manhattan') - - 'euclid' - * - bloom_fpr - - affects vinyl only - - number - - vinyl_bloom_fpr - * - page_size - - affects vinyl only - - number - - vinyl_page_size - * - range_size - - affects vinyl only - - number - - vinyl_range_size - * - run_count_per_level - - affects vinyl only - - number - - vinyl_run_count_per_level - * - run_size_ratio - - affects vinyl only - - number - - vinyl_run_size_ratio - * - sequence - - see section regarding - :ref:`specifying a sequence in create_index() ` - - string or number - - not present - * - func - - :ref:`functional index ` - - string - - not present - * - hint (since version :doc:`2.6.1 `) - - affects TREE only. - ``true`` makes an index work faster, ``false`` -- index size is reduced by half - - boolean - - true - - The options in the above chart are also applicable for - :doc:`/reference/reference_lua/box_index/alter`. - - - **Note on storage engine:** vinyl has extra options which by default are - based on configuration parameters - :ref:`vinyl_bloom_fpr `, - :ref:`vinyl_page_size `, - :ref:`vinyl_range_size `, - :ref:`vinyl_run_count_per_level `, and - :ref:`vinyl_run_size_ratio ` - -- see the description of those parameters. - The current values can be seen by selecting from - :doc:`/reference/reference_lua/box_space/_index`. - **Example:** .. code-block:: tarantoolsession @@ -168,6 +62,75 @@ On this page: name: primary ... + + + +.. _index_opts_object: + +index_opts +---------- + + +.. class:: index_opts + + Index options. + These options can be passed to the :ref:`space_object.create_index() ` method. + + .. NOTE:: + + These options are also applicable to :doc:`/reference/reference_lua/box_index/alter`. + + .. _index_opts_type: + + .. data:: type + + The index type. + To learn more, see the :ref:`Index types ` section. + + | Type: string + | Default: ``TREE`` + | Possible values: ``TREE``, ``HASH``, ``RTREE``, ``BITSET`` + + + .. _index_opts_id: + + .. data:: id + + As with spaces, you should specify the index name and let Tarantool come up with a unique numeric identifier (index ID). + + | Type: number + | Default: last index's ID + 1 + + + .. _index_opts_unique: + + .. data:: unique + + An index may be unique, that is, you can declare that it would be illegal to have the same key value twice. + + | Type: boolean + | Default: ``true`` + + + .. _index_opts_if_not_exists: + + .. data:: if_not_exists + + no error if duplicate name + + | Type: boolean + | Default: ``false`` + + + .. _index_opts_parts: + + .. data:: parts + + Specify key parts. + + | Type: table of :ref:`key_part ` values + | Default: ``{1, ‘unsigned’}`` + .. _index_parts_declaration_note: .. NOTE:: @@ -196,227 +159,259 @@ On this page: my_space:create_index('one_part_idx', {parts = {1, 'unsigned', is_nullable=true}}) -.. _details_about_index_field_types: + .. _index_opts_dimension: -.. _box_space-index_field_types: + .. data:: dimension -Details about index field types -------------------------------- + The RTREE index dimension. -Index field types differ depending on what values are allowed, -and what index types are allowed. + | Type: number + | Default: 2 -.. container:: table - .. list-table:: - :widths: 23 42 20 15 - :header-rows: 1 + .. _index_opts_distance: - * - Index field type - - What can be in it - - Where it is legal - - Examples + .. data:: distance - * - ``unsigned`` - - unsigned integers between 0 and 18446744073709551615, - about 18 quintillion. May also be called - 'uint' or 'num', but 'num' is deprecated - - memtx TREE or HASH indexes; + The RTREE index distance type. - vinyl TREE indexes - - 123456 + | Type: string + | Default: ``euclid`` + | Possible values: ``euclid``, ``manhattan`` - * - ``string`` - - any set of octets, up to the :ref:`maximum length - `. May also be called 'str'. - A string may have a :ref:`collation ` - - memtx TREE or HASH or BITSET indexes; - vinyl TREE indexes - - 'A B C' + .. _index_opts_sequence: - '\\65 \\66 \\67' + .. data:: sequence - * - ``varbinary`` - - any set of octets, up to the :ref:`maximum length - `. A varbinary byte sequence - does not have a :ref:`collation ` - because its contents are not UTF-8 characters - - memtx TREE, HASH or BITSET (since version :doc:`2.7.1 `) indexes; + Create a generator for indexes using a sequence object. + Learn more from :ref:`specifying a sequence in create_index() `. - vinyl TREE indexes - - '\\65 \\66 \\67' + | Type: string or number - * - ``integer`` - - integers between -9223372036854775808 and 18446744073709551615. - May also be called 'int' - - memtx TREE or HASH indexes; - vinyl TREE indexes - - -2^63 + .. _index_opts_func: - * - ``number`` - - integers between -9223372036854775808 and 18446744073709551615, - single-precision floating point numbers, or double-precision - floating point numbers, or exact numbers - - memtx TREE or HASH indexes; + .. data:: func - vinyl TREE indexes - - 1.234 + Specify the identifier of the :ref:`functional index ` function. - -44 + | Type: string - 1.447e+44 - * - ``double`` - - double-precision floating point numbers - - memtx TREE or HASH indexes; + .. _index_opts_hint: - vinyl TREE indexes - - 1.234 + .. data:: hint - * - ``boolean`` - - true or false - - memtx TREE or HASH indexes; + **Since:** :doc:`2.6.1 ` - vinyl TREE indexes - - false + Manage hint optimization for the TREE index. + ``true`` makes an index work faster, ``false`` – the index size is reduced by half. - * - ``decimal`` - - exact number returned from a function in the - :ref:`decimal ` module - - memtx TREE or HASH indexes; + | Type: boolean + | Default: ``true`` - vinyl TREE indexes - - decimal.new(1.2) - - * - ``datetime`` (since :doc:`2.10.0 `) - - object returned from a function in the - :doc:`datetime ` module - - memtx and vinyl TREE indexes - - datetime.new{year = 2002} - * - ``uuid`` (since :doc:`2.4.1 `) - - a 128-bit quantity sequence of lower-case hexadecimal digits, - representing Universally Unique Identifiers (UUID) - - memtx TREE or HASH indexes; + .. _index_opts_bloom_fpr: - vinyl TREE indexes - - uuid.fromstr('64d22e4d-ac92-4a23-899a-e59f34af5479') + .. data:: bloom_fpr - * - ``array`` - - array of numbers - - memtx :ref:`RTREE ` indexes - - {10, 11} + **Vinyl only** - {3, 5, 9, 10} + Bloom filter false positive rate. - * - ``scalar`` - - null (input with ``msgpack.NULL`` or ``yaml.NULL`` or ``json.NULL``), - booleans (true or false), or - integers between -9223372036854775808 and 18446744073709551615, or - single-precision floating point numbers, or - double-precision floating point numbers, or - exact numbers, or - strings, or - (varbinary) byte arrays, or - uuids. - When there is a mix of types, the key order is: null, - then booleans, then numbers, then strings, then byte arrays, - then uuids. - - memtx TREE or HASH indexes; + | Type: number + | Default: :ref:`vinyl_bloom_fpr ` - vinyl TREE indexes - - null - true + .. _index_opts_page_size: - -1 + .. data:: page_size - 1.234 + **Vinyl only** - '' + The size of a page used for read and write disk operations. - 'ру' + | Type: number + | Default: :ref:`vinyl_page_size ` - * - ``nil`` - - Additionally, `nil` is allowed with any index field type - if :ref:`is_nullable=true ` is specified - - - - + .. _index_opts_range_size: -.. _box_space-is_nullable: + .. data:: range_size -Allowing null for an indexed key --------------------------------- + **Vinyl only** -is_nullable parts option -~~~~~~~~~~~~~~~~~~~~~~~~ + The default maximum range size (in bytes) for a vinyl index. -If the index type is TREE, and the index is not the primary index, -then the ``parts={...}`` clause may include ``is_nullable=true`` or -``is_nullable=false`` (the default). + | Type: number + | Default: :ref:`vinyl_range_size ` -If ``is_nullable`` is true, then it is legal to insert ``nil`` or an equivalent -such as ``msgpack.NULL``. -It is also legal to insert nothing at all when using trailing nullable fields. -Within indexes, such null values are always treated as equal to other null -values, and are always treated as less than non-null values. -Nulls may appear multiple times even in a unique index. Example: -.. code-block:: lua + .. _index_opts_run_count_per_level: + + .. data:: run_count_per_level + + **Vinyl only** + + The maximum number of runs per level in the LSM tree. + + | Type: number + | Default: :ref:`vinyl_run_count_per_level ` + + + .. _index_opts_run_size_ratio: + + .. data:: run_size_ratio + + **Vinyl only** + + The ratio between the sizes of different levels in the LSM tree. + + | Type: number + | Default: :ref:`vinyl_run_size_ratio ` + + + + + +.. _key_part_object: + +key_part +-------- + +.. class:: key_part + + A descriptor of a single part in a multipart key. + See :ref:`parts `. - box.space.tester:create_index('I', {unique = true, parts = {{field = 2, type = 'number', is_nullable = true}}}) + .. _key_part_field: -.. WARNING:: + .. data:: field - It is legal to create multiple indexes for the same field with different - ``is_nullable`` values, or to call :doc:`/reference/reference_lua/box_space/format` - with a different ``is_nullable`` value from what is used for an index. - When there is a contradiction, the rule is: null is illegal unless - ``is_nullable=true`` for every index and for the space format. + The field name or number -exclude_null parts option -~~~~~~~~~~~~~~~~~~~~~~~~~ + | Type: string or number -Since version 2.8.2 an index part definition may include option ``exclude_null``, -which allows an index to skip tuples with null at this part. + .. _key_part_field_type: -By default, the option is set to ``false``. When ``exclude_null`` is turned on, -the ``is_nullable=true`` option will be set automatically. -It can't be used for the primary key. This option can be changed dynamically: -in this case the index is rebuilt. + .. data:: type -Such indexes do not store filtered tuples at all, so indexing can be done faster. + The field type -``exclude_null`` and ``is_nullable`` are connected, so this table describes -the result of combining them: + .. _key_part_collation: -.. container:: table stackcolumn + .. data:: collation - .. rst-class:: left-align-column-1 - .. rst-class:: left-align-column-2 + The field :ref:`collation ` - .. list-table:: + .. _key_part_is_nullable: - * - **exclude_null/is_nullable** - - **false** - - **true** + .. data:: is_nullable - * - **false** - - ok - - ok + If is_nullable is ``true``, then it is legal to insert ``nil`` or an equivalent such as ``msgpack.NULL``. - * - **true** - - not allowed - - ok + If the index type is TREE, and the index is not the primary index, + then the ``parts={...}`` clause may include ``is_nullable=true`` or + ``is_nullable=false`` (the default). + If ``is_nullable`` is true, then it is legal to insert ``nil`` or an equivalent + such as ``msgpack.NULL``. + It is also legal to insert nothing at all when using trailing nullable fields. + Within indexes, such null values are always treated as equal to other null + values, and are always treated as less than non-null values. + Nulls may appear multiple times even in a unique index. Example: + + .. code-block:: lua + + box.space.tester:create_index('I', {unique = true, parts = {{field = 2, type = 'number', is_nullable = true}}}) + + .. WARNING:: + + It is legal to create multiple indexes for the same field with different + ``is_nullable`` values, or to call :doc:`/reference/reference_lua/box_space/format` + with a different ``is_nullable`` value from what is used for an index. + When there is a contradiction, the rule is: null is illegal unless + ``is_nullable=true`` for every index and for the space format. + + + .. _key_part_exclude_null: + + .. data:: exclude_null + + **Since:** :doc:`2.8.2 ` + + An index part definition may include option ``exclude_null``, + which allows an index to skip tuples with null at this part. + + By default, the option is set to ``false``. When ``exclude_null`` is turned on, + the ``is_nullable=true`` option will be set automatically. + It can't be used for the primary key. This option can be changed dynamically: + in this case the index is rebuilt. + + Such indexes do not store filtered tuples at all, so indexing can be done faster. + + ``exclude_null`` and ``is_nullable`` are connected, so this table describes + the result of combining them: + + .. container:: table stackcolumn + + .. rst-class:: left-align-column-1 + .. rst-class:: left-align-column-2 + + .. list-table:: + + * - **exclude_null/is_nullable** + - **false** + - **true** + + * - **false** + - ok + - ok + + * - **true** + - not allowed + - ok + + + + .. _key_part_path: + + .. data:: path + + To create an index for a field that is a map (a path string and a scalar value), specify the path string during index creation. + + + + + + + + + + + + + + + + + + + + + + +.. _create_index_examples: + +Examples +-------- .. _box_space-field_names: Creating an index using field names instead of field numbers ------------------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ``create_index()`` can use field names and/or field types described by the optional :doc:`/reference/reference_lua/box_space/format` clause. @@ -446,10 +441,13 @@ The variations include omitting the type, using numbers, and adding extra braces box.space.tester:create_index('I10', {parts = {{'x'}}}) box.space.tester:create_index('I11', {parts = {{'x'}, {'y'}}}) + + .. _box_space-path: Creating an index using the path option for map fields (JSON-path indexes) --------------------------------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + To create an index for a field that is a map (a path string and a scalar value), specify the path string during index creation, like this: @@ -489,10 +487,11 @@ must always be maps with the same path. **Note regarding storage engine:** vinyl supports only the TREE index type, and vinyl secondary indexes must be created before tuples are inserted. + .. _box_space-path_multikey: Creating a multikey index using the path option with [*] --------------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The string in a path option can contain ``[*]`` which is called **an array index placeholder**. Indexes defined with this are useful @@ -552,7 +551,7 @@ Some restrictions exist: .. _box_space-index_func: Creating a functional index ---------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~ Functional indexes are indexes that call a user-defined function for forming the index key, rather than depending entirely on the Tarantool default formation. @@ -698,3 +697,11 @@ N tuples, then N keys will be added to the index. s:insert({"Sherlock", "221B Baker St Marylebone London NW1 6XE UK"}) idx:select('Uk') -- Both tuples will be returned. + + + + + + + + diff --git a/doc/reference/reference_lua/box_space/format.rst b/doc/reference/reference_lua/box_space/format.rst index a7199eedd2..d0544dee82 100644 --- a/doc/reference/reference_lua/box_space/format.rst +++ b/doc/reference/reference_lua/box_space/format.rst @@ -43,9 +43,9 @@ space_object:format() :ref:`indexed fields `; * the optional ``is_nullable`` value may be either ``true`` or ``false`` (the same as the requirement in - :ref:`"Options for space_object:create_index" `). + :ref:`"Options for space_object:create_index" `). See also the warning notice in section - :ref:`Allowing null for an indexed key `. + :ref:`Allowing null for an indexed key `. It is not legal for tuples to contain values that have the wrong type. The example below will cause an error: diff --git a/doc/reference/reference_lua/key_def.rst b/doc/reference/reference_lua/key_def.rst index 62e8540da2..d84369e94b 100644 --- a/doc/reference/reference_lua/key_def.rst +++ b/doc/reference/reference_lua/key_def.rst @@ -25,7 +25,7 @@ to extract or compare the index key values. The parts table has components which are the same as the ``parts`` option in - :ref:`Options for space_object:create_index() `. + :ref:`Options for space_object:create_index() `. ``fieldno`` (integer), for example, ``fieldno = 1``. It is legal to use ``field`` instead of ``fieldno``. diff --git a/doc/reference/reference_lua/uuid.rst b/doc/reference/reference_lua/uuid.rst index 0e1592ab06..0d54bf04f6 100644 --- a/doc/reference/reference_lua/uuid.rst +++ b/doc/reference/reference_lua/uuid.rst @@ -72,7 +72,7 @@ Below is list of all ``uuid`` functions and members. Since version :doc:`2.4.1 `. Create a UUID sequence. You can use it in an index over a - :ref:`UUID field `. + :ref:`UUID field `. For example, to create such index for a space named ``test``, say: .. code-block:: tarantoolsession diff --git a/doc/reference/reference_sql/sql_plus_lua.rst b/doc/reference/reference_sql/sql_plus_lua.rst index 1e2e6b26ca..0f05eba084 100644 --- a/doc/reference/reference_sql/sql_plus_lua.rst +++ b/doc/reference/reference_sql/sql_plus_lua.rst @@ -83,7 +83,7 @@ The NoSQL :ref:`basic data operation requests ` select, insert, replace, upsert, update, delete will all work. Particularly interesting are the requests that come only via NoSQL. -To create an index on things (remark) with a non-default :ref:`option ` for example a special id, say: |br| +To create an index on things (remark) with a non-default :ref:`option ` for example a special id, say: |br| ``box.space.THINGS:create_index('idx_100_things_2', {id=100, parts={2, 'scalar'}})`` (If the SQL data type name is SCALAR, then the NoSQL type is 'scalar', diff --git a/doc/reference/reference_sql/sql_statements_and_clauses.rst b/doc/reference/reference_sql/sql_statements_and_clauses.rst index a2bba3f2c4..0656295fb5 100644 --- a/doc/reference/reference_sql/sql_statements_and_clauses.rst +++ b/doc/reference/reference_sql/sql_statements_and_clauses.rst @@ -359,7 +359,7 @@ Column definition -- relation to NoSQL ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ All of the SQL data types except SCALAR correspond to -:ref:`Tarantool/NoSQL types with the same name `. +:ref:`Tarantool/NoSQL types with the same name `. For example an SQL STRING is stored in a NoSQL space as type = 'string'. Therefore specifying an SQL data type X determines that the storage will be @@ -2633,7 +2633,7 @@ what is sometimes called a "full table scan", even if there is an index for Ordinarily Tarantool chooses the appropriate index or lookup method depending on a complex set of "optimizer" rules; the INDEXED BY clause overrides the optimizer choice. If the index was defined with the -:ref:`exclude_null ` parts option, +:ref:`exclude_null ` parts option, it will only be used if the user specifies it. Example: diff --git a/doc/reference/reference_sql/sql_user_guide.rst b/doc/reference/reference_sql/sql_user_guide.rst index c8dc1a263e..6bea181405 100644 --- a/doc/reference/reference_sql/sql_user_guide.rst +++ b/doc/reference/reference_sql/sql_user_guide.rst @@ -807,7 +807,7 @@ column it is in. If the data type of NULL cannot be determined from context, it is BOOLEAN. Most of the SQL data types correspond to -:ref:`Tarantool/NoSQL types ` with the same name. +:ref:`Tarantool/NoSQL types ` with the same name. In Tarantool versions before :tarantool-release:`2.10.0`, There were also some Tarantool/NoSQL data types which had no corresponding SQL data types. In those versions, if Tarantool/SQL reads a Tarantool/NoSQL value of a type that has no SQL equivalent, diff --git a/doc/release/1.7.rst b/doc/release/1.7.rst index f1a85d742c..292ff57e59 100644 --- a/doc/release/1.7.rst +++ b/doc/release/1.7.rst @@ -32,12 +32,12 @@ New options are available for: * space :ref:`formats ` (user-defined field names and types), * :ref:`base64 ` (``urlsafe`` option), and * index :ref:`creation ` - (collation, :ref:`is-nullable `, field names). + (collation, :ref:`is-nullable `, field names). Incompatible changes: * Layout of ``box.space._index`` has been extended to support - :ref:`is_nullable ` + :ref:`is_nullable ` and :ref:`collation ` features. All new indexes created on columns with ``is_nullable`` or ``collation`` properties will have the new definition format. @@ -79,7 +79,7 @@ Functionality added or changed: By default, all fields in Tarantool are "NOT NULL". Starting from Tarantool 1.7.6, you can use ``is_nullable`` option in :ref:`space:format() ` - or :ref:`inside an index part definition ` + or :ref:`inside an index part definition ` to allow storing NULL in indexes. Tarantool partially implements `three-valued logic `_ diff --git a/doc/release/1.9.rst b/doc/release/1.9.rst index f4854492a7..53a5e87a7e 100644 --- a/doc/release/1.9.rst +++ b/doc/release/1.9.rst @@ -78,7 +78,7 @@ Functionality added or changed: * (Application server) :ref:`box.info.memory() ` provides a high-level overview of server memory usage, including networking, Lua, transaction and index memory. (:tarantool-issue:`934`). - * (Database) it is now possible to :ref:`add missing tuple fields ` to an index, + * (Database) it is now possible to :ref:`add missing tuple fields ` to an index, which is very useful when adding an index along with the evolution of the database schema. :tarantool-issue:`2988`). @@ -87,7 +87,7 @@ Functionality added or changed: (:tarantool-issue:`2893`, :tarantool-issue:`3011` and :tarantool-issue:`3008`). - * (Database) it is now possible to turn on :ref:`is_nullable ` property on a field + * (Database) it is now possible to turn on :ref:`is_nullable ` property on a field even if the space is not empty, the change is instantaneous. (:tarantool-issue:`2973`). * (Database) :ref:`logging ` has been improved in many respects: individual messages diff --git a/doc/release/2.4.1.rst b/doc/release/2.4.1.rst index 4dd1003939..6356cd78e0 100644 --- a/doc/release/2.4.1.rst +++ b/doc/release/2.4.1.rst @@ -57,8 +57,8 @@ Core :tarantool-issue:`2916`). Read more: - :ref:`UUID field type ` - - :ref:`mapping UUID field to index types ` - - :ref:`uuid.new() `. + - :ref:`mapping UUID field to index types ` + - :ref:`uuid.new() ` - Add ability to encode/decode UUIDs to MsgPack (:tarantool-issue:`4268`, :tarantool-issue:`2916`). Read more: :ref:`MessagePack extensions (UUID type) `. diff --git a/doc/release/2.6.1.rst b/doc/release/2.6.1.rst index 3aeb8c43af..52f3f0f17f 100644 --- a/doc/release/2.6.1.rst +++ b/doc/release/2.6.1.rst @@ -69,7 +69,7 @@ Core Read more: :doc:`/reference/reference_lua/box_space/alter`. - Composite types extraction is now supported in key_def (:tarantool-issue:`4538`). - Make memtx tuple hints an optional feature (:tarantool-issue:`4927`). - Read more: :ref:`Options for space_object:create_index() `. + Read more: :ref:`Options for space_object:create_index() `. Vinyl ~~~~~