[GitHub] jiangphcn commented on a change in pull request #285: Couchdb 3326 clustered purge

[GitBox <gi...@apache.org>]

jiangphcn commented on a change in pull request #285: Couchdb 3326 clustered purge
URL: https://github.com/apache/couchdb-documentation/pull/285#discussion_r202673339
 
 

 ##########
 File path: src/api/database/misc.rst
 ##########
 @@ -78,47 +63,216 @@
         {
             "c6114c65e295552ab1019e2b046b10e": [
                 "3-b06fcd1c1c9e0ec7c480ee8aa467bf3b",
-                "3-0e871ef78849b0c206091f1a7af6ec41"
+                "3-c50a32451890a3f1c3e423334cc92745"
             ]
         }
 
     **Response**:
 
     .. code-block:: http
 
-        HTTP/1.1 200 OK
+        HTTP/1.1 201 Created
         Cache-Control: must-revalidate
-        Content-Length: 103
+        Content-Length: 107
         Content-Type: application/json
-        Date: Mon, 12 Aug 2013 10:53:24 GMT
-        Server: CouchDB (Erlang/OTP)
+        Date: Fri, 02 Jun 2017 18:55:54 GMT
+        Server: CouchDB/2.0.0-2ccd4bf (Erlang OTP/18)
 
         {
-            "purge_seq":3,
-            "purged":{
-                "c6114c65e295552ab1019e2b046b10e": [
-                    "3-b06fcd1c1c9e0ec7c480ee8aa467bf3b"
-                ]
+          "purged": {
+            "c6114c65e295552ab1019e2b046b10e": {
+              "purged": [
+                "3-c50a32451890a3f1c3e423334cc92745"
+              ],
+              "ok": true
             }
+          }
         }
 
+.. figure:: ../../../images/rev-tree1.png
+     :align: center
+     :alt: Document Revision Tree 1
+
+     Document Revision Tree 1
+
+For example, given the above purge tree and issuing the above purge request,
+the whole document will be purged, as it contains only a single branch with a
+leaf revision  `3-c50a32451890a3f1c3e423334cc92745` that will be purged.
+As a result of this purge operation, a document with
+`_id:c6114c65e295552ab1019e2b046b10e` will be completely removed from the
+database's documents's b+tree, and sequence b+tree. It will not be available
+through `_all_docs` or `_changes` APIs, as though this document never existed.
+Also as a result of purge operation, the database's `purge_seq` and `update_seq`
+will be increased.
+
+Notice, how revision `3-b06fcd1c1c9e0ec7c480ee8aa467bf3b` was ignored. Revisions
+that have already been purged and non-leaf revisions are ignored in a purge
+request.
+
+If a document has two conflict revisions with the following revision history:
+
+.. figure:: ../../../images/rev-tree2.png
+     :align: center
+     :alt: Document Revision Tree 1
+
+     Document Revision Tree 2
+
+the above purge request will purge only one branch, leaving the document's
+revision tree with only a single branch:
+
+.. figure:: ../../../images/rev-tree3.png
+    :align: center
+    :alt: Document Revision Tree 3
+
+    Document Revision Tree 3
+
+As a result of this purge operation, a new updated version of the document will
+be available in `_all_docs` and `_changes`, creating a new record in `_changes`.
+The database's `purge_seq` and `update_seq` will be increased.
+
+Internal Replication
+======================
+Purges are automatically replicated between replicas of the same database. Each
+database has an internal purge tree that stores a certain number of the most
+recent purges. This allows internal synchonization between replicas of the same
+database.
+
+External Replication
+======================
+Purge operations are not replicated to other external databases. External
+replication works by identifying source's document revisions that are missing on
+target, and copying these revisions from source to target. A purge operation
+completely purges revisions from a document's purge tree making external
+replication of purges not possible.
+
+    .. note::
+      If you are replicating between external databases and have
+      purged any documents and interested in having corresponding
+      purges in other databases as well, you should run purge
+      separately on each of the external databases.
+
 Updating Indexes
 ================
 
 The number of purges on a database is tracked using a purge sequence. This is
 used by the view indexer to optimize the updating of views that contain the
 purged documents.
 
-When the indexer identifies that the purge sequence on a database has changed,
-it compares the purge sequence of the database with that stored in the view
-index. If the difference between the stored sequence and database is sequence
-is only 1, then the indexer uses a cached list of the most recently purged
-documents, and then removes these documents from the index individually. This
-prevents completely rebuilding the index from scratch.
+Each internal database indexer, including the view indexer, keeps its own purge
+sequence. The purge sequence stored in index can be much smaller than the
+database's purge sequence up to the number of purge requests allowed to be
+stored in the purge trees of the database. Multiple purge requests can be
+processed by indexer without incurring rebuilt of the index. The index will be
+updated according to these purge requests.
+
+The index of document is based on winner of revision tree. Depending on which
+revision specified in purge request, there are different behaviors to update
+index:
+
+- if winner of revision tree is not specified in purge request, there is no
+  change on index record of this document;
+- if winner of revision tree is specified in purge request and there is still
+  revision left after purging, the index record of document will be built
+  according to new winner of revision tree;
+- if all revisions of document are specified in purge request, the index record
+  of document will be deleted. The document can't be searched out any more.
+
+.. _api/db/_purged_infos_limit:
+
+==============================
+``/db/_purged_infos_limit``
+==============================
+
+.. http:get:: /{db}/_purged_infos_limit
 
 Review comment:
   We changed from `_purged_docs_limit` to `_purged_infos_limit`. Let us check with Paul @davisp about his preference. 

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services