Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

A newer version of this documentation is available.

View Latest

Revisions

      +

      About Sync Gateway’s use of Revisions, Revision Trees and Revision Caches.
      Revisions are at the heart of Couchbase Mobile’s ability to respond flexibly and securely to changing data from server to edge.

      Related concepts topics: Users | Roles | Channels | Revisions | Tombstones

      Other related topics: Pruning — Managing DB Sizes in Couchbase Mobile | Data Replication Protocol - Revision Trees | MVCC — Demystifying Conflict Resolution]

      Introduction

      Documents and buckets (collections of, usually related, documents) are the basic units of data within Couchbase.

      Remember that within Couchbase Mobile a document comprises:

      • A Document ID

      • A current revision ID

      • A JSON body

      • Metadata

      Each change to a document (even its creation and deletion) is recorded as a revision. The document’s revisions are contained within its metadata, which stores the revision history as a revision tree.

      Note that binary data such images, audio or other multimedia objects are stored separately from the document,in an entity known as a blob (or attachment). Changes to blobs do not generate revisions.

      Revisions

      Couchbase creates a revision whenever a document is created, updated or deleted. So, each document comprises a series of one or more revisions, a revision tree.

      Each revision is given a unique Revision ID in addition to the Document ID.

      The revision id is used when resolving any conflicts arising when concurrent changes are made to replicated copies of distributed data. It comprises two parts:

      • a generation ID
        This is a sequential auto-incrementing number, specific to the database on which the document resides. Couchbase Lite generates simple integers. Sync Gateway generates more complex long base64 values.
        The contents of remote revision IDs are implementation dependent. Do not base any processing logic on their contents.

      • a hash derived from the document contents

      Revision Trees

      A document’s revision tree comprises each revision — in sequence — that has been made to the document throughout its lifetime to date. The tip of that tree, the leaf node, is the current revision — the most recent version of the document.

      A revision tree’s growth is unlimited and obsolete revisions need to be removed in order to maintain performance levels. This process is know as Revision Tree Pruning.

      Revision Tree Pruning

      In the section

      Algorithm | Controls | Constraints | Learn More

      The process of removing obsolete revisions (pruning) runs automatically every time a revision is added.

      Algorithm

      Although fundamentally the same, the pruning algorithm works slightly differently between Sync Gateway and Couchbase Lite.

      On Sync Gateway, the pruning algorithm is applied to the shortest, non-tombstoned branch in the revision tree.

      The algorithm allows the branch to retain a configurable number of revisions (revs_limit) and removes all older revisions.

      Controls

      You can vary the number of retained revisions using the Configuration File’s revs_limit setting.

      So, for example, with a revs_limit of 1000 the algorithm will keep the last 1000 revisions in the shortest non-tombstoned branch and remove any others from that branch.

      Do not set revs_limit below 100 when allow_conflicts = true
      Otherwise …​ you may adversely affect the conflict resolution process, as there may be insufficient revision history to resolve a given conflict.

      Constraints

      The default and minimum values of revs_limit are dependent on whether allow_conflicts is True or False.

      The presence of multiple unresolved conflicts in a revision tree can impair the pruning process. This may result in obsolete revisions not being pruned, or in revisions being pruned prematurely.

      Learn More

      To learn more about revision pruning and database size management in general see our blog: Pruning — Managing DB Sizes in Couchbase Mobile.

      Revision Caching

      In this section

      Control | Size | Sharding | Delta Sync and Revisions | Disabling the Revision Cache

      Whenever a document is accessed its revision tree (or at least some portion of its revision tree) is also cached.

      Control

      You can control the size of the revision cache using the rev_cache settings within the configuration file, specifically:

      Size

      Use the rev_cache.size setting to specify the total number of document revisions to be cached in memory for all (recently accessed) documents.

      When the revision cache is full, Sync Gateway will remove older document revisions to make room for newer ones.

      By adjusting this setting you can fine-tune Sync Gateway’s memory consumption. This can be useful when working on servers with limited memory and in cases when Sync Gateway creates and-or updated many new documents relative to the number of read operations.

      Sharding

      This content relates only to ENTERPRISE EDITION

      The Community Edition is configured with the default value and ignores any rev_cache.shard_count value in the configuration file.

      You can control the number of shards ino which Sync Gateway will split its revisions cache by using the rev_cache.shard_count

      More shards means lower cache contention when accessing distinct revisions, at the cost of some memory overhead per-shard.

      Do not change the default rev_cache.shard_count unless advised to do so by Couchbase Support — see: Couchbase Support Policy.

      Delta Sync and Revisions

      This content relates only to ENTERPRISE EDITION

      When executing a write operation with delta_sync enabled the revision body is backed up in the bucket and retained for this_db.delta_sync.rev_max_age_seconds, during which time it is available for the calculation of future revision deltas.

      As a result, new deltas can only be generated for read requests that come in within the this_db.delta_sync.rev_max_age_seconds time window.

      Storing backed up revision bodies for delta sync incurs additional bucket storage, the size of which equates to:
      `(doc_size * updates_per_day * rev_max_age_seconds) / 86400 ` — see Example 1.

      Example 1. Calculating Additional Delta-Sync Storage

      Enabling delta sync would take up an additional 400 KB of storage on Couchbase Server, assuming:

      • An average document size of 4 KB

      • 100 writes/day

      • The default {rev_max_age_seconds} value

      Equating to: (4 * 100 * 86400)/86400 = 400 KB

      Setting this_db.delta_sync.rev_max_age_seconds to zero will generate deltas opportunistically on pull replications, with no additional storage requirements.

      Disabling the Revision Cache

      This content relates only to ENTERPRISE EDITION

      Disabling the revision cache can be useful when there are very large documents or if you expect a very low cache hit rate. Otherwise it can negatively impact the latency of replications.

      Do not disable the revision cache, unless advised to do so by Couchbase Support — see: Couchbase Support Policy.

      To disable the revision cache entirely, set rev_cache.size to zero. Community Edition ignores a zero setting.

      Related Content

      Learn more …​
      Reference material …​
      Community