draft

Author: xuniq

doc/platform/sharding/vshard_admin.rst

@@ -551,6 +551,90 @@ In a router application, you can define the ``put`` function that specifies how
 
 Learn more at :ref:`vshard-process-requests`.
 
+.. _vshard-deduplication:
+
+Deduplication of non-idempotent requests
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Idempotent requests** produce the same result every time they are called.
+For example, a data read request or a multiplication by one are idempotent.
+Increment by one is an example of a non-idempotent operation.
+When such an operation is applied again, the value for the field will be increased by 2 instead of 1.
+
+..  note::
+
+    Any write requests that are planned to be executed repeatedly should be idempotent.
+    The idempotency of such operations ensures that the change from the operation will be applied **only once**.
+
+Re-invoking queries
+
+A query may need to be re-executed if an error occurs on the server or client side.
+In this case:
+
+- Read requests can be executed repeatedly. To do this, the method
+[vshard.router.call()](https://www.tarantool.io/ru/doc/latest/reference/reference_rock/vshard/vshard_router/#router-api-call)
+in the `read` mode (`mode=read`) uses the `request_timeout` parameter (available since `vshard` 0.1.28).
+The `request_timeout` and `timeout` parameters must be passed together, observing the following condition:
+
+  For example, if ``timeout = 10``, and ``request_timeout = 2``,
+  then within 10 seconds the router is able to make up to 5 attempts to contact (2 seconds each) with a request to different replicas,
+  until the request finally succeeds.
+
+- Write requests ([vshard.router.callrw()](https://www.tarantool.io/ru/doc/latest/reference/reference_rock/vshard/vshard_router/#router-api-callrw))
+in general **cannot be re-executed** without checking that the request has not been applied before.
+Lack of such a check may lead to duplicate records or unplanned data changes.
+
+  For example, a client has sent a request to the server and is waiting for a response within a specified time.
+  If the server sends a response about successful execution after this time has elapsed, the client will receive an error and when
+  re-sending the request without additional checking, the operation may be applied twice.
+
+  A write request can be re-executed without a check only if the error occurred on the server side --
+  for example, `ER_READONLY`.
+
+Methods of deduplicating queries
+
+To ensure idempotency of write queries, such as data insert, update, and upsert, as well as autoincrement,
+it is necessary to implement a check in the code that the query is being used for the first time.
+
+For example, when adding a new tuple to a space, a unique key by which the insertion is performed can be used for checking.
+In such a query within a single transaction:
+
+1. It is checked whether there is a tuple with the key `key` in the `bands` space.
+2. If there is no record with such a key in the space, the tuple is inserted.
+
+..  code-block:: lua
+
+    box.begin()
+    if box.space.bands:get{key} == nil then
+        box.space.bands:insert{key, value}
+    end
+    box.commit()
+
+For tuple update requests, a separate _deduplication_ space can be created, in which the query IDs will be saved.
+_deduplication_ space is a user space that contains a list of unique identifiers.
+Each such identifier corresponds to one executed query.
+This space can have any name, in the example it is called `deduplication`.
+
+In the example below, within a single transaction:
+
+1. The `deduplication` space is checked for the presence of the `deduplication_key` request ID.
+2. If there is no such ID, this ID is added to the deduplication space.
+3. The request then increments the specified field in the `bands` space by one.
+
+This approach ensures that each data modification request will be executed **only once**.
+
+..  code-block:: lua
+
+    function update_1(deduplication_key, key)
+        box.begin()
+        if box.space.deduplication:get{deduplication_key} == nil then
+            box.space.deduplication:insert{deduplication_key}
+            box.space.bands:update(key, {{'+', 'value', 1 }})
+        end
+        box.commit()
+    end
+
+
 .. _vshard-maintenance:
 
 Sharded cluster maintenance