From 4288e2cf477ba972a49e33a1cd6103c8efd39022 Mon Sep 17 00:00:00 2001
From: ocelot-inc <pgulutzan@ocelot.ca>
Date: Sun, 14 Jun 2015 17:03:21 -0600
Subject: [PATCH] 1/3 repair of whole manual
---
doc/sphinx/_static/sphinx_design.css | 7 +-
doc/sphinx/book/box/box_index.rst | 2 +
doc/sphinx/book/box/box_schema.rst | 22 +-
doc/sphinx/book/box/box_space.rst | 750 +++++++++++++--------------
doc/sphinx/book/box/index.rst | 70 +--
doc/sphinx/book/index.rst | 1 +
doc/sphinx/book/intro.rst | 143 +++--
doc/sphinx/conf.py | 20 +-
8 files changed, 526 insertions(+), 489 deletions(-)
diff --git a/doc/sphinx/_static/sphinx_design.css b/doc/sphinx/_static/sphinx_design.css
index 4e63207a97..5e01ee393a 100644
--- a/doc/sphinx/_static/sphinx_design.css
+++ b/doc/sphinx/_static/sphinx_design.css
@@ -450,9 +450,14 @@ div.b-cols_content_left .b-search-text {
height: 100%;
}
+/*
+ Classes whose names start with "ccode" are a Tarantool extension,
+ see comment in conf.py file: Tarantool custom roles
+*/
+
.ccode, .ccodeb, .ccodei, .ccodebi {
white-space: pre;
- font-size: 13px;
+ font-size: 14px;
font-family: monospace;
}
diff --git a/doc/sphinx/book/box/box_index.rst b/doc/sphinx/book/box/box_index.rst
index ef5095bd4d..d967125a4a 100644
--- a/doc/sphinx/book/box/box_index.rst
+++ b/doc/sphinx/book/box/box_index.rst
@@ -289,6 +289,8 @@ API is a direct binding to corresponding methods of index objects of type
---
...
+.. _index_select:
+
.. function:: select(key, options)
This is is an alternative to :func:`box.space...select() <space_object.select>`
diff --git a/doc/sphinx/book/box/box_schema.rst b/doc/sphinx/book/box/box_schema.rst
index ce26ff70c6..8af37388ab 100644
--- a/doc/sphinx/book/box/box_schema.rst
+++ b/doc/sphinx/book/box/box_schema.rst
@@ -41,18 +41,16 @@ The ``box.schema`` package has one data-definition function: ``space.create()``.
Example
=================================================
-.. code-block:: lua
-
- tarantool> s = box.schema.space.create('space55')
- ---
- ...
- tarantool> s = box.schema.space.create('space55', {id = 555, temporary = false})
- ---
- - error: Space 'space55' already exists
- ...
- tarantool> s = box.schema.space.create('space55', {if_not_exists = true})
- ---
- ...
+ | :codenormal:`tarantool>` :codebold:`s = box.schema.space.create('space55')`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`s = box.schema.space.create('space55', {id = 555, temporary = false})`
+ | :codenormal:`---`
+ | :codenormal:`- error: Space 'space55' already exists`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`s = box.schema.space.create('space55', {if_not_exists = true})`
+ | :codenormal:`---`
+ | :codenormal:`...`
After a space is created, usually the next step is to
:func:`create an index <space_object.create_index>` for it,
diff --git a/doc/sphinx/book/box/box_space.rst b/doc/sphinx/book/box/box_space.rst
index 86f6df2702..5390b1bace 100644
--- a/doc/sphinx/book/box/box_space.rst
+++ b/doc/sphinx/book/box/box_space.rst
@@ -58,14 +58,12 @@ A list of all ``box.space`` functions follows, then comes a list of all
unique option other than unique, or a parts option with more than one
field component, is only applicable for the memtx storage engine.
- .. code-block:: lua
-
- tarantool> s = box.space.space55
- ---
- ...
- tarantool> s:create_index('primary', {unique = true, parts = {1, 'NUM', 2, 'STR'}})
- ---
- ...
+ | :codenormal:`tarantool>` :codebold:`s = box.space.space55`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`s:create_index('primary', {unique = true, parts = {1, 'NUM', 2, 'STR'}})`
+ | :codenormal:`---`
+ | :codenormal:`...`
.. function:: insert(tuple)
@@ -79,9 +77,7 @@ A list of all ``box.space`` functions follows, then comes a list of all
Possible errors: If a tuple with the same unique-key value already exists,
returns :errcode:`ER_TUPLE_FOUND`.
- .. code-block:: lua
-
- box.space.tester:insert{5000,'tuple number five thousand'}
+ Example: :codebold:`box.space.tester:insert{5000,'tuple number five thousand'}`
.. function:: select(key)
@@ -102,57 +98,55 @@ A list of all ``box.space`` functions follows, then comes a list of all
Complexity Factors: Index size, Index type.
- .. code-block:: lua
-
- EXAMPLE
-
- 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']
- ...
+ | :codebold:`EXAMPLE`
+ |
+ | :codenormal:`tarantool>` :codebold:`s = box.schema.space.create('tmp', {temporary=true})`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`s:create_index('primary',{parts = {1,'NUM', 2, 'STR'}})`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`s:insert{1,'A'}`
+ | :codenormal:`---`
+ | :codenormal:`- [1, 'A']`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`s:insert{1,'B'}`
+ | :codenormal:`---`
+ | :codenormal:`- [1, 'B']`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`s:insert{1,'C'}`
+ | :codenormal:`---`
+ | :codenormal:`- [1, 'C']`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`s:insert{2,'D'}`
+ | :codenormal:`---`
+ | :codenormal:`- [2, 'D']`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`-- must equal both primary-key fields`
+ | :codenormal:`tarantool>` :codebold:`s:select{1,'B'}`
+ | :codenormal:`---`
+ | :codenormal:`- - [1, 'B']`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`-- must equal only one primary-key field`
+ | :codenormal:`tarantool>` :codebold:`s:select{1}`
+ | :codenormal:`---`
+ | :codenormal:`- - [1, 'A']`
+ | :codenormal:`- [1, 'B']`
+ | :codenormal:`- [1, 'C']`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`-- must equal 0 fields, so returns all tuples`
+ | :codenormal:`tarantool>` :codebold:`s:select{}`
+ | :codenormal:`---`
+ | :codenormal:`- - [1, 'A']`
+ | :codenormal:`- [1, 'B']`
+ | :codenormal:`- [1, 'C']`
+ | :codenormal:`- [2, 'D']`
+ | :codenormal:`...`
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``.
+ :ref:`box.space.space-name[.index.index-name]:select <index_select>`.
.. function:: get(key)
@@ -169,11 +163,15 @@ A list of all ``box.space`` functions follows, then comes a list of all
Complexity Factors: Index size, Index type,
Number of indexes accessed, WAL settings.
- .. code-block:: lua
-
- EXAMPLE
+ The :codenormal:`box.space...select` function returns a set
+ of tuples as a Lua table; the :codenormal:`box.space...get`
+ function returns a single tuple. And it is possible to get
+ the first tuple in a tuple set by appending "[1]".
+ Therefore :codenormal:`box.space.tester:get{1}` has the same
+ effect as :codenormal:`box.space.tester:select{1}[1]`, and
+ may serve as a convenient shorthand.
- tarantool> box.space.tester:get{1}
+ Example: :codenormal:`tarantool>` :codebold:`box.space.tester:get{1}`
.. function:: drop()
@@ -188,11 +186,7 @@ A list of all ``box.space`` functions follows, then comes a list of all
Complexity Factors: Index size, Index type,
Number of indexes accessed, WAL settings.
- .. code-block:: lua
-
- EXAMPLE
-
- tarantool> box.space.space_that_does_not_exist:drop()
+ Example: :codenormal:`tarantool>` :codebold:`box.space.space_that_does_not_exist:drop()`
.. function:: rename(space-name)
@@ -205,16 +199,14 @@ A list of all ``box.space`` functions follows, then comes a list of all
Possible errors: ``space-name`` does not exist.
- .. code-block:: lua
-
- EXAMPLE
-
- tarantool> box.space.space55:rename('space56')
- ---
- ...
- tarantool> box.space.space56:rename('space55')
- ---
- ...
+ | :codebold:`EXAMPLE`
+ |
+ | :codenormal:`tarantool>` :codebold:`box.space.space55:rename('space56')`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`box.space.space56:rename('space55')`
+ | :codenormal:`---`
+ | :codenormal:`...`
.. function:: replace(tuple)
put(tuple)
@@ -239,11 +231,7 @@ A list of all ``box.space`` functions follows, then comes a list of all
Complexity Factors: Index size, Index type,
Number of indexes accessed, WAL settings.
- .. code-block:: lua
-
- EXAMPLE
-
- tarantool> box.space.tester:replace{5000, 'New value'}
+ Example: :codenormal:`tarantool>` :codebold:`box.space.tester:replace{5000, 'New value'}`
.. function:: update(key, {{operator, field_no, value}, ...})
@@ -258,7 +246,7 @@ A list of all ``box.space`` functions follows, then comes a list of all
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
+ applied. In other words, it is always safe to merge multiple :codenormal:`update`
invocations into a single invocation, with no change in semantics.
Possible operators are:
@@ -273,6 +261,8 @@ A list of all ``box.space`` functions follows, then comes a list of all
* '#' for deletion
* '=' for assignment
+ For “!†and “=†operations the field number can be -1, meaning the last field in the tuple.
+
: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
@@ -290,85 +280,84 @@ A list of all ``box.space`` functions follows, then comes a list of all
Complexity Factors: Index size, Index type, number of indexes accessed, WAL
settings.
- Thus in the instruction s:update(44, {{'+',1,55},{'=',3,'x'}})
+ Thus in the instruction :codenormal:`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
-
- EXAMPLE
-
- -- 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, '!!'}})
+ | :codebold:`EXAMPLE`
+ |
+ | :codenormal:`-- Assume that the initial state of the database is ...`
+ | :codenormal:`-- tester has one tuple set and one primary key whose type is 'NUM'.`
+ | :codenormal:`-- There is one tuple, with field[1] = 999 and field[2] = 'A'.`
+ |
+ | :codenormal:`-- In the following update ...`
+ | :codenormal:`-- The first argument is tester, that is, the affected space is tester`
+ | :codenormal:`-- The second argument is 999, that is, the affected tuple is identified by`
+ | :codenormal:`-- primary key value = 999`
+ | :codenormal:`-- The third argument is '=', that is, there is one operation, assignment`
+ | :codenormal:`-- to a field`
+ | :codenormal:`-- The fourth argument is 2, that is, the affected field is field[2]`
+ | :codenormal:`-- The fifth argument is 'B', that is, field[2] contents change to 'B'`
+ | :codenormal:`-- Therefore, after the following update, field[1] = 999 and field[2] = 'B'.`
+ | :codenormal:`box.space.tester:update(999, {{'=', 2, 'B'}})`
+ |
+ | :codenormal:`-- In the following update, the arguments are the same, except that ...`
+ | :codenormal:`-- the key is passed as a Lua table (inside braces). This is unnecessary`
+ | :codenormal:`-- when the primary key has only one field, but would be necessary if the`
+ | :codenormal:`-- primary key had more than one field.`
+ | :codenormal:`-- Therefore, after the following update, field[1] = 999 and field[2] = 'B'`
+ | :codenormal:`-- (no change).`
+ | :codenormal:`box.space.tester:update({999}, {{'=', 2, 'B'}})`
+ |
+ | :codenormal:`-- In the following update, the arguments are the same, except that ...`
+ | :codenormal:`-- The fourth argument is 3, that is, the affected field is field[3].`
+ | :codenormal:`-- It is okay that, until now, field[3] has not existed. It gets added.`
+ | :codenormal:`-- Therefore, after the following update, field[1] = 999, field[2] = 'B',`
+ | :codenormal:`-- field[3] = 1.`
+ | :codenormal:`box.space.tester:update({999}, {{'=', 3, 1}})`
+ |
+ | :codenormal:`-- In the following update, the arguments are the same, except that ...`
+ | :codenormal:`-- The third argument is '+', that is, the operation is addition rather`
+ | :codenormal:`-- than assignment.`
+ | :codenormal:`-- Since field[3] previously contained 1, this means we're adding 1 to 1.`
+ | :codenormal:`-- Therefore, after the following update, field[1] = 999, field[2] = 'B',`
+ | :codenormal:`-- field[3] = 2.`
+ | :codenormal:`box.space.tester:update({999}, {{'+', 3, 1}})`
+ |
+ | :codenormal:`-- In the following update ...`
+ | :codenormal:`-- The idea is to modify two fields at once.`
+ | :codenormal:`-- The formats are '|' and '=', that is, there are two operations, OR and`
+ | :codenormal:`-- assignment.`
+ | :codenormal:`-- The fourth and fifth arguments mean that field[3] gets ORed with 1.`
+ | :codenormal:`-- The seventh and eighth arguments mean that field[2] gets assigned 'C'.`
+ | :codenormal:`-- Therefore, after the following update, field[1] = 999, field[2] = 'C',`
+ | :codenormal:`-- field[3] = 3.`
+ | :codenormal:`box.space.tester:update({999}, {{'|', 3, 1}, {'=', 2, 'C'}})`
+ |
+ | :codenormal:`-- In the following update ...`
+ | :codenormal:`-- The idea is to delete field[2], then subtract 3 from field[3], but ...`
+ | :codenormal:`-- after the delete, there is a renumbering -- so field[3] becomes field[2]`
+ | :codenormal:`-- before we subtract 3 from it, and that's why the seventh argument is 2 not 3.`
+ | :codenormal:`-- Therefore, after the following update, field[1] = 999, field[2] = 0.`
+ | :codenormal:`box.space.tester:update({999}, {{'-- ', 2, 1}, {'-', 2, 3}})`
+ |
+ | :codenormal:`-- In the following update ...`
+ | :codenormal:`-- We're making a long string so that splice will work in the next example.`
+ | :codenormal:`-- Therefore, after the following update, field[1] = 999, field[2] = 'XYZ'.`
+ | :codenormal:`box.space.tester:update({999}, {{'=', 2, 'XYZ'}})`
+ |
+ | :codenormal:`-- In the following update ...`
+ | :codenormal:`-- The third argument is ':', that is, this is the example of splice.`
+ | :codenormal:`-- The fourth argument is 2 because the change will occur in field[2].`
+ | :codenormal:`-- The fifth argument is 2 because deletion will begin with the second byte.`
+ | :codenormal:`-- The sixth argument is 1 because the number of bytes to delete is 1.`
+ | :codenormal:`-- The seventh argument is '!!' because '!!' is to be added at this position.`
+ | :codenormal:`-- Therefore, after the following update, field[1] = 999, field[2] = 'X!!Z'.`
+ | :codenormal:`box.space.tester:update({999}, {{':', 2, 2, 1, '!!'}})`
+
.. function:: delete(key)
@@ -383,22 +372,20 @@ A list of all ``box.space`` functions follows, then comes a list of all
Complexity Factors: Index size, Index type
- .. code-block:: lua
-
- EXAMPLE
-
- 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'
- ...
+ | :codebold:`Example:`
+ |
+ | :codenormal:`tarantool>` :codebold:`box.space.tester:delete(0)`
+ | :codenormal:`---`
+ | :codenormal:`- [0, 'My first tuple']`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`box.space.tester:delete(0)`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`box.space.tester:delete('a')`
+ | :codenormal:`---`
+ | :codenormal:`- error: 'Supplied key type of part 0 does not match index part type:`
+ | :codenormal:`expected NUM'`
+ | :codenormal:`...`
.. _space_object_id:
@@ -416,7 +403,7 @@ A list of all ``box.space`` functions follows, then comes a list of all
space-object.enabled
Whether or not this space is enabled.
- The value is false if there is no index.
+ The value is :codenormal:`false` if there is no index.
:rtype: boolean
@@ -441,22 +428,20 @@ A list of all ``box.space`` functions follows, then comes a list of all
:rtype: table
- .. code-block: lua
-
- EXAMPLE
-
- tarantool> box.space.tester.id
- ---
- - 512
- ...
- tarantool> box.space.tester.field_count
- ---
- - 0
- ...
- tarantool> box.space.tester.index.primary.type
- ---
- - TREE
- ...
+ | :codebold:`Example`
+ |
+ | :codenormal:`tarantool>` :codebold:`box.space.tester.id`
+ | :codenormal:`---`
+ | :codenormal:`- 512`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`box.space.tester.field_count`
+ | :codenormal:`---`
+ | :codenormal:`- 0`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`box.space.tester.index.primary.type`
+ | :codenormal:`---`
+ | :codenormal:`- TREE`
+ | :codenormal:`...`
.. _space_object_len:
@@ -468,14 +453,12 @@ A list of all ``box.space`` functions follows, then comes a list of all
:return: Number of tuples in the space.
- .. code-block:: lua
-
- EXAMPLE
-
- tarantool> box.space.tester:len()
- ---
- - 2
- ...
+ | :codebold:`Example`
+ |
+ | :codenormal:`tarantool>` :codebold:`box.space.tester:len()`
+ | :codenormal:`---`
+ | :codenormal:`- 2`
+ | :codenormal:`...`
.. _space_object_truncate:
@@ -487,17 +470,15 @@ A list of all ``box.space`` functions follows, then comes a list of all
:return: nil
- .. code-block:: lua
-
- EXAMPLE
-
- tarantool> box.space.tester:truncate()
- ---
- ...
- tarantool> box.space.tester:len()
- ---
- - 0
- ...
+ | :codebold:`Example`
+ |
+ | :codenormal:`tarantool>` :codebold:`box.space.tester:truncate()`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`box.space.tester:len()`
+ | :codenormal:`---`
+ | :codenormal:`- 0`
+ | :codenormal:`...`
.. _space_object_inc:
@@ -518,24 +499,23 @@ A list of all ``box.space`` functions follows, then comes a list of all
Complexity Factors: Index size, Index type, WAL settings.
- .. code-block:: lua
-
- EXAMPLE
-
- 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
- ...
+
+ | :codebold:`Example`
+ |
+ | :codenormal:`tarantool>` :codebold:`s = box.schema.space.create('forty_second_space')`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`s:create_index('primary', {unique = true, parts = {1, 'NUM', 2, 'STR'}})`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`box.space.forty_second_space:inc{1,'a'}`
+ | :codenormal:`---`
+ | :codenormal:`- 1`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`box.space.forty_second_space:inc{1,'a'}`
+ | :codenormal:`---`
+ | :codenormal:`- 2`
+ | :codenormal:`...`
.. _space_object_dec:
@@ -555,28 +535,26 @@ A list of all ``box.space`` functions follows, then comes a list of all
Complexity Factors: Index size, Index type, WAL settings.
- .. code-block:: lua
-
- EXAMPLE
-
- 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
- ...
+ | :codebold:`Example`
+ |
+ | :codenormal:`tarantool>` :codebold:`s = box.schema.space.create('space19')`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`s:create_index('primary', {unique = true, parts = {1, 'NUM', 2, 'STR'}})`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`box.space.space19:insert{1,'a',1000}`
+ | :codenormal:`---`
+ | :codenormal:`- [1, 'a', 1000]`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`box.space.space19:dec{1,'a'}`
+ | :codenormal:`---`
+ | :codenormal:`- 999`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`box.space.space19:dec{1,'a'}`
+ | :codenormal:`---`
+ | :codenormal:`- 998`
+ | :codenormal:`...`
.. _space_object_auto_increment:
@@ -597,18 +575,16 @@ A list of all ``box.space`` functions follows, then comes a list of all
Possible errors: index has wrong type or primary-key indexed field is not a number.
- .. code-block:: lua
-
- EXAMPLE
-
- 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']
- ...
+ | :codebold:`Example`
+ |
+ | :codenormal:`tarantool>` :codebold:`box.space.tester:auto_increment{'Fld#1', 'Fld#2'}`
+ | :codenormal:`---`
+ | :codenormal:`- [1, 'Fld#1', 'Fld#2']`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`box.space.tester:auto_increment{'Fld#3'}`
+ | :codenormal:`---`
+ | :codenormal:`- [2, 'Fld#3']`
+ | :codenormal:`...`
.. _space_object_pairs:
@@ -621,27 +597,25 @@ A list of all ``box.space`` functions follows, then comes a list of all
: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
-
- EXAMPLE
-
- 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
- ...
+ | :codebold:`Example`
+ |
+ | :codenormal:`tarantool>` :codebold:`s = box.schema.space.create('space33')`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`-- index 'X' has default parts {1,'NUM'}`
+ | :codenormal:`tarantool>` :codebold:`s:create_index('X', {})`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`s:insert{0,'Hello my '}; s:insert{1,'Lua world'}`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`tmp = ''; for k, v in s:pairs() do tmp = tmp .. v[2] end`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`tmp`
+ | :codenormal:`---`
+ | :codenormal:`- Hello my Lua world`
+ | :codenormal:`...`
.. data:: _schema
@@ -650,32 +624,27 @@ A list of all ``box.space`` functions follows, then comes a list of all
EXAMPLE: The following function will display all fields in all tuples of ``_schema``.
- .. code-block:: lua
-
- console = require('console'); console.delimiter('!')
- function example()
- local ta = {}, i, line
- for k, v in box.space._schema:pairs() do
- i = 1
- line = ''
- while i <= #v do line = line .. v[i] .. ' ' i = i + 1 end
- table.insert(ta, line)
- end
- return ta
- end!
- console.delimiter('')!
-
+ | :codenormal:`console = require('console'); console.delimiter('!')`
+ | :codenormal:`function example()`
+ | :codenormal:`local ta = {}, i, line`
+ | :codenormal:`for k, v in box.space._schema:pairs() do`
+ | :codenormal:`i = 1`
+ | :codenormal:`line = ''`
+ | :codenormal:`while i <= #v do line = line .. v[i] .. ' ' i = i + 1 end`
+ | :codenormal:`table.insert(ta, line)`
+ | :codenormal:`end`
+ | :codenormal:`return ta`
+ | :codenormal:`end!`
+ | :codenormal:`console.delimiter('')!`
Here is what ``example()`` returns in a typical installation:
- .. code-block:: lua
-
- tarantool> example()
- ---
- - - 'cluster 1ec4e1f8-8f1b-4304-bb22-6c47ce0cf9c6 '
- - 'max_id 520 '
- - 'version 1 6 '
- ...
+ | :codenormal:`tarantool>` :codebold:`example()`
+ | :codenormal:`---`
+ | :codenormal:`- - 'cluster 1ec4e1f8-8f1b-4304-bb22-6c47ce0cf9c6 '`
+ | :codenormal:`- 'max_id 520 '`
+ | :codenormal:`- 'version 1 6 '`
+ | :codenormal:`...`
.. data:: _space
@@ -685,43 +654,39 @@ A list of all ``box.space`` functions follows, then comes a list of all
EXAMPLE. The following function will display all simple fields
in all tuples of ``_space``.
- .. code-block:: lua
-
- console = require('console'); console.delimiter('!')
- function example()
- local ta = {}, i, line
- for k, v in box.space._space:pairs() do
- i = 1
- line = ''
- while i <= #v do
- if type(v[i]) ~= 'table' then
- line = line .. v[i] .. ' '
- end
- i = i + 1
- end
- table.insert(ta, line)
- end
- return ta
- end!
- console.delimiter('')!
+ | :codenormal:`console = require('console'); console.delimiter('!')`
+ | :codenormal:`function example()`
+ | :codenormal:`local ta = {}, i, line`
+ | :codenormal:`for k, v in box.space._space:pairs() do`
+ | :codenormal:`i = 1`
+ | :codenormal:`line = ''`
+ | :codenormal:`while i <= #v do`
+ | :codenormal:`if type(v[i]) ~= 'table' then`
+ | :codenormal:`line = line .. v[i] .. ' '`
+ | :codenormal:`end`
+ | :codenormal:`i = i + 1`
+ | :codenormal:`end`
+ | :codenormal:`table.insert(ta, line)`
+ | :codenormal:`end`
+ | :codenormal:`return ta`
+ | :codenormal:`end!`
+ | :codenormal:`console.delimiter('')!`
Here is what ``example()`` returns in a typical installation:
- .. code-block:: lua
-
- tarantool> example()
- ---
- - - '272 1 _schema memtx 0 '
- - '280 1 _space memtx 0 '
- - '288 1 _index memtx 0 '
- - '296 1 _func memtx 0 '
- - '304 1 _user memtx 0 '
- - '312 1 _priv memtx 0 '
- - '320 1 _cluster memtx 0 '
- - '512 1 tester memtx 0 '
- - '513 1 origin sophia 0 '
- - '514 1 archive memtx 0 '
- ...
+ | :codenormal:`tarantool>` :codebold:`example()`
+ | :codenormal:`---`
+ | :codenormal:`- - '272 1 _schema memtx 0 '`
+ | :codenormal:`- '280 1 _space memtx 0 '`
+ | :codenormal:`- '288 1 _index memtx 0 '`
+ | :codenormal:`- '296 1 _func memtx 0 '`
+ | :codenormal:`- '304 1 _user memtx 0 '`
+ | :codenormal:`- '312 1 _priv memtx 0 '`
+ | :codenormal:`- '320 1 _cluster memtx 0 '`
+ | :codenormal:`- '512 1 tester memtx 0 '`
+ | :codenormal:`- '513 1 origin sophia 0 '`
+ | :codenormal:`- '514 1 archive memtx 0 '`
+ | :codenormal:`...`
.. data:: _index
@@ -731,48 +696,45 @@ A list of all ``box.space`` functions follows, then comes a list of all
The following function will display all fields in all tuples of _index.
- .. code-block:: lua
-
- console = require('console'); console.delimiter('!')
- function example()
- local ta = {}, i, line
- for k, v in box.space._index:pairs() do
- i = 1
- line = ''
- while i <= #v do line = line .. v[i] .. ' ' i = i + 1 end
- table.insert(ta, line)
- end
- return ta
- end!
- console.delimiter('')!
+ | :codenormal:`console = require('console'); console.delimiter('!')`
+ | :codenormal:`function example()`
+ | :codenormal:`local ta = {}, i, line`
+ | :codenormal:`for k, v in box.space._index:pairs() do`
+ | :codenormal:`i = 1`
+ | :codenormal:`line = ''`
+ | :codenormal:`while i <= #v do line = line .. v[i] .. ' ' i = i + 1 end`
+ | :codenormal:`table.insert(ta, line)`
+ | :codenormal:`end`
+ | :codenormal:`return ta`
+ | :codenormal:`end!`
+ | :codenormal:`console.delimiter('')!`
Here is what ``example()`` returns in a typical installation:
- .. code-block:: lua
-
- tarantool> example()
- ---
- - - '272 0 primary tree 1 1 0 str '
- - '280 0 primary tree 1 1 0 num '
- - '280 1 owner tree 0 1 1 num '
- - '280 2 name tree 1 1 2 str '
- - '288 0 primary tree 1 2 0 num 1 num '
- - '288 2 name tree 1 2 0 num 2 str '
- - '296 0 primary tree 1 1 0 num '
- - '296 1 owner tree 0 1 1 num '
- - '296 2 name tree 1 1 2 str '
- - '304 0 primary tree 1 1 0 num '
- - '304 1 owner tree 0 1 1 num '
- - '304 2 name tree 1 1 2 str '
- - '312 0 primary tree 1 3 1 num 2 str 3 num '
- - '312 1 owner tree 0 1 0 num '
- - '312 2 object tree 0 2 2 str 3 num '
- - '320 0 primary tree 1 1 0 num '
- - '320 1 uuid tree 1 1 1 str '
- - '512 0 primary tree 1 1 0 num '
- - '513 0 first tree 1 1 0 NUM '
- - '514 0 first tree 1 1 0 STR '
- ...
+
+ | :codenormal:`tarantool>` :codebold:`example()`
+ | :codenormal:`---`
+ | :codenormal:`- - '272 0 primary tree 1 1 0 str '`
+ | :codenormal:`- '280 0 primary tree 1 1 0 num '`
+ | :codenormal:`- '280 1 owner tree 0 1 1 num '`
+ | :codenormal:`- '280 2 name tree 1 1 2 str '`
+ | :codenormal:`- '288 0 primary tree 1 2 0 num 1 num '`
+ | :codenormal:`- '288 2 name tree 1 2 0 num 2 str '`
+ | :codenormal:`- '296 0 primary tree 1 1 0 num '`
+ | :codenormal:`- '296 1 owner tree 0 1 1 num '`
+ | :codenormal:`- '296 2 name tree 1 1 2 str '`
+ | :codenormal:`- '304 0 primary tree 1 1 0 num '`
+ | :codenormal:`- '304 1 owner tree 0 1 1 num '`
+ | :codenormal:`- '304 2 name tree 1 1 2 str '`
+ | :codenormal:`- '312 0 primary tree 1 3 1 num 2 str 3 num '`
+ | :codenormal:`- '312 1 owner tree 0 1 0 num '`
+ | :codenormal:`- '312 2 object tree 0 2 2 str 3 num '`
+ | :codenormal:`- '320 0 primary tree 1 1 0 num '`
+ | :codenormal:`- '320 1 uuid tree 1 1 1 str '`
+ | :codenormal:`- '512 0 primary tree 1 1 0 num '`
+ | :codenormal:`- '513 0 first tree 1 1 0 NUM '`
+ | :codenormal:`- '514 0 first tree 1 1 0 STR '`
+ | :codenormal:`...`
.. data:: _user
@@ -831,21 +793,19 @@ returns a table.
... And here is what happens when one invokes the function:
-.. code-block:: lua
-
- tarantool> example()
- ---
- - - _schema tuple_count =3. first field in first tuple = cluster
- - _space tuple_count =15. first field in first tuple = 272
- - _index tuple_count =25. first field in first tuple = 272
- - _func tuple_count =1. first field in first tuple = 1
- - _user tuple_count =4. first field in first tuple = 0
- - _priv tuple_count =6. first field in first tuple = 1
- - _cluster tuple_count =1. first field in first tuple = 1
- - tester tuple_count =2. first field in first tuple = 1
- - origin tuple_count =0
- - archive tuple_count =13. first field in first tuple = test_0@tarantool.org
- - space55 tuple_count =0
- - tmp tuple_count =0
- - forty_second_space tuple_count =1. first field in first tuple = 1
- ...
+ | :codenormal:`tarantool>` :codebold:`example()`
+ | :codenormal:`---`
+ | :codenormal:`- - _schema tuple_count =3. first field in first tuple = cluster`
+ | :codenormal:`- _space tuple_count =15. first field in first tuple = 272`
+ | :codenormal:`- _index tuple_count =25. first field in first tuple = 272`
+ | :codenormal:`- _func tuple_count =1. first field in first tuple = 1`
+ | :codenormal:`- _user tuple_count =4. first field in first tuple = 0`
+ | :codenormal:`- _priv tuple_count =6. first field in first tuple = 1`
+ | :codenormal:`- _cluster tuple_count =1. first field in first tuple = 1`
+ | :codenormal:`- tester tuple_count =2. first field in first tuple = 1`
+ | :codenormal:`- origin tuple_count =0`
+ | :codenormal:`- archive tuple_count =13. first field in first tuple = test_0@tarantool.org`
+ | :codenormal:`- space55 tuple_count =0`
+ | :codenormal:`- tmp tuple_count =0`
+ | :codenormal:`- forty_second_space tuple_count =1. first field in first tuple = 1`
+ | :codenormal:`...`
diff --git a/doc/sphinx/book/box/index.rst b/doc/sphinx/book/box/index.rst
index 3f56a66a0e..368dcf76fa 100644
--- a/doc/sphinx/book/box/index.rst
+++ b/doc/sphinx/book/box/index.rst
@@ -5,9 +5,9 @@
This chapter describes how Tarantool stores values
and what operations with data it supports.
-==================
+===================
Document data model
-==================
+===================
If you tried out the
:ref:`Starting Tarantool and making your first database <first database>`
@@ -81,7 +81,7 @@ of a field is the field's number, base 1. For example
When Tarantool returns a tuple value, it surrounds
strings with single quotes, separates fields with commas,
and encloses the tuple inside square brackets.
-For example: [ 3, 'length', 93 ].
+For example: :codenormal:`[ 3, 'length', 93 ]`.
.. _box.index:
@@ -174,7 +174,7 @@ requires only one byte but the largest number requires nine bytes.
A "string" is a variable-length sequence of bytes,
usually represented with alphanumeric characters inside single quotes.
-A "boolean" is either true or false.
+A "boolean" is either :codenormal:`true` or :codenormal:`false`.
A "nil" type has only one possible value, also called "nil",
but often displayed as "null".
@@ -184,7 +184,7 @@ Nils may not be used in Lua tables; the workaround
is to use :ref:`yaml.NULL <yaml-null>` or
:ref:`json.NULL <json-null>` or :ref:`msgpack.NULL <msgpack-null>`.
-A tuple is returned in YAML format like - [120, 'a', 'b', 'c'].
+A tuple is returned in YAML format like :codenormal:`- [120, 'a', 'b', 'c']`.
A few functions may return tables with multiple tuples.
A scalar may be converted to a tuple with only one field.
A Lua table may contain all of a tuple's fields, but not nil.
@@ -238,9 +238,9 @@ Five examples of basic operations:
box.space.tester:delete{999}
How does Tarantool do a basic operation? Let's take this example:
- box.space.tester:update({3}, {{'=', 2, 'size'}, {'=', 3, 0}})
+ :codenormal:`box.space.tester:update({3}, {{'=', 2, 'size'}, {'=', 3, 0}})`
which, for those who know SQL, is equivalent to a statement like
- UPDATE tester SET "field[2]" = 'size', "field[3]" = 0 WHERE "field[[1]" = 3
+ :codenormal:`UPDATE tester SET "field[2]" = 'size', "field[3]" = 0 WHERE "field[[1]" = 3`
STEP #1: if this is happening on a remote client,
then the client parses the statement and changes
@@ -269,7 +269,7 @@ no such thing ever happens. Only the transaction processor
thread can access the database, and there is only one
transaction processor thread for each instance of the server.
-FACT #2: the transaction processor thread can handle many fibers.
+FACT #2: the transaction processor thread can handle many *fibers*.
A fiber is a set of computer instructions that may contain
“yield†signals. The transaction processor thread will execute
all computer instructions until a yield, then switch to execute
@@ -283,15 +283,15 @@ or network-access causes an implicit yield, and every
statement that goes through the tarantool client causes
an implicit yield. And there are explicit yields:
in a Lua function one can and should add “yield†statements
-to prevent hogging. This is called cooperative multitasking.
+to prevent hogging. This is called *cooperative multitasking*.
Since all data-change operations end with an implicit yield
and an implicit commit, and since no data-change operation
can change more than one tuple, there is no need for any locking.
Consider, for example, a Lua function that does three Tarantool operations:|br|
-s:select{999} -- this does not yield and does not commit |br|
-s:update({...},{{...}}) -- this yields and commits |br|
-s:select{999} -- this does not yield and does not commit |br|
+:codenormal:`s:select{999} -- this does not yield and does not commit` |br|
+:codenormal:`s:update({...},{{...}}) -- this yields and commits` |br|
+:codenormal:`s:select{999} -- this does not yield and does not commit` |br|
The combination “SELECT plus UPDATE†is an atomic transaction:
the function holds a consistent view of the database until the UPDATE ends.
For the combination “UPDATE plus SELECT†the view is not consistent,
@@ -329,19 +329,17 @@ A new WAL file is created for every :confval:`rows_per_wal <rows_per_wal>` recor
Each data change request gets assigned a continuously growing
64-bit log sequence number. The name of the WAL file is based
on the log sequence number of the first record in the file,
-plus an extension .xlog.
+plus an extension :codenormal:`.xlog`.
Apart from a log sequence number and the data change request
(its format is the same as in the binary protocol and is described
in `doc/box-protocol.html`_), each WAL record contains a header,
-some metadata, and then the data formatted according to msgpack rules.
+some metadata, and then the data formatted according to `msgpack`_ rules.
For example this is what the WAL file looks like after the first INSERT
request ("s:insert({1})") for the introductory sandbox exercise
":ref:`Starting Tarantool and making your first database <first database>`“.
-On the left are the hexadecimal bytes that one would see with
-
-$ hexdump 00000000000000000001.xlog
-
+On the left are the hexadecimal bytes that one would see with |br|
+:codebold:`$ hexdump 00000000000000000001.xlog` |br|
and on the right are comments.
.. code-block:: none
@@ -419,12 +417,13 @@ Data manipulation
-----------------
The basic "data-manipulation" requests are:
-insert, replace, update, delete, select.
-They all are part of the box library.
+:codenormal:`insert`, :codenormal:`replace`, :codenormal:`update`,
+:codenormal:`delete`, :codenormal:`select`.
+They all are part of the :codenormal:`box` library.
They all may return data. Usually both inputs and outputs may be Lua tables.
The Lua syntax for data-manipulation functions can vary.
-Here are examples of the variations with select examples;
+Here are examples of the variations with :codenormal:`select` examples;
the same rules exist for the other data-manipulation functions.
Every one of the examples does the same thing:
select a tuple set from a space named tester where
@@ -432,13 +431,13 @@ the primary-key field value equals 1.
First there are "naming variations":
- 1. box.space.tester:select{1}
+ 1. :codenormal:`box.space.tester:select{1}`
- 2. box.space['tester']:select{1}
+ 2. :codenormal:`box.space['tester']:select{1}`
- 3. box.space[512]:select{1}
+ 3. :codenormal:`box.space[512]:select{1}`
- 4. variable = 'tester'; box.space[variable]:select{1}
+ 4. :codenormal:`variable = 'tester'; box.space[variable]:select{1}`
... There is an assumption that the numeric id of
'tester' is 512, which happens to be the case in our
@@ -450,17 +449,17 @@ the variants exist in the wild.
Then there are "parameter variations":
- 1. box.space.tester:select{1}
+ 1. :codenormal:`box.space.tester:select{1}`
- 2. box.space.tester:select({1})
+ 2. :codenormal:`box.space.tester:select({1})`
- 3. box.space.tester:select(1)
+ 3. :codenormal:`box.space.tester:select(1)`
- 4. box.space.tester:select({1},{iterator='EQ'})
+ 4. :codenormal:`box.space.tester:select({1},{iterator='EQ'})`
- 5. variable = 1; box.space.tester:select{variable}
+ 5. :codenormal:`variable = 1; box.space.tester:select{variable}`
- 6. variable = {1}; box.space.tester:select(variable)
+ 6. :codenormal:`variable = {1}; box.space.tester:select(variable)`
... The primary-key value is enclosed in braces, and if
it was a multi-part primary key then the value would be
@@ -478,7 +477,7 @@ user preference and all the variants exist in the wild.
All the data-manipulation functions operate on tuple sets but,
since primary keys are unique, the number of tuples in the
-tuple set is always 1. The only exception is box.space...select,
+tuple set is always 1. The only exception is :codenormal:`box.space...select`,
which may accept either a primary-key value or a secondary-key value.
.. _box-library:
@@ -488,13 +487,14 @@ The box library
---------------
As well as executing Lua chunks or defining their own functions, users can exploit
-the Tarantool server's storage functionality with the ``box`` Lua library.
+the Tarantool server's storage functionality with the :codenormal:`Lua library`.
=====================================================================
Packages of the box library
=====================================================================
-The contents of the box library can be inspected at runtime with ``box``, with
+The contents of the :codenormal:`box` library can be inspected at runtime
+with :codenormal:`box`, with
no arguments. The packages inside the box library are:
box.schema, box.tuple, box.space, box.index, net.box, box.cfg, box.info, box.slab, box.stat.
Every package contains one or more Lua functions. A few packages contain
@@ -533,7 +533,7 @@ introspection (inspecting contents of spaces, accessing server configuration).
| | :ref:`wal_mode <wal_mode>`. If the setting causes |
| | no writing or |
| | delayed writing, this factor is unimportant. If the |
- | | settings causes every data-change request to wait |
+ | | setting causes every data-change request to wait |
| | for writing to finish on a slow device, this factor |
| | is more important than all the others. |
+-------------------+-----------------------------------------------------+
diff --git a/doc/sphinx/book/index.rst b/doc/sphinx/book/index.rst
index c283330142..4966cbdf13 100644
--- a/doc/sphinx/book/index.rst
+++ b/doc/sphinx/book/index.rst
@@ -8,6 +8,7 @@
:caption: Table of Contents
intro
+ user_guide_getting_started
box/index
replication/index
configuration/index
diff --git a/doc/sphinx/book/intro.rst b/doc/sphinx/book/intro.rst
index ff67fadbb1..31b09823ea 100644
--- a/doc/sphinx/book/intro.rst
+++ b/doc/sphinx/book/intro.rst
@@ -1,5 +1,5 @@
-------------------------------------------------------------------------------
- Intro
+ Preface
-------------------------------------------------------------------------------
===============================================================================
@@ -18,15 +18,23 @@ data persistence level.
The code is free. The open-source license is `BSD license`_. The supported platforms
are GNU/Linux, Mac OS and FreeBSD.
-Tarantool database is deeply integrated with the application server. On
-the surface, Tarantool is simply a Lua language interpreter, and the database
-is one of many built-in Lua packages. But the exposed database API not only
-allows to persist Lua objects to disk, but to manage object collections, create
-or drop secondary keys, configure and monitor replication, perform controlled
-fail-over, execute Lua code upon database events.
-Remote database instances are accessible transparently via remote
-procedure invocation API.
+Tarantool's creator and biggest user is `Mail.Ru`_, the largest internet
+company in Russia, with 30 million users, 25 million emails per day, and a web
+site whose Alexa global rank is in the `top 40`_ worldwide. Tarantool services
+Mail.Ru's hottest data, such as the session data of online users, the
+properties of online applications, the caches of the underlying data, the
+distribution and sharding algorithms, and much more. Outside Mail.Ru the
+software is used by a growing number of projects in online gaming, digital
+marketing, and social media industries. While product development is sponsored
+by Mail.Ru, the roadmap, the bugs database and the development process are
+fully open. The software incorporates patches from dozens of community
+contributors. The Tarantool community writes and maintains most of the drivers
+for programming languages. The greater Lua community has hundreds of useful
+packages most of which can become Tarantool extensions.
+Users can create, modify and drop **Lua functions** at runtime.
+Or they can define **Lua programs** that are loaded during startup for triggers,
+background tasks, and interacting with networked peers.
Unlike popular application development frameworks based on a "reactor" pattern,
networking in server-side Lua is sequential, yet very efficient, as it is built
on top of the **cooperative multitasking** environment that Tarantool itself
@@ -37,18 +45,8 @@ components of multi-tier Web application architectures. Performance is a few
thousand transactions per second on a laptop, scalable upwards or outwards to
server farms.
-Tarantool data storage is built around **storage engine** concept, when
-different sets of algorithms and data structures can be used for different
-collections of objects. Two storage engines are built-in: in-memory engine,
-which represents 100% of data and indexes in RAM, and a two-level B-tree,
-for data sets exceeding the amount of available RAM from 10 to up to 1000
-times. All storage engines in Tarantool support transactions and
-replication by using a common **write ahead log**. This ensures consistency
-and crash safety of the persistent state. The logging subsystem supports
-group commit.
-
-**Tarantool in-memory engine is lock-free**. Instead of the operating system's
-concurrency primitives, such as mutexes, it uses cooperative multitasking to
+**Tarantool is lock-free** in typical situations. Instead of the operating system's
+concurrency primitives, such as mutexes, Tarantool uses cooperative multitasking to
handle thousands of connections simultaneously. There is a fixed number of
independent execution threads. The threads do not share state. Instead they
exchange data using low-overhead message queues. While this approach limits the
@@ -56,16 +54,50 @@ number of cores that the server will use, it removes competition for the memory
bus and ensures peak scalability of memory access and network throughput. CPU
utilization of a typical highly-loaded Tarantool server is under 10%.
-**Tarantool disk-based engine** is a fusion of ideas from modern filesystems,
+Although Tarantool can run without it, the database management component
+is a strong distinguishing feature.
+(On the surface Tarantool is simply a Lua language interpreter and
+the DBMS server is one of many built-in Lua packages.)
+So here is a closer look at "The Box", or DBMS server.
+
+The database API allows for persisting Lua objects to disk,
+managing object collections, creating or dropping secondary keys,
+configuring and monitoring replication, performing controlled fail-over,
+and executing Lua code triggered by database events.
+Remote database instances are accessible transparently via
+a remote procedure invocation API.
+
+Tarantool's DBMS server uses the **storage engine** concept, where
+different sets of algorithms and data structures can be used for different
+collections of objects. Two storage engines are built-in: an in-memory engine,
+which all the data and indexes in RAM, and a two-level B-tree engine,
+for data sets whose size is 10 to 1000 times the amount of available RAM.
+All storage engines in Tarantool support transactions and
+replication by using a common **write ahead log** (WAL). This ensures consistency
+and crash safety of the persistent state.
+The server performs inserts and updates atomically -- changes
+are not considered complete until the WAL is written.
+The logging subsystem supports group commit.
+
+**Tarantool in-memory storage engine** (memtx) keeps all the data in
+random-access memory, and therefore has very low read latency.
+It also keeps persistent copies of the data in non-volatile storage,
+such as disk, when users request "snapshots".
+If a server stops and the random-access memory is lost,
+then restarts, it reads the latest snapshot
+and then replays the transactions that are in the log --
+therefore no data is lost.
+
+**Tarantool disk-based storage engine** is a fusion of ideas from modern filesystems,
log-structured merge trees and classical B-trees. All data is organized
-into **branches**, each branch is represented by a file on disk. Branch
+into **branches**. Each branch is represented by a file on disk. Branch
size is a configuration option and normally is around 64MB. Each
branch is a collection of pages, serving different purposes. Pages
in a fully merged branch contain non-overlapping ranges of keys. A branch
can be partially merged if there were a lot of changes in its key range
recently. In that case some pages represent new keys and values in the
branch. The disk-based engine is append only: new data never overwrites
-the old.
+old data.
Unlike most NoSQL DBMSs, Tarantool supports **secondary index keys** as well as
primary keys, and **multi-part index keys**. The possible index types are HASH,
@@ -76,20 +108,56 @@ The replication architecture can be **master-master**, that is, many nodes may
both handle the loads and receive what others have handled, for the same data
sets.
-Tarantool's creator and biggest user is `Mail.Ru`_, the largest internet
-company in Russia, with 30 million users, 25 million emails per day, and a web
-site whose Alexa global rank is in the `top 40`_ worldwide. Tarantool services
-Mail.Ru's hottest data, such as the session data of online users, the
-properties of online applications, the caches of the underlying data, the
-distribution and sharding algorithms, and much more. Outside Mail.Ru the
-software is used by a growing number of projects in online gaming, digital
-marketing, and social media industries. While product development is sponsored
-by Mail.Ru, the roadmap, the bugs database and the development process are
-fully open. The software incorporates patches from dozens of community
-contributors. The Tarantool community writes and maintains most of the drivers
-for programming languages. The greater Lua community has hundreds of useful
-packages most of which can be used in Tarantool applications with no change.
+===============================================================================
+ Conventions
+===============================================================================
+
+This manual is written with `Sphinx`_ markup and uses
+standard formatting conventions:
+
+UNIX shell command input is prefixed with ':codenormal:`$` ' and is in a fixed-width font:
+ :codenormal:`$ tarantool --help`
+
+File names are also in a fixed-width font:
+ :codenormal:`/path/to/var/dir`
+
+Text that represents user input is in boldface:
+ :codebold:`$ your input here`
+
+Within user input, replaceable items are in italics:
+ :codebold:`$ tarantool` :codebolditalic:`--option`
+
+===============================================================================
+ How to read the documentation
+===============================================================================
+
+To get started, one can either download the whole package
+as described in the first part of Chapter 2 "Getting started",
+or one can initially skip the download and connect to the online
+Tarantool server running on the web at http://try.tarantool.org.
+Either way, the first tryout can be a matter of following the example
+in the second part of chapter 2: "Starting Tarantool and making your first database".
+
+Chapter 3 "Databases" is about the Tarantool NoSQL DBMS.
+If the only intent is to use Tarantool as a Lua application server,
+most of the material in this chapter and in the following chapter
+(Chapter 4 "Replication") will not be necessary.
+Once again, the detailed instructions about each package can be regarded as reference material.
+
+Chapter 6 "Server administration" and Chapter 5 "Configuration reference"
+are primarily for administrators; however, every user should know something
+about how the server is configured so the section about box.cfg is not skippable.
+Chapter 7 "Connectors" is strictly for users who are connecting from a different
+language such as C or Perl or Python -- other users will find no immediate need for this chapter.
+
+The two long tutorials in Appendix C -- "Insert one million tuples with a Lua stored procedure"
+and "Sum a JSON field for all tuples" -- start slowly and contain commentary that is especially
+aimed at users who may not consider themselves experts at either Lua or NoSQL database management.
+
+Finally, Appendix D "Plugins" has examples that will be essential for those users who want to
+connect the Tarantool server to another DBMS: MySQL or PostgreSQL.
+For experienced users, there is also a developer's guide and an extensive set of comments in the source code.
===============================================================================
Reporting bugs
@@ -107,3 +175,4 @@ or via a mailing list, `Tarantool Google group`_.
.. _BSD license: http://www.gnu.org/licenses/license-list.html#ModifiedBSD
.. _Mail.Ru: http://corp.mail.ru
.. _top 40: http://www.alexa.com/siteinfo/mail.ru
+.. _Sphinx: http://sphinx-doc.org/
diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py
index 646e0e35bd..8961002ac1 100644
--- a/doc/sphinx/conf.py
+++ b/doc/sphinx/conf.py
@@ -62,21 +62,23 @@ html_use_smartypants = False
# :codebolditalic:`text` displays text as monospace italic bold
# The effect on HTML output is defined in _static/sphinx_design.css
# (which is the css file designated in _templates/layout.html).
-rst_epilog = """
-.. |br| raw:: html
-
- <br />
-
+rst_prolog = """
.. role:: codenormal
- :class: ccode
+ :class: ccode
.. role:: codebold
- :class: ccodeb
+ :class: ccodeb
.. role:: codeitalic
- :class: ccodei
+ :class: ccodei
.. role:: codebolditalic
- :class: ccodebi
+ :class: ccodebi
+"""
+
+rst_epilog = """
+.. |br| raw:: html
+
+ <br />
"""
--
GitLab