diff --git a/doc/sphinx/book/box/box_index.rst b/doc/sphinx/book/box/box_index.rst
index c269c7009b286b17e5fae6bd5c973ce5c26f1a4a..3d421d1ff242e2e94f7a210c0702bec5ab6bc928 100644
--- a/doc/sphinx/book/box/box_index.rst
+++ b/doc/sphinx/book/box/box_index.rst
@@ -484,6 +484,21 @@ API is a direct binding to corresponding methods of index objects of type
:return: the updated tuple.
:rtype: tuple
+ .. function:: upsert(key, {{operator, field_no, value}, ...}, {tuple})
+
+ Update or insert a tuple.
+
+ Same as :func:`box.space...upsert() <space_object.upsert>`,
+ but key is searched in this index instead of primary key.
+ This index ought to be unique.
+
+ :param lua-value key: key to be matched against the index key
+ :param table {operator, field_no, value}: update opearations (see: func:`box.space...update() <space_object.update>`)
+
+ :return: the updated or inserted tuple.
+ :rtype: tuple
+
+
.. function:: delete(key)
Delete a tuple identified by a key.
diff --git a/doc/sphinx/book/box/box_space.rst b/doc/sphinx/book/box/box_space.rst
index c8080e942da6825404c095e78d0ef2646ea4800d..4cb344bdd278fd5f517ee68211664282b475db29 100644
--- a/doc/sphinx/book/box/box_space.rst
+++ b/doc/sphinx/book/box/box_space.rst
@@ -5,7 +5,7 @@
.. module:: box.space
The ``box.space`` package has the data-manipulation functions ``select``,
-``insert``, ``replace``, ``update``, ``delete``, ``get``, ``put``. It also has
+``insert``, ``replace``, ``update``, ``upsert``, ``delete``, ``get``, ``put``. It also has
members, such as id, and whether or not a space is enabled. Package source code
is available in file
`src/box/lua/schema.lua <https://github.com/tarantool/tarantool/blob/master/src/box/lua/schema.lua>`_.
@@ -65,6 +65,8 @@ A list of all ``box.space`` functions follows, then comes a list of all
| :codenormal:`---`
| :codenormal:`...`
+.. _box_insert:
+
.. function:: insert(tuple)
Insert a tuple into a space.
@@ -233,6 +235,8 @@ A list of all ``box.space`` functions follows, then comes a list of all
Example: :codenormal:`tarantool>` :codebold:`box.space.tester:replace{5000, 'New value'}`
+.. _box_update:
+
.. function:: update(key, {{operator, field_no, value}, ...})
Update a tuple.
@@ -359,6 +363,39 @@ A list of all ``box.space`` functions follows, then comes a list of all
| :codenormal:`box.space.tester:update({999}, {{':', 2, 2, 1, '!!'}})`
+ .. function:: upsert(key, {{operator, field_no, value}, ...}, {tuple})
+
+ Update or insert a tuple.
+
+ If there is an existing tuple which matches :code:`key`, then the
+ request has the same effect as :ref:`update <box_update>` and the
+ :code:`{{operator, field_no, value}, ...}` parameter is used.
+ If there is no existing tuple which matches :code:`key`, then the
+ request has the same effect as :ref:`insert <box_insert>` and the
+ :code:`{tuple}` parameter is used.
+
+ :param space_object space-object:
+ :param lua-value key: primary-key field values, must be passed as a Lua
+ table if key is multi-part
+ :param table {operator, field_no, value}: a group of arguments for each
+ operation, indicating what the operation is, what field the
+ operation will apply to, and what value will be applied. The
+ field number can be negative, meaning the position from the
+ end of tuple (#tuple + negative field number + 1).
+
+ :return: the updated or inserted tuple.
+ :rtype: tuple
+
+ Possible errors: it is illegal to modify a primary-key field.
+
+ Complexity Factors: Index size, Index type, number of indexes accessed, WAL
+ settings.
+
+ | :codebold:`Example:`
+ |
+ | :codenormal:`tarantool>` :codebold:`box.space.tester:upsert({12},{{'=',3,'a'},{'=',4,'b'}},{13,'c'})`
+
+
.. function:: delete(key)
Delete a tuple identified by a primary key.
diff --git a/doc/sphinx/book/box/index.rst b/doc/sphinx/book/box/index.rst
index 458a72ad79349fd0d24852c21ebecac0946ccc1b..ae09442bc1b0cc37daf88bbee64227afe8e0a7b7 100644
--- a/doc/sphinx/book/box/index.rst
+++ b/doc/sphinx/book/box/index.rst
@@ -199,8 +199,8 @@ For more tuple examples see :ref:`box.tuple <box-tuple>`.
Operations
----------
-The basic operations are: the four data-change operations
-(insert, update, delete, replace), and the data-retrieval
+The basic operations are: the five data-change operations
+(insert, update, upsert, delete, replace), and the data-retrieval
operation (select). There are also minor operations like
“ping†which can only be used with the binary protocol.
Also, there are :ref:`index iterator <index-iterator>` operations, which can only
@@ -422,7 +422,7 @@ Data manipulation
-----------------
The basic "data-manipulation" requests are:
-:codenormal:`insert`, :codenormal:`replace`, :codenormal:`update`,
+:codenormal:`insert`, :codenormal:`replace`, :codenormal:`update`, :codenormal:`upsert`,
: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.
@@ -495,7 +495,7 @@ 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
members as well as functions. The functions allow data definition (create
-alter drop), data manipulation (insert delete update select replace), and
+alter drop), data manipulation (insert delete update upsert select replace), and
introspection (inspecting contents of spaces, accessing server configuration).
diff --git a/doc/sphinx/book/box/triggers.rst b/doc/sphinx/book/box/triggers.rst
index 80864adbe38b83695107cefcb3fc164b113961bd..b47f01108bf7ab22bef5f38eb11bb751309a87b6 100644
--- a/doc/sphinx/book/box/triggers.rst
+++ b/doc/sphinx/book/box/triggers.rst
@@ -145,7 +145,7 @@ Here is what might appear in the log file in a typical installation:
.. function:: box.space.<space-name>:on_replace(trigger-function [, old-trigger-function])
Create a "``replace trigger``". The ``function-name`` will be executed whenever
- a ``replace()`` or ``insert()`` or ``update()`` or ``delete()`` happens to a
+ a ``replace()`` or ``insert()`` or ``update()`` or ``upsert()`` or ``delete()`` happens to a
tuple in ``<space-name>``.
:param function trigger-function: function which will become the trigger function