Skip to content

Commit 2535467

Browse files
p7novxuniq
p7nov
and
xuniq
authored
Add _space_sequence and _vspace_sequence reference (#3610)
Resolves #3292 Co-authored-by: Kseniia Antonova <[email protected]>
1 parent eca7a36 commit 2535467

File tree

8 files changed

+187
-75
lines changed

8 files changed

+187
-75
lines changed

‎doc/code_snippets/test/sequence/sequence_test.lua

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
local fio = require('fio')
2+
local server = require('luatest.server')
3+
local t = require('luatest')
4+
local g = t.group()
5+
g.before_each(function(cg)
6+
cg.server = server:new {
7+
box_cfg = {},
8+
workdir = fio.cwd() .. '/tmp'
9+
}
10+
cg.server:start()
11+
end)
12+
13+
g.after_each(function(cg)
14+
cg.server:stop()
15+
cg.server:drop()
16+
end)
17+
18+
g.test_sequence = function(cg)
19+
cg.server:exec(function()
20+
-- Create a sequence --
21+
box.schema.sequence.create('id_seq',{min=1000, start=1000})
22+
--[[
23+
---
24+
- step: 1
25+
id: 1
26+
min: 1000
27+
cache: 0
28+
uid: 1
29+
cycle: false
30+
name: id_seq
31+
start: 1000
32+
max: 9223372036854775807
33+
...
34+
--]]
35+
36+
-- Get the next item --
37+
box.sequence.id_seq:next()
38+
--[[
39+
---
40+
- 1000
41+
...
42+
--]]
43+
44+
-- Create a space --
45+
box.schema.space.create('customers')
46+
47+
-- Create an index that uses the sequence --
48+
box.space.customers:create_index('primary',{ sequence = 'id_seq' })
49+
--[[
50+
---
51+
- parts:
52+
- type: unsigned
53+
is_nullable: false
54+
fieldno: 1
55+
sequence_id: 1
56+
id: 0
57+
space_id: 513
58+
unique: true
59+
hint: true
60+
type: TREE
61+
name: primary
62+
sequence_fieldno: 1
63+
...
64+
--]]
65+
66+
-- Insert a tuple without the primary key value --
67+
box.space.customers:insert{ nil, 'Adams' }
68+
--[[
69+
---
70+
- [1001, 'Adams']
71+
...
72+
--]]
73+
74+
-- Create a space --
75+
box.schema.space.create('orders')
76+
77+
-- Create an index that uses an auto sequence --
78+
box.space.orders:create_index( 'primary', { sequence = true })
79+
80+
-- Check the connections between spaces and sequences
81+
box.space._space_sequence:select{}
82+
--[[
83+
---
84+
- - [512, 1, false, 0, '']
85+
- [513, 2, true, 0, '']
86+
...
87+
--]]
88+
89+
-- Tests --
90+
t.assert_equals(box.sequence.id_seq:next(), 1002)
91+
t.assert_equals(box.space.customers:insert{ nil, 'Adams' }, {1003, 'Adams'})
92+
t.assert_equals(box.space.orders:insert{ nil, 'test' }, {1, 'test'})
93+
t.assert_equals(box.space._space_sequence:select{}, { { 512, 1, false, 0, '' }, { 513, 2, true, 0, '' }})
94+
95+
end)
96+
end

‎doc/how-to/db/sequences.rst

Lines changed: 33 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ As with spaces and indexes, you should specify the sequence **name** and let
99
Tarantool generate a unique numeric identifier (sequence ID).
1010

1111
As well, you can specify several options when creating a new sequence.
12-
The options determine what value will be generated whenever the sequence is used.
12+
The options determine the values that are generated whenever the sequence is used.
1313

1414
.. _index-box_sequence-options:
1515

@@ -63,75 +63,43 @@ the next value, or associated with an index.
6363
Associating a sequence with an index
6464
------------------------------------
6565

66-
For an initial example, we generate a sequence named 'S'.
66+
First, create a sequence:
6767

68-
.. code-block:: tarantoolsession
69-
70-
tarantool> box.schema.sequence.create('S',{min=5, start=5})
71-
---
72-
- step: 1
73-
id: 5
74-
min: 5
75-
cache: 0
76-
uid: 1
77-
max: 9223372036854775807
78-
cycle: false
79-
name: S
80-
start: 5
81-
...
68+
.. literalinclude:: /code_snippets/test/sequence/sequence_test.lua
69+
:language: lua
70+
:lines: 20-34
71+
:dedent:
8272

8373
The result shows that the new sequence has all default values,
8474
except for the two that were specified, ``min`` and ``start``.
8575

86-
Then we get the next value, with the ``next()`` function.
87-
88-
.. code-block:: tarantoolsession
89-
90-
tarantool> box.sequence.S:next()
91-
---
92-
- 5
93-
...
94-
95-
The result is the same as the start value. If we called ``next()``
96-
again, we would get 6 (because the previous value plus the
97-
step value is 6), and so on.
98-
99-
Then we create a new table and specify that its primary key should be
100-
generated from the sequence.
101-
102-
.. code-block:: tarantoolsession
103-
104-
tarantool> s=box.schema.space.create('T')
105-
---
106-
...
107-
tarantool> s:create_index('I',{sequence='S'})
108-
---
109-
- parts:
110-
- type: unsigned
111-
is_nullable: false
112-
fieldno: 1
113-
sequence_id: 1
114-
id: 0
115-
space_id: 520
116-
unique: true
117-
type: TREE
118-
sequence_fieldno: 1
119-
name: I
120-
...
121-
---
122-
...
123-
124-
Then we insert a tuple without specifying a value for the primary key.
125-
126-
.. code-block:: tarantoolsession
127-
128-
tarantool> box.space.T:insert{nil,'other stuff'}
129-
---
130-
- [6, 'other stuff']
131-
...
132-
133-
The result is a new tuple where the first field has a value of 6.
134-
This arrangement, where the system automatically generates the
76+
Get the next value from the sequence by calling the ``next()`` function:
77+
78+
.. literalinclude:: /code_snippets/test/sequence/sequence_test.lua
79+
:language: lua
80+
:lines: 36-42
81+
:dedent:
82+
83+
The result is the same as the start value. The next call increases the value
84+
by one (the default sequence step).
85+
86+
Create a space and specify that its primary key should be
87+
generated from the sequence:
88+
89+
.. literalinclude:: /code_snippets/test/sequence/sequence_test.lua
90+
:language: lua
91+
:lines: 44-64
92+
:dedent:
93+
94+
Insert a tuple without specifying a value for the primary key:
95+
96+
.. literalinclude:: /code_snippets/test/sequence/sequence_test.lua
97+
:language: lua
98+
:lines: 65-72
99+
:dedent:
100+
101+
The result is a new tuple where the first field is assigned the next value from
102+
the sequence. This arrangement, where the system automatically generates the
135103
values for a primary key, is sometimes called "auto-incrementing"
136104
or "identity".
137105

‎doc/reference/reference_lua/box_space.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -148,6 +148,13 @@ Below is a list of all ``box.space`` functions and members.
148148
* - :doc:`./box_space/_vspace`
149149
- (Metadata) List of spaces accessible for the current user
150150

151+
* - :doc:`./box_space/_space_sequence`
152+
- (Metadata) List of connections between spaces and sequences
153+
154+
* - :doc:`./box_space/_vspace_sequence`
155+
- (Metadata) List of connections between spaces and sequences accessible
156+
for the current user
157+
151158
* - :doc:`./box_space/_user`
152159
- (Metadata) List of users
153160

@@ -215,6 +222,8 @@ To see examples, visit the :ref:`how-to guide on CRUD operations <box_space_exam
215222
box_space/_sequence_data
216223
box_space/_space
217224
box_space/_vspace
225+
box_space/_space_sequence
226+
box_space/_vspace_sequence
218227
box_space/_user
219228
box_space/_vuser
220229
box_space/_ck_constraint

‎doc/reference/reference_lua/box_space/_space.rst

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
11
.. _box_space-space:
22

3-
===============================================================================
43
box.space._space
5-
===============================================================================
4+
================
65

76
.. module:: box.space
87

@@ -21,6 +20,8 @@ box.space._space
2120

2221
These fields are established by :doc:`/reference/reference_lua/box_schema/space_create`.
2322

23+
The :ref:`system space view <box_space-sysviews>` for ``_space`` is ``_vspace``.
24+
2425
**Example #1:**
2526

2627
The following function will display every simple field in all tuples of
@@ -98,6 +99,3 @@ box.space._space
9899
---
99100
- - [12345, 1, 'TM', 'memtx', 0, {}, [{'name': 'field_1'}, {'type': 'unsigned'}]]
100101
...
101-
102-
The :ref:`system space view <box_space-sysviews>` for ``_space`` is ``_vspace``.
103-

‎doc/reference/reference_lua/box_space/_space_sequence.rst

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
.. _box_space-space-sequence:
2+
3+
box.space._space_sequence
4+
=========================
5+
6+
.. module:: box.space
7+
8+
.. data:: _space_sequence
9+
10+
``_space_sequence`` is a system space. It contains connections between spaces
11+
and sequences.
12+
13+
Tuples in this space contain the following fields:
14+
15+
* ``id`` (``unsigned``) -- space id
16+
* ``sequence_id`` (``unsigned``) -- id of the attached sequence
17+
* ``is_generated`` (``boolean``) -- ``true`` if the sequence was created automatically
18+
via a ``space:create_index('pk', {sequence = true})`` call
19+
* ``field`` (``unsigned``) -- id of the space field to which the sequence is attached.
20+
* ``path`` (``string``) -- path to the data within the field that is set
21+
using the attached sequence.
22+
23+
The :ref:`system space view <box_space-sysviews>` for ``_space_sequence`` is
24+
``_vspace_sequence``.
25+
26+
27+
**Example**
28+
29+
.. literalinclude:: /code_snippets/test/sequence/sequence_test.lua
30+
:language: lua
31+
:lines: 20-21,44-48,73-87
32+
:dedent:

‎doc/reference/reference_lua/box_space/_vspace.rst

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
11
.. _box_space-vspace:
22

3-
===============================================================================
43
box.space._vspace
5-
===============================================================================
4+
=================
65

76
.. module:: box.space
87

‎doc/reference/reference_lua/box_space/_vspace_sequence.rst

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
.. _box_space-vspace-sequence:
2+
3+
box.space._vspace_sequence
4+
==========================
5+
6+
.. module:: box.space
7+
8+
.. data:: _vspace_sequence
9+
10+
``_vspace_sequence`` is the :ref:`system space view <box_space-sysviews>` for
11+
:ref:`_space <box_space-space-sequence>`.

‎doc/reference/reference_lua/box_space/system_views.rst

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,7 @@
11
.. _box_space-sysviews:
22

3-
===============================================================================
43
System space views
5-
===============================================================================
6-
4+
==================
75

86
A system space view, also called a 'sysview', is a restricted read-only copy of a system space.
97

@@ -14,6 +12,7 @@ The system space views and the system spaces that they are associated with are:
1412
``_vpriv``, a view of :ref:`_priv <box_space-priv>`, |br|
1513
``_vsequence``, a view of :ref:`_sequence <box_space-sequence>`, |br|
1614
``_vspace``, a view of :ref:`_space <box_space-space>`, |br|
15+
``_vspace_sequence``, a view of :ref:`_space_sequence <box_space-space-sequence>`, |br|
1716
``_vuser``, a view of :ref:`_user <box_space-user>`.
1817

1918
The structure of a system space view's tuples is identical to the

0 commit comments

Comments
 (0)