Document Revisions Overview

• The revisions configuration enables or disables the creation and purging of revisions for documents,
  and optionally limits the number of revisions retained per document.

• By default, the revisions feature is disabled for all collections: no revisions are created or purged for any document. You can modify this behavior and other revisions settings by applying a revisions configuration to the database. The revisions configuration is stored in the database record.

Defining a revisions configuration

You can apply a revisions configuration using the Studio or the Client API:

• Via Studio:
  • Manage the revisions configuration in the Document Revisions settings view.
  • Inspect existing revisions and manually create a new revision in the Revisions tab in the Studio's Document View.
• Via Client API:
  • Use the ConfigureRevisionsOperation Store operation to define and apply a revisions configuration.

Default settings and collection-specific configurations

The revisions configuration consists of default settings and/or collection-specific configurations:

• Default settings:
  The default settings apply to all documents for which a collection-specific configuration is not defined.

• Collection-specific configurations:
  Collection-specific configurations apply only to documents of the collections they are defined for,
  overriding the default settings for these collections.
  

  If no default settings are applied, revisions will be disabled for any collection where a collection-specific configuration is not defined.

Revisions configuration options

A revisions configuration defines -

• Whether to enable or disable revisions creation:

  • If the revisions configuration is Enabled for a collection,
    creating, modifying, or deleting any document in this collection will trigger the automatic creation of a new document revision, and optionally the purging of existing revisions for the document.
  • If the revisions configuration is Disabled for a collection,
    RavenDB will not automatically create or purge revisions for documents in this collection.

• Whether to limit the number of revisions that can be kept per document.
  RavenDB will only purge revisions if they exceed the limits you set.

• Learn more about the available configuration options in Configure revisions operations.

Revisions configuration execution

Creating a revisions configuration does not immediately trigger its execution.
Default and collection-specific configurations are executed when -

1. Documents are Created, Modified, or Deleted.
   When a document is created, modified, or deleted, the configuration (either default or collection-specific) that applies to its collection is examined. If the revisions configuration is enabled for this collection:

   • A revision of the document will be created.
   • Existing revisions will optionally be purged according to the limits set in the configuration.

2. Enforce Configuration is applied.
   Enforcing the configuration applies the defined revisions configuration immediately throughout the database, purging all the revisions pending purging according to default settings or collection-specific configurations, and deleting all revisions that no configuration applies to.
   

   • Large databases and collections may contain numerous revisions pending purging, which Enforcing Configuration will purge all at once. Be aware that this operation may require substantial server resources, so time it accordingly.
   • Revisions that were created over time but to which no configuration currently applies will be deleted.
     Make sure that your configuration includes the default settings and collection-specific configurations needed to retain the revisions you want to keep.
     

Enabling and disabling revisions for existing documents

• When revisions creation is Enabled for a populated collection:

  • The first revision will be created for an existing document the next time the document is modified
    (recording the document after its modification), or when the document is deleted.

• When revisions creation is Disabled for a collection after revisions have been created:

  • The creation of new revisions and the purging of existing revisions will stop.
  • Existing revisions will remain intact.

Let's play with revisions a little to get a taste of its advantages.

1. Enable Revisions so we can experiment with the feature.
   Revisions can be enabled from the Studio or using the ConfigureRevisionsOperation Store operation.

   

   Enable Revisions for the Users Collection

2. Create a new document in the Users collection.
   We will follow the automatic creation of revisions for this document.
   You can create the document in the Studio or using the session.Store method.

   

   Create a Document

3. Inspect the new document's Revisions tab in the Studio.
   Creating the document also created its first revision.

   

   Revision for Document Creation

   (Click the See the current document button to return to the parent document view.)

4. Modify and Save the document.
   This will create a second revision.

   

   Revision for Document Modification

5. Delete the document.
   Though you deleted the document, its audit trail is not lost: all revisions were moved to the Revisions Bin,
   including a new revision (called "Delete-Revision"), created to indicate that the document was deleted.

   To see the "orphaned" revisions (whose parent document was deleted):

   • Open the Documents > Revisions Bin section in the Studio
   • Click the deleted document's ID
   

   Revisions Bin

6. Restore the document.
   To restore the document after deleting it from one of its revisions, create a document with the same ID as the document you deleted.

   The revisions of the deleted document will be restored from the revisions bin and added to the new document. Opening the document's Revisions tab will display the whole audit trail, including the delete-revision created when the old document was deleted and the revision created when the new document was created.

   

   Restored Revisions

Revisions storage

When a document revision is created, a full version of the modified document is stored in the revisions storage, using the same blittable JSON document format as regular documents.

Revisions Compression

• By default, revisions are compressed.
  This setting can be customized server-wide via the CompressRevisionsDefault configuration key.
• At the database level, revisions compression can be customized via the database record,
  as shown in this example.
• Individual fields are compressed as they are compressed in regular documents:
  any text field exceeding 128 bytes is compressed.
  Learn more about documents compression in Documents Compression.

Storage of document extensions in revisions

Read here about revisions and time series.
Read here about revisions and counters.
Read here about revisions and attachments.

So far we've discussed the automatic creation of revisions when the feature is enabled.
However, you can also force the creation of a document revision, whether the feature is enabled or not.

This is useful when you choose to disable automatic revisions creation but still want to create a revision for a specific document, e.g. take a snapshot of the document as a precaution before editing it.

• You can force the creation of a revision via the Studio or use the Client API.
• A revision will be created even if the revisions configuration is disabled for the document's collection.
• A revision will be created even if the document has not been modified
  (unless the document has revisions and the latest revision contains the current document contents).
• Similar to revisions created automatically due to the revisions configuration,
  deleting a document with a manually created revision will move the revision to the Revisions Bin,
  and a "Delete-Revision" will be created.

Force revision creation via the Studio

To create a revision manually via the Studio,
click the Create Revision button in the Revisions tab in the document view.

Create a revision manually

Force revision creation via the Client API

To create a revision manually via the API, use the advanced session force_revision_creation_for method.

with self.store.open_session() as session:
    company = session.load(company_id, Company)
    company.name = "HR V2"

    session.advanced.revisions.force_revision_creation_for(company)
    session.save_changes()

    revisions = session.advanced.revisions.get_for(company.Id, Company)
    revisions_count = len(revisions)

    self.assertEqual(1, revisions_count)
    # Assert revision contains the value 'Before' the changes...
    self.assertEqual("HR", revisions[0].name)