Revisions: Configuring Revisions



Syntax

ConfigureRevisionsOperation

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

public ConfigureRevisionsOperation(RevisionsConfiguration configuration)
Parameter Type Description
configuration RevisionsConfiguration The Revisions configuration to apply

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.

Usage Flow

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.

Examples

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.

Note that the configuration is applied to the Document Store's default database.
To configure a different database, use the ForDatabase() method.

// 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));