Document Revisions Overview

By default, the Revisions feature is Disabled for all collections: no revisions are created or purged for any document.
You can change this behavior, and other Revisions settings, by applying a Revisions Configuration to the database.

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

The revision configurations are stored in the database record.

Default Settings and Collection-Specific Configurations

The Revisions configuration is comprised of Default Settings and/or Collection-specific configurations.

• The default settings apply to all the documents that a collection-specific configuration is not defined for.
• Collection-specific configurations apply only to documents of the collections they are defined for,
  overriding the default settings for these collections.
  

  If you apply no default settings, Revisions will be disabled for any collection that a collection-specific configuration is not defined for.
  

Defining a Revisions Configuration

You can apply a Revisions configuration using Studio or the Client API.

• Via Studio:
  • Manage the Revisions configuration via Studio using the Studio Settings Document Revisions page.
  • Inspect and manage the revisions created for each document using Studio's Document View Revisions tab.
• Via Client API:
  Read here how to define and apply a Revisions configuration using the ConfigureRevisionsOperation Store operation.

Revisions Configuration Options

A Revisions configuration defines -

• Whether to Enable or Disable Revisions.
  • If the Revisions feature is Enabled for a collection,
    creating, modifying, or deleting any document from 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 feature is Disabled for a collection,
    RavenDB will not automatically Create or Purge revisions for documents of 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 here about the available configuration options.

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 feature is enabled for this collection:

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

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

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

Enabling and Disabling Revisions for Existing Documents

• When the Revisions feature 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.

• Disabling Revisions for a collection after revisions were 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.
   The Revisions feature can be enabled using Studio or 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 using Studio or the session.Store method.

   

   Create a Document

3. Use Studio to inspect the new document's Revisions tab.
   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 Studio Documents > Revisions Bin section
   • 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 Documents Storage

• The creation of a document revision stores a full version of the modified document in the revisions storage,
  in the same blittable JSON document format as that of regular documents.

• Revisions Compression

  • individual fields are compressed as they are compressed in regular documents:
    any text field of more than 128 bytes is compressed.
  • Revisions are compressed by default.
    Learn here how to toggle this database option on and off.
  • Learn here how to apply Document Compression to revisions.

Revisions Document Extensions Storage

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.
But 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 Revisions but still want to create a revision for a specific document,
e.g. to take a snapshot of the document as a precaution before editing it.

• You can force the creation of a revision via Studio or using the ForceRevisionCreationFor API method.
• A revision will be created even if the Revisions feature is disabled for the document's collection.
• A revision will be created even if the document was not modified
  (unless the document has revisions and the latest revision contains the current document contents).

Force Revision Creation via Studio

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

Create a revision manually

Force Revision Creation via API

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

ForceRevisionCreationFor overloads:

// Force revision creation by entity.
// Can be used with tracked entities only.
void ForceRevisionCreationFor<T>(T entity, 
              ForceRevisionStrategy strategy = ForceRevisionStrategy.Before);

// Force revision creation by document ID.
void ForceRevisionCreationFor(string id, 
              ForceRevisionStrategy strategy = ForceRevisionStrategy.Before);

• Parameters:

  Parameter	Type	Description
  entity	T	The tracked entity you want to create a revision for
  id	string	ID of the document you want to create a revision for
  strategy	ForceRevisionStrategy	Defines the revision creation strategy (see below). Default: ForceRevisionStrategy.Before

  ForceRevisionStrategy:

  public enum ForceRevisionStrategy
  {
      // Do not force a revision
      None,
          
      // Create a forced revision from the document that is currently in store, 
      // BEFORE applying any changes made by the user.  
      // The only exception is a new document, for which a revision will be 
      // created AFTER the update.
      Before
  }

• Sample:

  • By_ID
  • By_Entity

  // Force revision creation by ID
  session.Advanced.Revisions.ForceRevisionCreationFor(companyId);
  session.SaveChanges();

  // Force revision creation by entity
  var company = new Company { 
          Name = "CompanyProfile" 
      };
  session.Store(company);
  companyId = company.Id;
  session.SaveChanges();
  
  // Forcing the creation of a revision by entity can be performed 
  // only when the entity is tracked, after the document is stored.
  session.Advanced.Revisions.ForceRevisionCreationFor<Company>(company);