Revisions: Configuring Revisions

ConfigureRevisionsOperation

The ConfigureRevisionsOperation Store operation is used to apply your Revisions configurations.

public ConfigureRevisionsOperation(RevisionsConfiguration configuration)

RevisionsConfiguration

This object contains the default settings that apply to all collections, and a Dictionary of collection-specific configurations that override the default settings for the collections they are defined for.

public class RevisionsConfiguration
{
    public RevisionsCollectionConfiguration Default;
    public Dictionary<string, RevisionsCollectionConfiguration> Collections;
}

• Properties

  Property	Type	Description
  Default	RevisionsCollectionConfiguration	Optional default settings that apply to any collection not specified in Collections
  Collections	Dictionary<string, RevisionsCollectionConfiguration>	A Dictionary of collection-specific configurations, where - The keys are collection names. The values are the corresponding configurations.

RevisionsCollectionConfiguration

This object contains a collection-specific Revisions configuration.
It can also be used to define the default settings for all database collections.

public class RevisionsCollectionConfiguration
{
    public long? MinimumRevisionsToKeep { get; set; }
    public TimeSpan? MinimumRevisionAgeToKeep { get; set; }
    public bool Disabled { get; set; }
    public bool PurgeOnDelete { get; set; }
    public long? MaximumRevisionsToDeleteUponDocumentUpdate { get; set; }
}

• Properties

  Configuration Option	Type	Description	Default
  MinimumRevisionsToKeep	long	Limit the Number of revisions to keep per document. null = no limit	null
  MinimumRevisionAgeToKeep	TimeSpan	Limit the Age of revisions kept per document. null = no age limit	null
  Disabled	bool	If true, disable revisions Creation and Purging	false
  PurgeOnDelete	bool	If true, deleting a document will also delete its revisions	false
  MaximumRevisionsToDeleteUponDocumentUpdate	long	The maximum number of revisions to delete upon document update. null = no limit	null

  • Revisions will be purged if they exceeds either MinimumRevisionsToKeep or MinimumRevisionAgeToKeep.
  • After applying the configuration, revisions are Created and Purged for a document when the document is created, modified, or deleted.
  • Use MaximumRevisionsToDeleteUponDocumentUpdate to limit the number of revisions that RavenDB is allowed to purge each time a document is updated, e.g. when many documents have many revisions pending purging and you prefer that the server would purge them gradually.
    

To apply a Revisions configuration to all and/or specific collections, follow these steps:

1. Create a RevisionsCollectionConfiguration object for every collection you want to set Revisions for.
2. If you want to define default settings, create a RevisionsCollectionConfiguration object for them.
3. Add all the RevisionsCollectionConfiguration objects you created to a RevisionsConfiguration object.
4. Pass the RevisionsConfiguration object to the ConfigureRevisionsOperation Store operation.
   Executing the operation will replace the Revisions configuration in the database record.
   

   If you want to modify the existing configuration rather than replace it,
   retrieve the current configuration and edit it as shown here.
   

Example I - Replace Existing Configuration

In this example, we replace the existing Revisions configuration (if there is one) with our own, applying default settings and two collection-specific configurations.

// Define default settings that will apply to all collections
var defaultRevConfig = new RevisionsCollectionConfiguration()
{
    MinimumRevisionsToKeep = 100,
    MinimumRevisionAgeToKeep = new TimeSpan(days: 7, 0, 0, 0),
    PurgeOnDelete = false,

    // Even if MinimumRevisionsToKeep or MinimumRevisionAgeToKeep are exceeded,
    // purge no more than 15 revisions each time the document is modified.
    MaximumRevisionsToDeleteUponDocumentUpdate = 15
};

// Create a collection-specific configuration
// that will override the default settings for the Employees collection
var employeesRevConfig = new RevisionsCollectionConfiguration()
{
    MinimumRevisionsToKeep = 42,
    MinimumRevisionAgeToKeep = new TimeSpan(hours: 1, minutes: 23, seconds: 45),
    PurgeOnDelete = true
};

// Create a collection-specific configuration
// that will override the default settings for the Products collection
var productsRevConfig = new RevisionsCollectionConfiguration()
{
    Disabled = true
};

// Combine the configurations in a RevisionsConfiguration object
var revConfig = new RevisionsConfiguration()
{
    Default = defaultRevConfig,

    Collections = new Dictionary<string, RevisionsCollectionConfiguration>()
    {
        { "Employees", employeesRevConfig },
        { "Products", productsRevConfig }
    }
};

// Execute the operation to update Revisions settings
documentStore.Maintenance.Send(new ConfigureRevisionsOperation(revConfig));

// Define default settings that will apply to all collections
var defaultRevConfig = new RevisionsCollectionConfiguration()
{
    MinimumRevisionsToKeep = 100,
    MinimumRevisionAgeToKeep = new TimeSpan(days: 7, 0, 0, 0),
    PurgeOnDelete = false,

    // Even if MinimumRevisionsToKeep or MinimumRevisionAgeToKeep are exceeded,
    // purge no more than 15 revisions each time the document is modified.
    MaximumRevisionsToDeleteUponDocumentUpdate = 15
};

// Create a collection-specific configuration
// that will override the default settings for the Employees collection
var employeesRevConfig = new RevisionsCollectionConfiguration()
{
    MinimumRevisionsToKeep = 42,
    MinimumRevisionAgeToKeep = new TimeSpan(hours: 1, minutes: 23, seconds: 45),
    PurgeOnDelete = true
};

// Create a collection-specific configuration
// that will override the default settings for the Products collection
var productsRevConfig = new RevisionsCollectionConfiguration()
{
    Disabled = true
};

// Combine the configurations in a RevisionsConfiguration object
var revConfig = new RevisionsConfiguration()
{
    Default = defaultRevConfig,

    Collections = new Dictionary<string, RevisionsCollectionConfiguration>()
    {
        { "Employees", employeesRevConfig },
        { "Products", productsRevConfig }
    }
};

// Execute the operation to update Revisions settings
await documentStore.Maintenance.SendAsync(new ConfigureRevisionsOperation(revConfig));

Example II - Modify Existing Configuration

In this example, we modify the existing Revisions configuration default settings and collection-specific configurations.

We retrieve the existing configuration from the database record, and check its contents.
If no configuration is found, we define a new configuration.
If a configuration is already defined, we modify the existing configuration.

// Get the current Revisions configuration from the Database Record
RevisionsConfiguration configuration =
    documentStore.Maintenance.Server.Send(
        new GetDatabaseRecordOperation(documentStore.Database)).Revisions;

// if there is no Revisions configuration, we create our own
if (configuration == null)
{
    configuration = new RevisionsConfiguration()
    {
        Default = defaultRevConfig,

        Collections = new Dictionary<string, RevisionsCollectionConfiguration>()
        {
            { "Employees", employeesRevConfig },
            { "Products", productsRevConfig }
        }
    };
}

// If a Revisions configuration already exists, we modify it
else
{
    configuration.Default = defaultRevConfig;

    configuration.Collections["Employees"] = employeesRevConfig;
    configuration.Collections["Products"] = productsRevConfig;
}

// Update the configuration
documentStore.Maintenance.Send(new ConfigureRevisionsOperation(configuration));

// Get the current Revisions configuration from the Database Record
RevisionsConfiguration configuration =
    documentStore.Maintenance.Server.Send(
        new GetDatabaseRecordOperation(documentStore.Database)).Revisions;

// if there is no Revisions configuration, we create our own
if (configuration == null)
{
    configuration = new RevisionsConfiguration()
    {
        Default = defaultRevConfig,

        Collections = new Dictionary<string, RevisionsCollectionConfiguration>()
        {
            { "Employees", employeesRevConfig },
            { "Products", productsRevConfig }
        }
    };
}

// If a Revisions configuration already exists, we modify it
else
{
    configuration.Default = defaultRevConfig;

    configuration.Collections["Employees"] = employeesRevConfig;
    configuration.Collections["Products"] = productsRevConfig;
}

// Update the configuration
await documentStore.Maintenance.SendAsync(new ConfigureRevisionsOperation(configuration));