Revisions: Configuring Revisions
-
Use the ConfigureRevisionsOperation Store operation to apply a Revisions configuration to the database.
-
A Revisions configuration includes Default settings and/or Collection-specific configurations.
- The default settings apply to all database collections.
- Collection-specific configurations override the default settings for the collections they are applied to.
-
Default settings and Collection-specific configurations are defined in RevisionsCollectionConfiguration objects.
-
All
RevisionsCollectionConfiguration
objects are gathered in a single RevisionsConfiguration object.
There is oneRevisionsConfiguration
object per database, stored in the database record. -
The
RevisionsConfiguration
object is passed to the ConfigureRevisionsOperation Store operation and applied to the database when the operation is executed, replacing the current Revisions configuration in the database record. -
In this page:
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 -
Thekeys
are collection names.
Thevalues
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 limitnull
MinimumRevisionAgeToKeep TimeSpan Limit the Age of revisions kept per document.
null
= no age limitnull
Disabled bool
If true
, disable revisions Creation and Purgingfalse
PurgeOnDelete bool
If true
, deleting a document will also delete its revisionsfalse
MaximumRevisionsToDeleteUponDocumentUpdate long
The maximum number of revisions to delete upon document update.
null
= no limitnull
- Revisions will be purged if they exceeds either
MinimumRevisionsToKeep
orMinimumRevisionAgeToKeep
. - 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.
- Revisions will be purged if they exceeds either
Usage Flow
To apply a Revisions configuration to all and/or specific collections, follow these steps:
- Create a RevisionsCollectionConfiguration object for every collection you want to set Revisions for.
- If you want to define default settings, create a
RevisionsCollectionConfiguration
object for them. - Add all the
RevisionsCollectionConfiguration
objects you created to a RevisionsConfiguration object. -
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));