flimzy commented on a change in pull request #285: Couchdb 3326 clustered purge
URL:
https://github.com/apache/couchdb-documentation/pull/285#discussion_r201067301
##########
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.
Review comment:
A question here: Is it worth mentioning that these purges should be done
while replications are not running? Otherwise, people may end up in a race,
purging docs, just to see them recreated during replication.... if I'm not
mistaken?
----------------------------------------------------------------
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:
[email protected]
With regards,
Apache Git Services
