Skip to content

Commit ac45261

Browse files
OnvemberNickVolynkin
Onvember
and
NickVolynkin
authored
fixes gh-1691 create an overview page about indexes (#1847)
* gh-1691 create an overview page about indexes * update table about indexes features * Apply suggestions from code review Co-authored-by: Nick Volynkin <[email protected]> * fix indentation for list * add more info about RTREE indexes from Tarantool wiki * small improvements after review * add links to reference Co-authored-by: Nick Volynkin <[email protected]>
1 parent 36b38f9 commit ac45261

File tree

4 files changed

+644
-313
lines changed

4 files changed

+644
-313
lines changed

‎doc/book/box/data_model.rst

Lines changed: 28 additions & 226 deletions
Original file line numberDiff line numberDiff line change
@@ -61,11 +61,35 @@ When Tarantool returns a tuple value in the console,
6161
by default it uses :ref:`YAML <interactive_console>` format,
6262
for example: ``[3, 'Ace of Base', 1993]``.
6363

64-
.. // Including a section about indexes
65-
6664
.. _index-box_index:
6765

68-
.. include:: indexes.rst
66+
--------------------------------------------------------------------------------
67+
Indexes
68+
--------------------------------------------------------------------------------
69+
70+
Read the full information about indexes on page :doc:`Indexes </book/box/indexes>`.
71+
72+
An **index** is a group of key values and pointers.
73+
74+
As with spaces, you should specify the index **name**, and let Tarantool
75+
come up with a unique **numeric identifier** ("index id").
76+
77+
An index always has a **type**. The default index type is :ref:`TREE <indexes-tree>`.
78+
TREE indexes are provided by all Tarantool engines, can index unique and
79+
non-unique values, support partial key searches, comparisons and ordered results.
80+
Additionally, memtx engine supports :ref:`HASH <indexes-hash>`,
81+
:ref:`RTREE <indexes-rtree>` and :ref:`BITSET <indexes-bitset>` indexes.
82+
83+
An index may be **multi-part**, that is, you can declare that an index key value
84+
is composed of two or more fields in the tuple, in any order.
85+
For example, for an ordinary TREE index, the maximum number of parts is 255.
86+
87+
An index may be **unique**, that is, you can declare that it would be illegal
88+
to have the same key value twice.
89+
90+
The first index defined on a space is called the **primary key index**,
91+
and it must be unique. All other indexes are called **secondary indexes**,
92+
and they may be non-unique.
6993

7094
.. _index-box_data-types:
7195

@@ -362,7 +386,7 @@ Full information is in section
362386
| ``'string'`` | :ref:`string <index-box_string>` | TREE, BITSET or HASH |
363387
| (may also be called ``‘str’``) | | |
364388
+--------------------------------+-------------------------------------------+--------------------------------------+
365-
| ``'varbinary'`` | :ref:`varbinary <index-box_bin>` | TREE or HASH |
389+
| ``'varbinary'`` | :ref:`varbinary <index-box_bin>` | TREE, BITSET or HASH |
366390
+--------------------------------+-------------------------------------------+--------------------------------------+
367391
| ``'uuid'`` | :ref:`uuid <index-box_uuid>` | TREE or HASH |
368392
+--------------------------------+-------------------------------------------+--------------------------------------+
@@ -792,228 +816,6 @@ See reference on ``box.space`` for more
792816
The client server protocol is open and documented.
793817
See this :ref:`annotated BNF <box_protocol-iproto_protocol>`.
794818

795-
.. _index-box_index-operations:
796-
797-
********************************************************
798-
Index operations
799-
********************************************************
800-
801-
Index operations are automatic: if a data-manipulation request changes a tuple,
802-
then it also changes the index keys defined for the tuple.
803-
804-
The simple index-creation operation that we've illustrated before is:
805-
806-
.. cssclass:: highlight
807-
.. parsed-literal::
808-
809-
:samp:`box.space.{space-name}:create_index('{index-name}')`
810-
811-
This creates a unique TREE index on the first field of all tuples
812-
(often called "Field#1"), which is assumed to be numeric.
813-
814-
The simple SELECT request that we've illustrated before is:
815-
816-
.. cssclass:: highlight
817-
.. parsed-literal::
818-
819-
:extsamp:`box.space.{*{space-name}*}:select({*{value}*})`
820-
821-
This looks for a single tuple via the first index. Since the first index
822-
is always unique, the maximum number of returned tuples will be: one.
823-
You can call ``select()`` without arguments, causing all tuples to be returned.
824-
825-
Let's continue working with the space 'tester' created in the :ref:`"Getting
826-
started" exercises <getting_started_db>` but first modify it:
827-
828-
.. code-block:: tarantoolsession
829-
830-
tarantool> box.space.tester:format({
831-
> {name = 'id', type = 'unsigned'},
832-
> {name = 'band_name', type = 'string'},
833-
> {name = 'year', type = 'unsigned'},
834-
> {name = 'rate', type = 'unsigned', is_nullable=true}})
835-
---
836-
...
837-
838-
Add the rate to the tuple #1 and #2:
839-
840-
.. code-block:: tarantoolsession
841-
842-
tarantool> box.space.tester:update(1, {{'=', 4, 5}})
843-
---
844-
- [1, 'Roxette', 1986, 5]
845-
...
846-
tarantool> box.space.tester:update(2, {{'=', 4, 4}})
847-
---
848-
- [2, 'Scorpions', 2015, 4]
849-
...
850-
851-
852-
And insert another tuple:
853-
854-
.. code-block:: tarantoolsession
855-
856-
tarantool> box.space.tester:insert({4, 'Roxette', 2016, 3})
857-
---
858-
- [4, 'Roxette', 2016, 3]
859-
...
860-
861-
**The existing SELECT variations:**
862-
863-
1. The search can use comparisons other than equality.
864-
865-
.. code-block:: tarantoolsession
866-
867-
tarantool> box.space.tester:select(1, {iterator = 'GT'})
868-
---
869-
- - [2, 'Scorpions', 2015, 4]
870-
- [3, 'Ace of Base', 1993]
871-
- [4, 'Roxette', 2016, 3]
872-
...
873-
874-
The :ref:`comparison operators <box_index-iterator-types>` are LT, LE, EQ, REQ, GE, GT
875-
(for "less than", "less than or equal", "equal", "reversed equal",
876-
"greater than or equal", "greater than" respectively).
877-
Comparisons make sense if and only if the index type is ‘TREE'.
878-
879-
This type of search may return more than one tuple; if so, the tuples will be
880-
in descending order by key when the comparison operator is LT or LE or REQ,
881-
otherwise in ascending order.
882-
883-
2. The search can use a secondary index.
884-
885-
For a primary-key search, it is optional to specify an index name.
886-
For a secondary-key search, it is mandatory.
887-
888-
.. code-block:: tarantoolsession
889-
890-
tarantool> box.space.tester:create_index('secondary', {parts = {{field=3, type='unsigned'}}})
891-
---
892-
- unique: true
893-
parts:
894-
- type: unsigned
895-
is_nullable: false
896-
fieldno: 3
897-
id: 2
898-
space_id: 512
899-
type: TREE
900-
name: secondary
901-
...
902-
tarantool> box.space.tester.index.secondary:select({1993})
903-
---
904-
- - [3, 'Ace of Base', 1993]
905-
...
906-
907-
3. The search may be for some key parts starting with the prefix of
908-
the key. Notice that partial key searches are available only in TREE indexes.
909-
910-
.. code-block:: tarantoolsession
911-
912-
-- Create an index with three parts
913-
tarantool> box.space.tester:create_index('tertiary', {parts = {{field = 2, type = 'string'}, {field=3, type='unsigned'}, {field=4, type='unsigned'}}})
914-
---
915-
- unique: true
916-
parts:
917-
- type: string
918-
is_nullable: false
919-
fieldno: 2
920-
- type: unsigned
921-
is_nullable: false
922-
fieldno: 3
923-
- type: unsigned
924-
is_nullable: true
925-
fieldno: 4
926-
id: 6
927-
space_id: 513
928-
type: TREE
929-
name: tertiary
930-
...
931-
-- Make a partial search
932-
tarantool> box.space.tester.index.tertiary:select({'Scorpions', 2015})
933-
---
934-
- - [2, 'Scorpions', 2015, 4]
935-
...
936-
937-
4. The search may be for all fields, using a table for the value:
938-
939-
.. code-block:: tarantoolsession
940-
941-
tarantool> box.space.tester.index.tertiary:select({'Roxette', 2016, 3})
942-
---
943-
- - [4, 'Roxette', 2016, 3]
944-
...
945-
946-
or the search can be for one field, using a table or a scalar:
947-
948-
.. code-block:: tarantoolsession
949-
950-
tarantool> box.space.tester.index.tertiary:select({'Roxette'})
951-
---
952-
- - [1, 'Roxette', 1986, 5]
953-
- [4, 'Roxette', 2016, 3]
954-
...
955-
956-
********************************************************
957-
Working with BITSET and RTREE
958-
********************************************************
959-
960-
**BITSET example:**
961-
962-
.. code-block:: tarantoolsession
963-
964-
tarantool> box.schema.space.create('bitset_example')
965-
tarantool> box.space.bitset_example:create_index('primary')
966-
tarantool> box.space.bitset_example:create_index('bitset',{unique=false,type='BITSET', parts={2,'unsigned'}})
967-
tarantool> box.space.bitset_example:insert{1,1}
968-
tarantool> box.space.bitset_example:insert{2,4}
969-
tarantool> box.space.bitset_example:insert{3,7}
970-
tarantool> box.space.bitset_example:insert{4,3}
971-
tarantool> box.space.bitset_example.index.bitset:select(2, {iterator='BITS_ANY_SET'})
972-
973-
The result will be:
974-
975-
.. code-block:: tarantoolsession
976-
977-
---
978-
- - [3, 7]
979-
- [4, 3]
980-
...
981-
982-
because (7 AND 2) is not equal to 0, and (3 AND 2) is not equal to 0.
983-
984-
**RTREE example:**
985-
986-
.. code-block:: tarantoolsession
987-
988-
tarantool> box.schema.space.create('rtree_example')
989-
tarantool> box.space.rtree_example:create_index('primary')
990-
tarantool> box.space.rtree_example:create_index('rtree',{unique=false,type='RTREE', parts={2,'ARRAY'}})
991-
tarantool> box.space.rtree_example:insert{1, {3, 5, 9, 10}}
992-
tarantool> box.space.rtree_example:insert{2, {10, 11}}
993-
tarantool> box.space.rtree_example.index.rtree:select({4, 7, 5, 9}, {iterator = 'GT'})
994-
995-
The result will be:
996-
997-
.. code-block:: tarantoolsession
998-
999-
---
1000-
- - [1, [3, 5, 9, 10]]
1001-
...
1002-
1003-
because a rectangle whose corners are at coordinates ``4,7,5,9`` is entirely
1004-
within a rectangle whose corners are at coordinates ``3,5,9,10``.
1005-
1006-
Additionally, there exist
1007-
:doc:`index iterator operations </reference/reference_lua/box_index/pairs>`.
1008-
They can only be used with code in Lua and C/C++. Index iterators are for
1009-
traversing indexes one key at a time, taking advantage of features that are
1010-
specific to an index type, for example evaluating Boolean expressions when
1011-
traversing BITSET indexes, or going in descending order when traversing TREE indexes.
1012-
1013-
See also other index operations like
1014-
:doc:`alter() </reference/reference_lua/box_index/alter>`
1015-
(modify index) and :doc:`drop() </reference/reference_lua/box_index/drop>`
1016-
(delete index) in reference for :doc:`/reference/reference_lua/box_index`.
1017819

1018820
********************************************************
1019821
Complexity factors

0 commit comments

Comments
 (0)