diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/revisions/overview.dotnet.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/revisions/overview.dotnet.markdown index 1fe3798ace..a1d7177517 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/revisions/overview.dotnet.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/revisions/overview.dotnet.markdown @@ -3,329 +3,281 @@ {NOTE: } -* **Document Revisions** are snapshots of documents and their extensions. - * Revisions can be created for documents **automatically** when the documents - are created, modified, or deleted. - * Revisions can also be created for documents [manually](../../document-extensions/revisions/overview#force-revision-creation). - -* Revisions will be automatically **created** and **purged** for a document - only if the Revisions feature is enabled for the document's collection. - To enable or disable the Revisions feature for collections, and to set - limits for the number of revisions that can be kept per document, - apply a [Revisions configuration](../../document-extensions/revisions/overview#revisions-configuration) - to all and/or specific collections. - -* The trail of revisions created for a document can be inspected to track the changes - made in the document over time, and the document's live version can be reverted to any - of its recorded revisions. - - {INFO: } - Tracking document revisions allows you, for example, to check how an employee's - contract has changed over time, restore a single corrupted document without requiring - a backup file, or conduct a full-scale audit of your data. - {INFO/} - -* Revisions and their configuration can be managed via Client API methods or using Studio. - -* In this page: - * [Revisions Configuration](../../document-extensions/revisions/overview#revisions-configuration) - * [Default Settings and Collection-Specific Configurations](../../document-extensions/revisions/overview#default-settings-and-collection-specific-configurations) - * [Defining a Revisions Configuration](../../document-extensions/revisions/overview#defining-a-revisions-configuration) - * [Revisions Configuration Options](../../document-extensions/revisions/overview#revisions-configuration-options) - * [Revisions Configuration Execution](../../document-extensions/revisions/overview#revisions-configuration-execution) - * [Enabling and Disabling Revisions for Existing Documents](../../document-extensions/revisions/overview#enabling-and-disabling-revisions-for-existing-documents) - * [How it Works](../../document-extensions/revisions/overview#how-it-works) - * [Revisions Storage](../../document-extensions/revisions/overview#revisions-storage) - * [Force Revision Creation](../../document-extensions/revisions/overview#force-revision-creation) +* **Document Revisions** are snapshots of documents and their extensions: + + * The trail of revisions created for a document can be inspected to track changes made in the document over time. + * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions) to any of its recorded revisions. + {INFO: } + For example, tracking document revisions allows you to check how an employee's contract has changed over time, + restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. + {INFO/} + +--- + +* Managed via the Client API or from the Studio, revisions can be created automatically or manually: + + * **Automatic revisions creation**: + When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. + To configure revisions settings, and set limits for the number of revisions retained per document, + apply a [Revisions configuration](../../document-extensions/revisions/overview#revisions-configuration) to all and/or specific collections. + + * **Manual revisions creation**: + When revisions settings are disabled, you can still create revisions manually. + See [Force revision creation](../../document-extensions/revisions/overview#force-revision-creation) below. + +--- + +* In this page: + * [Revisions configuration](../../document-extensions/revisions/overview#revisions-configuration) + * [Defining a revisions configuration](../../document-extensions/revisions/overview#defining-a-revisions-configuration) + * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview#default-settings-and-collection-specific-configurations) + * [Revisions configuration options](../../document-extensions/revisions/overview#revisions-configuration-options) + * [Revisions configuration execution](../../document-extensions/revisions/overview#revisions-configuration-execution) + * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview#enabling-and-disabling-revisions-for-existing-documents) + * [How it works](../../document-extensions/revisions/overview#how-it-works) + * [Revisions storage](../../document-extensions/revisions/overview#revisions-storage) + * [Force revision creation](../../document-extensions/revisions/overview#force-revision-creation) {NOTE/} --- -{PANEL: Revisions Configuration} +{PANEL: Revisions configuration} -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 retained per document. -The Revisions configuration enables or disables the creation and purging -of revisions for documents, and optionally limits the number of revisions -kept 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. -The revision configurations are stored in the database record. +{NOTE: } -{NOTE: Conflict Revisions} -Revisions created for **conflicting documents** are a special case, that is -not covered in this article. +##### Conflict Revisions -* Conflict revisions are **Enabled** by default. -* Read about the conflict revisions API here: - [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration) -* Read about managing conflict revisions via Studio here: - [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions#editing-the-conflicting-document-defaults) +Revisions created for **conflicting documents** are a special case that is not covered in this article. -{NOTE/} +* Conflict revisions are **enabled** by default. +* Read about the conflict revisions API here: + [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration) +* Read about managing conflict revisions via the Studio here: + [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions#editing-the-conflicting-document-defaults) +{NOTE/} --- -#### Default Settings and Collection-Specific Configurations +#### Defining a revisions configuration -The Revisions configuration is comprised of **Default Settings** and/or -**Collection-specific configurations**. +You can apply a revisions configuration using the Studio or the Client API: -* 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. - {NOTE: } - If you apply no default settings, Revisions will be **disabled** for any - collection that a collection-specific configuration is not defined for. - {NOTE/} +* Via Studio: + * Manage the revisions configuration in the [Document Revisions](../../studio/database/settings/document-revisions) settings view. + * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions#revisions-tab) in the Studio's Document View. +* Via Client API: + * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions) _Store_ operation to define and apply a revisions configuration. --- -#### Defining a Revisions Configuration +#### Default settings and collection-specific configurations + +The revisions configuration consists of default settings and/or collection-specific configurations: -You can apply a Revisions configuration using Studio or the Client API. +* **Default settings**: + The default settings apply to all documents for which a collection-specific configuration is not defined. -* Via Studio: - * Manage the Revisions configuration via Studio using the Studio Settings - [Document Revisions](../../studio/database/settings/document-revisions) - page. - * Inspect and manage the revisions created for each document using Studio's - Document View [Revisions tab](../../studio/database/document-extensions/revisions#revisions-tab). -* Via Client API: - [Read here](../../document-extensions/revisions/client-api/operations/configure-revisions) - how to define and apply a Revisions configuration using the `ConfigureRevisionsOperation` - Store operation. +* **Collection-specific configurations**: + Collection-specific configurations apply only to documents of the collections they are defined for, + overriding the default settings for these collections. + {NOTE: } + If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. + {NOTE/} --- -#### Revisions Configuration Options +#### Revisions configuration options -A Revisions configuration defines - +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_. +* 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 here](../../document-extensions/revisions/client-api/operations/configure-revisions#section-2) - about the available configuration options. + +* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions). --- -#### Revisions Configuration Execution +#### Revisions configuration execution -Creating a Revisions configuration does **not** immediately trigger its execution. -Default and collection-specific configurations are executed when - +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. + 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](../../studio/database/settings/document-revisions#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. - {WARNING: } - - * 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. - {WARNING/} + 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. + {WARNING: } + * 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. + {WARNING/} --- -#### Enabling and Disabling Revisions for Existing Documents +#### 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. +* 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. -* **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. +* 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. {PANEL/} -{PANEL: How it Works} +{PANEL: How it works} -Let's play with revisions a little to get a taste of its advantages. +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](../../studio/database/settings/document-revisions) - or the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions) - Store operation. - + Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions) + or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions) _Store_ operation. + ![Enable Revisions for the Users Collection](images\revisions_enable-revisions.png "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](../../studio/database/documents/create-new-document#create-new-document) - or the [session.Store](../../client-api/session/storing-entities#example) method. - + You can create the document in the [Studio](../../studio/database/documents/create-new-document#create-new-document) + or using the [session.Store](../../client-api/session/storing-entities#example) method. + ![Create a Document](images\revisions_create-document.png "Create a Document") -3. **Use Studio to inspect the new document's [Revisions tab](../../studio/database/document-extensions/revisions#revisions-tab)**. - Creating the document also created its first revision. - +3. **Inspect the new document's [Revisions tab](../../studio/database/document-extensions/revisions#revisions-tab)** in the Studio. + Creating the document also created its first revision. + ![Revision for Document Creation](images\revisions_document-created.png "Revision for Document Creation") - - (Click the _See the current document_ button to return to the parent document view.) + + (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. - + This will create a second revision. + ![Revision for Document Modification](images\revisions_modify-document.png "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](../../studio/database/document-extensions/revisions#revisions-bin), - including a new revision (called "Delete-Revision"), created to indicate - that the document was deleted. + Though you deleted the document, its **audit trail** is **not lost**: all revisions were moved to the [Revisions Bin](../../studio/database/document-extensions/revisions#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 - 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](images\revisions_revisions-bin.png "Revisions Bin") + ![Revisions Bin](images\revisions_revisions-bin.png "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. - + 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](images\revisions_restored.png "Restored Revisions") {PANEL/} -{PANEL: Revisions Storage} +{PANEL: Revisions storage} + +##### Revisions storage -### Revisions Documents 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. -* 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 -* **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](../../server/configuration/database-configuration#databases.compression.compressrevisionsdefault) - how to toggle this database option on and off. - * Learn [here](../../server/storage/documents-compression) how to apply Document Compression to revisions. +* By default, revisions are compressed. + This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration#databases.compression.compressrevisionsdefault) configuration key. +* At the database level, revisions compression can be customized via the database record, + as shown in [this example](../../server/storage/documents-compression#set-compression-for-selected-collections). +* 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](../../server/storage/documents-compression). --- -### Revisions Document Extensions Storage +##### Storage of document extensions in revisions Read [here](../../document-extensions/revisions/revisions-and-other-features#revisions-and-time-series) about revisions and **time series**. Read [here](../../document-extensions/revisions/revisions-and-other-features#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features#revisions-and-attachments) about revisions and **attachments**. +Read [here](../../document-extensions/revisions/revisions-and-other-features#revisions-and-attachments) about revisions and **attachments**. {PANEL/} -{PANEL: Force Revision Creation} +{PANEL: Force revision creation} 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. +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 Studio or using the - [ForceRevisionCreationFor](../../document-extensions/revisions/overview#force-revision-creation-via-api) - 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). +* You can force the creation of a revision via the [Studio](../../document-extensions/revisions/overview#force-revision-creation-via-the-studio) + or use the [Client API](../../document-extensions/revisions/overview#force-revision-creation-via-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](../../studio/database/document-extensions/revisions#revisions-bin), + and a "Delete-Revision" will be created. --- -#### Force Revision Creation via Studio +##### Force revision creation via the Studio -To create a revision manually via Studio, use the **Create Revision** button in the -document view's Revisions tab. +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](images\revisions_create-revision-manually.png "Create a revision manually") --- -#### Force Revision Creation via API - -To create a revision manually via the API, use the session `ForceRevisionCreationFor` method. - -`ForceRevisionCreationFor` overloads: -{CODE-BLOCK: csharp} -// Force revision creation by entity. -// Can be used with tracked entities only. -void ForceRevisionCreationFor(T entity, - ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); +##### Force revision creation via the Client API -// Force revision creation by document ID. -void ForceRevisionCreationFor(string id, - ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); -{CODE-BLOCK/} +To create a revision manually via the Client API, use the advanced session `ForceRevisionCreationFor` method, +followed by a call to `SaveChanges`. -* **Parameters**: +**Example**: - | 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` | +{CODE-TABS} +{CODE-TAB:csharp:Force_by_entity ForceRevisionCreationByEntity@DocumentExtensions\Revisions\Revisions.cs /} +{CODE-TAB:csharp:Force_by_ID ForceRevisionCreationByID@DocumentExtensions\Revisions\Revisions.cs /} +{CODE-TABS/} - `ForceRevisionStrategy`: - {CODE-BLOCK: csharp} -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 -} - {CODE-BLOCK/} +**Syntax**: -* **Sample**: - {CODE-TABS} - {CODE-TAB:csharp:By_ID ForceRevisionCreationByID@DocumentExtensions\Revisions\Revisions.cs /} - {CODE-TAB:csharp:By_Entity ForceRevisionCreationByEntity@DocumentExtensions\Revisions\Revisions.cs /} - {CODE-TABS/} +{CODE:csharp syntax_1@DocumentExtensions\Revisions\Revisions.cs /} +| Parameter | Type | Description | +|--------------|------------------------------|--------------------------------------------------------------------------------------------------| +| **entity** | `T` | The tracked entity for which you want to create a revision. | +| **id** | `string` | The ID of the document for which you want to create a revision. | +| **strategy** | `enum ForceRevisionStrategy` | Defines the revision creation strategy (see below).
Default: `ForceRevisionStrategy.Before` | -{NOTE: When the Revisions feature is disabled:} - -Deleting a document that owns a manually-created revision -will not move the revision to the revisions bin. - -* A `delete revision` will Not be created. -* Manual revisions will not be kept in the revisions bin. - -{NOTE/} - +{CODE:csharp syntax_2@DocumentExtensions\Revisions\Revisions.cs /} {PANEL/} @@ -333,16 +285,16 @@ will not move the revision to the revisions bin. ### Document Extensions -* [Revert Revisions](../../document-extensions/revisions/revert-revisions) -* [Revisions and Other Features](../../document-extensions/revisions/revisions-and-other-features) +* [Revert Revisions](../../document-extensions/revisions/revert-revisions) +* [Revisions and Other Features](../../document-extensions/revisions/revisions-and-other-features) ### Client API -* [Revisions: API Overview](../../document-extensions/revisions/client-api/overview) -* [Operations: Configuring Revisions](../../document-extensions/revisions/client-api/operations/configure-revisions) -* [Session: Loading Revisions](../../document-extensions/revisions/client-api/session/loading) +* [Revisions: API Overview](../../document-extensions/revisions/client-api/overview) +* [Operations: Configuring Revisions](../../document-extensions/revisions/client-api/operations/configure-revisions) +* [Session: Loading Revisions](../../document-extensions/revisions/client-api/session/loading) ### Studio -* [Settings: Document Revisions](../../studio/database/settings/document-revisions) +* [Settings: Document Revisions](../../studio/database/settings/document-revisions) * [Document Extensions: Revisions](../../studio/database/document-extensions/revisions) diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/revisions/overview.js.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/revisions/overview.js.markdown new file mode 100644 index 0000000000..970c786009 --- /dev/null +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/revisions/overview.js.markdown @@ -0,0 +1,307 @@ +# Document Revisions Overview +--- + +{NOTE: } + +* **Document Revisions** are snapshots of documents and their extensions: + + * The trail of revisions created for a document can be inspected to track changes made in the document over time. + * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions) to any of its recorded revisions. + {INFO: } + For example, tracking document revisions allows you to check how an employee's contract has changed over time, + restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. + {INFO/} + +--- + +* Managed via the Client API or from the Studio, revisions can be created automatically or manually: + + * **Automatic revisions creation**: + When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. + To configure revisions settings, and set limits for the number of revisions retained per document, + apply a [Revisions configuration](../../document-extensions/revisions/overview#revisions-configuration) to all and/or specific collections. + + * **Manual revisions creation**: + When revisions settings are disabled, you can still create revisions manually. + See [Force revision creation](../../document-extensions/revisions/overview#force-revision-creation) below. + +--- + +* In this page: + * [Revisions configuration](../../document-extensions/revisions/overview#revisions-configuration) + * [Defining a revisions configuration](../../document-extensions/revisions/overview#defining-a-revisions-configuration) + * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview#default-settings-and-collection-specific-configurations) + * [Revisions configuration options](../../document-extensions/revisions/overview#revisions-configuration-options) + * [Revisions configuration execution](../../document-extensions/revisions/overview#revisions-configuration-execution) + * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview#enabling-and-disabling-revisions-for-existing-documents) + * [How it works](../../document-extensions/revisions/overview#how-it-works) + * [Revisions storage](../../document-extensions/revisions/overview#revisions-storage) + * [Force revision creation](../../document-extensions/revisions/overview#force-revision-creation) + +{NOTE/} + +--- + +{PANEL: Revisions configuration} + +* 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. + +{NOTE: } + +##### Conflict Revisions + +Revisions created for **conflicting documents** are a special case that is not covered in this article. + +* Conflict revisions are **enabled** by default. +* Read about the conflict revisions API here: + [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration) +* Read about managing conflict revisions via the Studio here: + [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions#editing-the-conflicting-document-defaults) + +{NOTE/} + +--- + +#### 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](../../studio/database/settings/document-revisions) settings view. + * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions#revisions-tab) in the Studio's Document View. +* Via Client API: + * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions) _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. + {NOTE: } + If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. + {NOTE/} + +--- + +#### 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](../../document-extensions/revisions/client-api/operations/configure-revisions). + +--- + +#### 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](../../studio/database/settings/document-revisions#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. + {WARNING: } + * 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. + {WARNING/} + +--- + +#### 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. + +{PANEL/} + +{PANEL: How it works} + +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](../../studio/database/settings/document-revisions) + or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions) _Store_ operation. + + ![Enable Revisions for the Users Collection](images\revisions_enable-revisions.png "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](../../studio/database/documents/create-new-document#create-new-document) + or using the [session.Store](../../client-api/session/storing-entities#example) method. + + ![Create a Document](images\revisions_create-document.png "Create a Document") + +3. **Inspect the new document's [Revisions tab](../../studio/database/document-extensions/revisions#revisions-tab)** in the Studio. + Creating the document also created its first revision. + + ![Revision for Document Creation](images\revisions_document-created.png "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](images\revisions_modify-document.png "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](../../studio/database/document-extensions/revisions#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](images\revisions_revisions-bin.png "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](images\revisions_restored.png "Restored Revisions") + +{PANEL/} + +{PANEL: Revisions storage} + +##### 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](../../server/configuration/database-configuration#databases.compression.compressrevisionsdefault) configuration key. +* At the database level, revisions compression can be customized via the database record, + as shown in [this example](../../server/storage/documents-compression#set-compression-for-selected-collections). +* 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](../../server/storage/documents-compression). + +--- + +##### Storage of document extensions in revisions + +Read [here](../../document-extensions/revisions/revisions-and-other-features#revisions-and-time-series) about revisions and **time series**. +Read [here](../../document-extensions/revisions/revisions-and-other-features#revisions-and-counters) about revisions and **counters**. +Read [here](../../document-extensions/revisions/revisions-and-other-features#revisions-and-attachments) about revisions and **attachments**. + +{PANEL/} + +{PANEL: Force revision creation} + +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](../../document-extensions/revisions/overview#force-revision-creation-via-the-studio) + or use the [Client API](../../document-extensions/revisions/overview#force-revision-creation-via-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](../../studio/database/document-extensions/revisions#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](images\revisions_create-revision-manually.png "Create a revision manually") + +--- + +##### Force revision creation via the Client API + +To create a revision manually via the Client API, use the advanced session `forceRevisionCreationFor` method, +followed by a call to `saveChanges`. + +**Example**: + +{CODE-TABS} +{CODE-TAB:nodejs:Force_by_entity force_revision_creation_by_entity@documentExtensions\revisions\forceRevisionCreation.js /} +{CODE-TAB:nodejs:Force_by_id force_revision_creation_by_id@documentExtensions\revisions\forceRevisionCreation.js /} +{CODE-TABS/} + +**Syntax**: + +{CODE:nodejs syntax_1@documentExtensions\revisions\forceRevisionCreation.js /} + +| Parameter | Type | Description | +|--------------|----------|-------------------------------------------------------------------------------------------------| +| **entity** | `object` | The tracked entity for which you want to create a revision. | +| **id** | `string` | The ID of the document for which you want to create a revision. | +| **strategy** | `string` | Defines the revision creation strategy.
Can be `"None"` or `"Before"`
Default: `"Before"` | + +**Strategy**: + +`None`: +Do not force a revision + +`Before`: +Create a forced revision from the document currently in store BEFORE applying any changes made by the user. +The only exception is for a new document, where a revision will be created AFTER the update. + +{PANEL/} + +## Related Articles + +### Document Extensions + +* [Revert Revisions](../../document-extensions/revisions/revert-revisions) +* [Revisions and Other Features](../../document-extensions/revisions/revisions-and-other-features) + +### Client API + +* [Revisions: API Overview](../../document-extensions/revisions/client-api/overview) +* [Operations: Configuring Revisions](../../document-extensions/revisions/client-api/operations/configure-revisions) +* [Session: Loading Revisions](../../document-extensions/revisions/client-api/session/loading) + +### Studio + +* [Settings: Document Revisions](../../studio/database/settings/document-revisions) +* [Document Extensions: Revisions](../../studio/database/document-extensions/revisions) diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/revisions/overview.python.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/revisions/overview.python.markdown index 190708ae4b..5f41dc282f 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/revisions/overview.python.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/revisions/overview.python.markdown @@ -3,285 +3,294 @@ {NOTE: } -* **Document Revisions** are snapshots of documents and their extensions. - * Revisions can be created for documents **automatically** when the documents - are created, modified, or deleted. - * Revisions can also be created for documents [manually](../../document-extensions/revisions/overview#force-revision-creation). - -* Revisions will be automatically **created** and **purged** for a document - only if the Revisions feature is enabled for the document's collection. - To enable or disable the Revisions feature for collections, and to set - limits for the number of revisions that can be kept per document, - apply a [Revisions configuration](../../document-extensions/revisions/overview#revisions-configuration) - to all and/or specific collections. - -* The trail of revisions created for a document can be inspected to track the changes - made in the document over time, and the document's live version can be reverted to any - of its recorded revisions. - - {INFO: } - Tracking document revisions allows you, for example, to check how an employee's - contract has changed over time, restore a single corrupted document without requiring - a backup file, or conduct a full-scale audit of your data. - {INFO/} - -* Revisions and their configuration can be managed via Client API methods or using Studio. - -* In this page: - * [Revisions Configuration](../../document-extensions/revisions/overview#revisions-configuration) - * [Default Settings and Collection-Specific Configurations](../../document-extensions/revisions/overview#default-settings-and-collection-specific-configurations) - * [Defining a Revisions Configuration](../../document-extensions/revisions/overview#defining-a-revisions-configuration) - * [Revisions Configuration Options](../../document-extensions/revisions/overview#revisions-configuration-options) - * [Revisions Configuration Execution](../../document-extensions/revisions/overview#revisions-configuration-execution) - * [Enabling and Disabling Revisions for Existing Documents](../../document-extensions/revisions/overview#enabling-and-disabling-revisions-for-existing-documents) - * [How it Works](../../document-extensions/revisions/overview#how-it-works) - * [Revisions Storage](../../document-extensions/revisions/overview#revisions-storage) - * [Force Revision Creation](../../document-extensions/revisions/overview#force-revision-creation) +* **Document Revisions** are snapshots of documents and their extensions: + + * The trail of revisions created for a document can be inspected to track changes made in the document over time. + * A document's live version can be [reverted](../../document-extensions/revisions/revert-revisions) to any of its recorded revisions. + {INFO: } + For example, tracking document revisions allows you to check how an employee's contract has changed over time, + restore a single corrupted document without requiring a backup file, or conduct a full-scale audit of your data. + {INFO/} + +--- + +* Managed via the Client API or from the Studio, revisions can be created automatically or manually: + + * **Automatic revisions creation**: + When revisions settings are defined and enabled for a collection, a document revision is automatically created whenever documents are created, modified, or deleted. + To configure revisions settings, and set limits for the number of revisions retained per document, + apply a [Revisions configuration](../../document-extensions/revisions/overview#revisions-configuration) to all and/or specific collections. + + * **Manual revisions creation**: + When revisions settings are disabled, you can still create revisions manually. + See [Force revision creation](../../document-extensions/revisions/overview#force-revision-creation) below. + +--- + +* In this page: + * [Revisions configuration](../../document-extensions/revisions/overview#revisions-configuration) + * [Defining a revisions configuration](../../document-extensions/revisions/overview#defining-a-revisions-configuration) + * [Default settings and collection-specific configurations](../../document-extensions/revisions/overview#default-settings-and-collection-specific-configurations) + * [Revisions configuration options](../../document-extensions/revisions/overview#revisions-configuration-options) + * [Revisions configuration execution](../../document-extensions/revisions/overview#revisions-configuration-execution) + * [Enabling and disabling revisions for existing documents](../../document-extensions/revisions/overview#enabling-and-disabling-revisions-for-existing-documents) + * [How it works](../../document-extensions/revisions/overview#how-it-works) + * [Revisions storage](../../document-extensions/revisions/overview#revisions-storage) + * [Force revision creation](../../document-extensions/revisions/overview#force-revision-creation) {NOTE/} --- -{PANEL: Revisions Configuration} +{PANEL: Revisions configuration} + +* 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 change this behavior, and other Revisions settings, by applying -a Revisions Configuration to the database. +* 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. -The Revisions configuration enables or disables the creation and purging -of revisions for documents, and optionally limits the number of revisions -kept per document. +{NOTE: } -The revision configurations are stored in the database record. +##### Conflict Revisions -{NOTE: Conflict Revisions} -Revisions created for **conflicting documents** are a special case, that is -not covered in this article. +Revisions created for **conflicting documents** are a special case that is not covered in this article. -* Conflict revisions are **Enabled** by default. -* Read about the conflict revisions API here: - [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration) -* Read about managing conflict revisions via Studio here: - [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions#editing-the-conflicting-document-defaults) +* Conflict revisions are **enabled** by default. +* Read about the conflict revisions API here: + [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration) +* Read about managing conflict revisions via the Studio here: + [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions#editing-the-conflicting-document-defaults) {NOTE/} - --- -#### Default Settings and Collection-Specific Configurations +#### Defining a revisions configuration -The Revisions configuration is comprised of **Default Settings** and/or -**Collection-specific configurations**. +You can apply a revisions configuration using the Studio or the Client API: -* 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. - {NOTE: } - If you apply no default settings, Revisions will be **disabled** for any - collection that a collection-specific configuration is not defined for. - {NOTE/} +* Via Studio: + * Manage the revisions configuration in the [Document Revisions](../../studio/database/settings/document-revisions) settings view. + * Inspect existing revisions and manually create a new revision in the [Revisions tab](../../studio/database/document-extensions/revisions#revisions-tab) in the Studio's Document View. +* Via Client API: + * Use the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions) _Store_ operation to define and apply a revisions configuration. --- -#### Defining a Revisions Configuration +#### Default settings and collection-specific configurations -You can apply a Revisions configuration using Studio or the Client API. +The revisions configuration consists of default settings and/or collection-specific configurations: -* Via Studio: - * Manage the Revisions configuration via Studio using the Studio Settings - [Document Revisions](../../studio/database/settings/document-revisions) - page. - * Inspect and manage the revisions created for each document using Studio's - Document View [Revisions tab](../../studio/database/document-extensions/revisions#revisions-tab). -* Via Client API: - [Read here](../../document-extensions/revisions/client-api/operations/configure-revisions) - how to define and apply a Revisions configuration using the `ConfigureRevisionsOperation` - Store operation. +* **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. + {NOTE: } + If no default settings are applied, revisions will be **disabled** for any collection where a collection-specific configuration is not defined. + {NOTE/} --- -#### Revisions Configuration Options +#### Revisions configuration options -A Revisions configuration defines - +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_. +* 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 here](../../document-extensions/revisions/client-api/operations/configure-revisions#section-2) - about the available configuration options. + +* Learn more about the available configuration options in [Configure revisions operations](../../document-extensions/revisions/client-api/operations/configure-revisions). --- -#### Revisions Configuration Execution +#### Revisions configuration execution -Creating a Revisions configuration does **not** immediately trigger its execution. -Default and collection-specific configurations are executed when - +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. + 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](../../studio/database/settings/document-revisions#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. - {WARNING: } - - * 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. - {WARNING/} + 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. + {WARNING: } + * 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. + {WARNING/} --- -#### Enabling and Disabling Revisions for Existing Documents +#### 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. +* 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. -* **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. +* 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. {PANEL/} -{PANEL: How it Works} +{PANEL: How it works} -Let's play with revisions a little to get a taste of its advantages. +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](../../studio/database/settings/document-revisions) - or the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions) - Store operation. - + Revisions can be enabled from the [Studio](../../studio/database/settings/document-revisions) + or using the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions) _Store_ operation. + ![Enable Revisions for the Users Collection](images\revisions_enable-revisions.png "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](../../studio/database/documents/create-new-document#create-new-document) - or the [session.Store](../../client-api/session/storing-entities#example) method. - + You can create the document in the [Studio](../../studio/database/documents/create-new-document#create-new-document) + or using the [session.Store](../../client-api/session/storing-entities#example) method. + ![Create a Document](images\revisions_create-document.png "Create a Document") -3. **Use Studio to inspect the new document's [Revisions tab](../../studio/database/document-extensions/revisions#revisions-tab)**. - Creating the document also created its first revision. - +3. **Inspect the new document's [Revisions tab](../../studio/database/document-extensions/revisions#revisions-tab)** in the Studio. + Creating the document also created its first revision. + ![Revision for Document Creation](images\revisions_document-created.png "Revision for Document Creation") - - (Click the _See the current document_ button to return to the parent document view.) + + (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. - + This will create a second revision. + ![Revision for Document Modification](images\revisions_modify-document.png "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](../../studio/database/document-extensions/revisions#revisions-bin), - including a new revision (called "Delete-Revision"), created to indicate - that the document was deleted. + Though you deleted the document, its **audit trail** is **not lost**: all revisions were moved to the [Revisions Bin](../../studio/database/document-extensions/revisions#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 - 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](images\revisions_revisions-bin.png "Revisions Bin") + ![Revisions Bin](images\revisions_revisions-bin.png "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. - + 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](images\revisions_restored.png "Restored Revisions") {PANEL/} -{PANEL: Revisions Storage} +{PANEL: Revisions storage} + +##### Revisions storage -### Revisions Documents 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. + +--- -* 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 -* **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](../../server/configuration/database-configuration#databases.compression.compressrevisionsdefault) - how to toggle this database option on and off. - * Learn [here](../../server/storage/documents-compression) how to apply Document Compression to revisions. +* By default, revisions are compressed. + This setting can be customized server-wide via the [CompressRevisionsDefault](../../server/configuration/database-configuration#databases.compression.compressrevisionsdefault) configuration key. +* At the database level, revisions compression can be customized via the database record, + as shown in [this example](../../server/storage/documents-compression#set-compression-for-selected-collections). +* 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](../../server/storage/documents-compression). --- -### Revisions Document Extensions Storage +##### Storage of document extensions in revisions Read [here](../../document-extensions/revisions/revisions-and-other-features#revisions-and-time-series) about revisions and **time series**. Read [here](../../document-extensions/revisions/revisions-and-other-features#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features#revisions-and-attachments) about revisions and **attachments**. +Read [here](../../document-extensions/revisions/revisions-and-other-features#revisions-and-attachments) about revisions and **attachments**. {PANEL/} -{PANEL: Force Revision Creation} +{PANEL: Revisions storage} -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. +{NOTE: } + +##### 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. -* You can force the creation of a revision via Studio or using the - [ForceRevisionCreationFor](../../document-extensions/revisions/overview#force-revision-creation-via-api) - 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). +* **Revisions compression** + * Revisions are compressed by default. + Learn [here](../../server/configuration/database-configuration#databases.compression.compressrevisionsdefault) + how to toggle this database option on and off. + * Learn [here](../../server/storage/documents-compression) how to apply Document Compression to revisions. + * Individual fields are compressed as they are compressed in regular documents: + any text field of more than 128 bytes is compressed. +{NOTE/} +{NOTE: } + +##### Revisions document extensions storage --- -#### Force Revision Creation via Studio +Read [here](../../document-extensions/revisions/revisions-and-other-features#revisions-and-time-series) about revisions and **time series**. +Read [here](../../document-extensions/revisions/revisions-and-other-features#revisions-and-counters) about revisions and **counters**. +Read [here](../../document-extensions/revisions/revisions-and-other-features#revisions-and-attachments) about revisions and **attachments**. + +{NOTE/} +{PANEL/} -To create a revision manually via Studio, use the **Create Revision** button in the -document view's Revisions tab. +{PANEL: Force revision creation} -![Create a revision manually](images\revisions_create-revision-manually.png "Create a revision manually") +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](../../document-extensions/revisions/overview#force-revision-creation-via-the-studio) + or use the [Client API](../../document-extensions/revisions/overview#force-revision-creation-via-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](../../studio/database/document-extensions/revisions#revisions-bin), + and a "Delete-Revision" will be created. --- -#### Force Revision Creation via API +##### Force revision creation via the Studio -To create a revision manually via the API, use the advanced session `force_revision_creation_for` method. -{CODE:python force_revision_creation_for@DocumentExtensions\Revisions\Revisions.py /} +To create a revision manually via the Studio, +click the **Create Revision** button in the Revisions tab in the document view. -{NOTE: When the Revisions feature is disabled:} -Deleting a document that owns a manually-created revision will not move the revision to the revisions bin. +![Create a revision manually](images\revisions_create-revision-manually.png "Create a revision manually") -* A `delete revision` will Not be created. -* Manual revisions will not be kept in the revisions bin. +--- -{NOTE/} +##### Force revision creation via the Client API + +To create a revision manually via the API, use the advanced session `force_revision_creation_for` method. + +{CODE:python force_revision_creation_for@DocumentExtensions\Revisions\Revisions.py /} {PANEL/} @@ -289,16 +298,16 @@ Deleting a document that owns a manually-created revision will not move the revi ### Document Extensions -* [Revert Revisions](../../document-extensions/revisions/revert-revisions) -* [Revisions and Other Features](../../document-extensions/revisions/revisions-and-other-features) +* [Revert Revisions](../../document-extensions/revisions/revert-revisions) +* [Revisions and Other Features](../../document-extensions/revisions/revisions-and-other-features) ### Client API -* [Revisions: API Overview](../../document-extensions/revisions/client-api/overview) -* [Operations: Configuring Revisions](../../document-extensions/revisions/client-api/operations/configure-revisions) -* [Session: Loading Revisions](../../document-extensions/revisions/client-api/session/loading) +* [Revisions: API Overview](../../document-extensions/revisions/client-api/overview) +* [Operations: Configuring Revisions](../../document-extensions/revisions/client-api/operations/configure-revisions) +* [Session: Loading Revisions](../../document-extensions/revisions/client-api/session/loading) ### Studio -* [Settings: Document Revisions](../../studio/database/settings/document-revisions) +* [Settings: Document Revisions](../../studio/database/settings/document-revisions) * [Document Extensions: Revisions](../../studio/database/document-extensions/revisions) diff --git a/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/click-revision.png b/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/click-revision.png new file mode 100644 index 0000000000..2db760aea2 Binary files /dev/null and b/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/click-revision.png differ diff --git a/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/click-to-compare.png b/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/click-to-compare.png new file mode 100644 index 0000000000..8b302f71bf Binary files /dev/null and b/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/click-to-compare.png differ diff --git a/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/compare-with-drop-list.png b/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/compare-with-drop-list.png new file mode 100644 index 0000000000..f351b0e8ab Binary files /dev/null and b/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/compare-with-drop-list.png differ diff --git a/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/document-revisions.png b/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/document-revisions.png new file mode 100644 index 0000000000..1f7685e81c Binary files /dev/null and b/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/document-revisions.png differ diff --git a/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/orphaned-revisions.png b/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/orphaned-revisions.png new file mode 100644 index 0000000000..ac799fc204 Binary files /dev/null and b/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/orphaned-revisions.png differ diff --git a/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/restored-revisions.png b/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/restored-revisions.png new file mode 100644 index 0000000000..a5cfc3d67e Binary files /dev/null and b/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/restored-revisions.png differ diff --git a/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/revision-comparison.png b/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/revision-comparison.png new file mode 100644 index 0000000000..e3c1053192 Binary files /dev/null and b/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/revision-comparison.png differ diff --git a/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/revision-inspection.png b/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/revision-inspection.png new file mode 100644 index 0000000000..ecfea6f827 Binary files /dev/null and b/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/revision-inspection.png differ diff --git a/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/revisions-bin.png b/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/revisions-bin.png new file mode 100644 index 0000000000..f54c3a66d8 Binary files /dev/null and b/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/images/revisions/revisions-bin.png differ diff --git a/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/revisions.markdown b/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/revisions.markdown new file mode 100644 index 0000000000..fa5c9552d3 --- /dev/null +++ b/Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/revisions.markdown @@ -0,0 +1,174 @@ +# Document Extensions: Revisions +--- + +{NOTE: } + +* **Document Revisions** are snapshots of documents that can be created manually or automatically when a document is created, modified, or deleted. + Revisions can be used for data auditing, instant restoration after document corruption, and other purposes. + +* Learn more about document revisions in this [document revisions overview](../../../document-extensions/revisions/overview): + * To define and enable revisions creation, see [revisions configuration](../../../document-extensions/revisions/overview#revisions-configuration). + * A dynamic walkthrough demonstrating revisions management is available [here](../../../document-extensions/revisions/overview#how-it-works). + +* This article provides an overview of the Studio views related to working with revisions, including: + * Viewing revisions + * Comparing revisions + * Viewing revisions for deleted documents (Revisions Bin) + +--- + +* In this page: + * [Revisions Tab](../../../studio/database/document-extensions/revisions#revisions-tab) + * [Revision inspection](../../../studio/database/document-extensions/revisions#revision-inspection) + * [Revisions comparison](../../../studio/database/document-extensions/revisions#revisions-comparison) + * [Revisions Bin](../../../studio/database/document-extensions/revisions#revisions-bin) + * [Restoring revisions](../../../studio/database/document-extensions/revisions#restoring-revisions) + +{NOTE/} + +--- + +{PANEL: Revisions Tab} + +* Located within the Document View, + the Revisions Tab displays the full trail of all revisions created for the document. +* From this tab, you can inspect each revision, manually force the creation of a new revision, + and compare revisions to the live document version and to other revisions. + +![Revisions Tab](images/revisions/document-revisions.png "Revisions Tab") + +1. [Document View](../../../studio/database/documents/document-view) > **Revisions tab** + Click to display the document's revisions tab. + Revisions are listed in the revisions tab by their creation time signatures. + The current number of revisions is displayed in the tab header. +2. **Create revision** + Click to manually create a new revision for this document from the Studio. + A new revision will be created if the document doesn't already have a revision for the latest content. + [Learn here](../../../document-extensions/revisions/overview#force-revision-creation-via-the-client-api) about forcing the creation of a new revision via the Client API. +3. **Revision timestamp** + Click to inspect this revision. +4. **Compare revision** + Click to compare this revision with the current live version of the document and with other revisions. + +{PANEL/} + +{PANEL: Revision inspection} + +Click the revision timestamp to inspect the revision's contents: + +![Click to Inspect](images/revisions/click-revision.png "Click to Inspect") + +--- + +The revision will be visible in the Document View, +but file editing will Not be available since revisions cannot be modified. + +![Revision Inspection](images/revisions/revision-inspection.png "Revision Inspection") + +1. **Revision** + The REVISION label indicates that you are viewing a revision and not + the parent document. +2. **Clone** + Click to create a document that copies the revision's contents. + {INFO: } + * Cloning the revision will open the 'new document view' with this revision's contents. + * You can then save the clone under a new name to create a new document. + * Saving the clone with the exact same ID as the revision's parent document will revert the document to this revision. + {INFO/} +3. **See the current document** + Click to return to the revision's parent document view. +4. **Revision contents** + The content of the revision is displayed in read-only mode. + +{PANEL/} + + +{PANEL: Revisions comparison} + +Click the revision's comparison button to compare it with other revisions: + +![Click to Compare](images/revisions/click-to-compare.png "Click to Compare") + +--- + +![Revision Comparison](images/revisions/revision-comparison.png "Revision Comparison") + +1. **Exit revisions compare mode** + Click to exit the comparison window and return to the revisions tTab in the Document View. +2. **Compare with** + Click to select a revision to compare with. + ![Compare-with Drop List](images/revisions/compare-with-drop-list.png "Compare-with Drop List") +3. **Left-hand revision** + The left-hand view displays the revision selected in the revisions tab. +4. **Right-hand revision** + The right-hand view displays the revision selected using the "Compare with" drop-down list. +5. **Summary line** + This line summarizes the differences found between the two revisions. + +{PANEL/} + +{PANEL: Revisions Bin} + +* This view displays the revisions of deleted documents. + +* When a document is deleted: + * A "delete-revision" is created for the document, marking its deletion. + * The "delete-revision" and all the document's revisions - whether automatically created due to the defined revisions configuration or manually created - are moved to the Revisions Bin. + * This applies regardless of whether a [revisions configuration](../../../document-extensions/revisions/overview#revisions-configuration) is enabled or disabled. + +![Revisions Bin](images/revisions/revisions-bin.png "Revisions Bin") + +1. **Revisions Bin** + Click to open the Revisions Bin view. + Each item listed in the Revisions Bin view references all the revisions created for a deleted document. +2. **Selection boxes** + Check to select items. +3. **Delete** + Click to remove selected items. + Deleting revisions from the Revisions Bin will permanently dispose of these revisions, + making them irrecoverable. +4. **Deleted document ID** + This is the ID of the document that was deleted. + Click it to inspect the revisions created for this document, + known as "orphaned revisions" since their parent document has been deleted. + ![Orphaned Revisions](images/revisions/orphaned-revisions.png "Orphaned Revisions") + * Revisions stored in the revisions bin can be [inspected](../../../studio/database/document-extensions/revisions#revision-inspection) + and cloned just like the revisions of a live document. +5. **Change vector** + The change vector of the revision that was created for the document when it was deleted. +6. **Deletion date** + The date/time when the document was deleted. + +--- + +### Restoring revisions + +Giving a **new document** the ID of a deleted document whose revisions are kept in the Revisions Bin, +will restore the revisions from the bin and add them 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](images/revisions/restored-revisions.png "Restored Revisions") + +{PANEL/} + +## Related Articles + +### Document Extensions + +* [Document Revisions Overview](../../../document-extensions/revisions/overview) +* [Revert Revisions](../../../document-extensions/revisions/revert-revisions) +* [Revisions and Other Features](../../../document-extensions/revisions/revisions-and-other-features) + +### Client API + +* [Revisions: API Overview](../../../document-extensions/revisions/client-api/overview) +* [Operations: Configuring Revisions](../../../document-extensions/revisions/client-api/operations/configure-revisions) +* [Session: Loading Revisions](../../../document-extensions/revisions/client-api/session/loading) +* [Session: Including Revisions](../../../document-extensions/revisions/client-api/session/including) +* [Session: Counting Revisions](../../../document-extensions/revisions/client-api/session/counting) + +### Studio + +* [Settings: Document Revisions](../../../studio/database/settings/document-revisions) diff --git a/Documentation/5.4/Samples/csharp/Raven.Documentation.Samples/DocumentExtensions/Revisions/Revisions.cs b/Documentation/5.4/Samples/csharp/Raven.Documentation.Samples/DocumentExtensions/Revisions/Revisions.cs index 8bb37ef939..604ff01e08 100644 --- a/Documentation/5.4/Samples/csharp/Raven.Documentation.Samples/DocumentExtensions/Revisions/Revisions.cs +++ b/Documentation/5.4/Samples/csharp/Raven.Documentation.Samples/DocumentExtensions/Revisions/Revisions.cs @@ -1,14 +1,13 @@ using System; using System.Collections.Generic; -using System.Linq; using System.Threading.Tasks; using Raven.Client; using Raven.Client.Documents; -using Raven.Client.Documents.Operations.Indexes; using Raven.Client.Documents.Operations.Revisions; using Raven.Client.Documents.Session; using Raven.Client.Json; using Raven.Documentation.Samples.Orders; +using Xunit; namespace Raven.Documentation.Samples.Server { @@ -76,14 +75,14 @@ await store.Maintenance.SendAsync(new ConfigureRevisionsOperation(new RevisionsC .GetMetadataFor("users/1", start: 0, pageSize: 25); // Get revisions by their change vectors - User revison = session + User revision = session .Advanced .Revisions .Get(revisionsMetadata[0].GetString(Constants.Documents.Metadata.ChangeVector)); // Get a revision by its creation time // If no revision was created at that precise time, get the first revision to precede it - User revisonAtYearAgo = session + User revisionAtYearAgo = session .Advanced .Revisions .Get("users/1", DateTime.Now.AddYears(-1)); @@ -101,9 +100,12 @@ public async Task ForceRevisionCreationForSample() { #region ForceRevisionCreationByEntity // Force revision creation by entity + // ================================= + var company = new Company { - Name = "CompanyProfile" + Name = "CompanyName" }; + session.Store(company); companyId = company.Id; session.SaveChanges(); @@ -111,6 +113,12 @@ public async Task ForceRevisionCreationForSample() // 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); + + // Call SaveChanges for the revision to be created + session.SaveChanges(); + + var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; + Assert.Equal(1, revisionsCount); #endregion } @@ -118,11 +126,14 @@ public async Task ForceRevisionCreationForSample() { #region ForceRevisionCreationByID // Force revision creation by ID + // ============================= + session.Advanced.Revisions.ForceRevisionCreationFor(companyId); session.SaveChanges(); - #endregion var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; + Assert.Equal(1, revisionsCount); + #endregion } } } @@ -137,6 +148,36 @@ public class Company public string Phone { get; set; } public string Fax { get; set; } } - + + private interface IFoo + { + #region syntax_1 + // Available overloads: + // ==================== + + // Force revision creation by entity. + // Can be used with tracked entities only. + void ForceRevisionCreationFor(T entity, + ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); + + // Force revision creation by document ID. + void ForceRevisionCreationFor(string id, + ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); + #endregion + + #region syntax_2 + public enum ForceRevisionStrategy + { + // Do not force a revision + None, + + // Create a forced revision from the document currently in store + // BEFORE applying any changes made by the user. + // The only exception is for a new document, + // where a revision will be created AFTER the update. + Before + } + #endregion + } } } diff --git a/Documentation/5.4/Samples/nodejs/documentExtensions/revisions/forceRevisionCreation.js b/Documentation/5.4/Samples/nodejs/documentExtensions/revisions/forceRevisionCreation.js new file mode 100644 index 0000000000..d30dcec58c --- /dev/null +++ b/Documentation/5.4/Samples/nodejs/documentExtensions/revisions/forceRevisionCreation.js @@ -0,0 +1,61 @@ +import { DocumentStore } from "ravendb"; + +const documentStore = new DocumentStore(); + +async function forceRevisionCreation() { + { + //region force_revision_creation_by_entity + // Force revision creation by entity + // ================================= + + const company = new Company(); + company.name = "CompanyName"; + + const session = documentStore.openSession(); + await session.store(company); + await session.saveChanges(); + + // Forcing the creation of a revision by entity can be performed + // only when the entity is tracked, after the document is stored. + await session.advanced.revisions.forceRevisionCreationFor(company); + + // Must call 'saveChanges' for the revision to be created + await session.saveChanges(); + + // Get existing revisions: + const revisions = await session.advanced.revisions.getFor(company.id); + const revisionsCount = revisions.length; + + assert.equal(revisionsCount, 1); + //endregion + } + { + //region force_revision_creation_by_id + const company = new Company(); + company.name = "CompanyName"; + + const session = documentStore.openSession(); + await session.store(company); + await session.saveChanges(); + + // Force revision creation by ID + const companyId = company.id; + await session.advanced.revisions.forceRevisionCreationFor(companyId); + await session.saveChanges(); + + const revisions = await session.advanced.revisions.getFor(company.id); + const revisionsCount = revisions.length; + + assert.equal(revisionsCount, 1); + //endregion + } +} + +//region syntax_1 +// Available overloads: +// ==================== +forceRevisionCreationFor(entity); +forceRevisionCreationFor(entity, strategy); +forceRevisionCreationFor(id); +forceRevisionCreationFor(id, strategy); +//endregion diff --git a/Documentation/5.4/Samples/python/DocumentExtensions/Revisions/Revisions.py b/Documentation/5.4/Samples/python/DocumentExtensions/Revisions/Revisions.py index 054a9a2419..28e8b4ca44 100644 --- a/Documentation/5.4/Samples/python/DocumentExtensions/Revisions/Revisions.py +++ b/Documentation/5.4/Samples/python/DocumentExtensions/Revisions/Revisions.py @@ -1,26 +1,23 @@ -from examples_base import ExampleBase, Company +from ravendb.primitives import constants + +from examples_base import ExampleBase class Force(ExampleBase): def setUp(self): super().setUp() - def test_force_revision_creation_for(self): - with self.embedded_server.get_document_store("ForceRevision") as store: - with store.open_session() as session: - self.add_companies(session) - company_id = "companies/1" - # region force_revision_creation_for - with store.open_session() as session: - company = session.load(company_id, Company) - company.name = "HR V2" + # region force_revision_creation_for + 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() + session.advanced.revisions.force_revision_creation_for(company) + session.save_changes() - revisions = session.advanced.revisions.get_for(company.Id, Company) - revisions_count = len(revisions) + 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 V2", revisions[1].name) - # endregion + self.assertEqual(1, revisions_count) + # Assert revision contains the value 'Before' the changes... + self.assertEqual("HR", revisions[0].name) + # endregion diff --git a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_create-document.png b/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_create-document.png deleted file mode 100644 index d02fe2a4ec..0000000000 Binary files a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_create-document.png and /dev/null differ diff --git a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_create-document.snag b/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_create-document.snag deleted file mode 100644 index 46f8cece0b..0000000000 Binary files a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_create-document.snag and /dev/null differ diff --git a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_create-revision-manually.png b/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_create-revision-manually.png deleted file mode 100644 index f725f5014b..0000000000 Binary files a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_create-revision-manually.png and /dev/null differ diff --git a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_create-revision-manually.snag b/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_create-revision-manually.snag deleted file mode 100644 index 0db6a56f31..0000000000 Binary files a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_create-revision-manually.snag and /dev/null differ diff --git a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_document-created.png b/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_document-created.png deleted file mode 100644 index 0a2d42bb63..0000000000 Binary files a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_document-created.png and /dev/null differ diff --git a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_document-created.snag b/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_document-created.snag deleted file mode 100644 index 8800f19ce5..0000000000 Binary files a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_document-created.snag and /dev/null differ diff --git a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_enable-revisions.png b/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_enable-revisions.png deleted file mode 100644 index 85c2278f2d..0000000000 Binary files a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_enable-revisions.png and /dev/null differ diff --git a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_enable-revisions.snag b/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_enable-revisions.snag deleted file mode 100644 index 3146832329..0000000000 Binary files a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_enable-revisions.snag and /dev/null differ diff --git a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_modify-document.png b/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_modify-document.png deleted file mode 100644 index 730a9505de..0000000000 Binary files a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_modify-document.png and /dev/null differ diff --git a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_modify-document.snag b/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_modify-document.snag deleted file mode 100644 index ac148466ff..0000000000 Binary files a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_modify-document.snag and /dev/null differ diff --git a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_restored.png b/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_restored.png deleted file mode 100644 index 263521c478..0000000000 Binary files a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_restored.png and /dev/null differ diff --git a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_restored.snag b/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_restored.snag deleted file mode 100644 index 302e020ba9..0000000000 Binary files a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_restored.snag and /dev/null differ diff --git a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_revisions-bin.png b/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_revisions-bin.png deleted file mode 100644 index 33d11b5a2d..0000000000 Binary files a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_revisions-bin.png and /dev/null differ diff --git a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_revisions-bin.snag b/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_revisions-bin.snag deleted file mode 100644 index a6793eaabf..0000000000 Binary files a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/images/revisions_revisions-bin.snag and /dev/null differ diff --git a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/overview.dotnet.markdown b/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/overview.dotnet.markdown deleted file mode 100644 index 1fe3798ace..0000000000 --- a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/overview.dotnet.markdown +++ /dev/null @@ -1,348 +0,0 @@ -# Document Revisions Overview ---- - -{NOTE: } - -* **Document Revisions** are snapshots of documents and their extensions. - * Revisions can be created for documents **automatically** when the documents - are created, modified, or deleted. - * Revisions can also be created for documents [manually](../../document-extensions/revisions/overview#force-revision-creation). - -* Revisions will be automatically **created** and **purged** for a document - only if the Revisions feature is enabled for the document's collection. - To enable or disable the Revisions feature for collections, and to set - limits for the number of revisions that can be kept per document, - apply a [Revisions configuration](../../document-extensions/revisions/overview#revisions-configuration) - to all and/or specific collections. - -* The trail of revisions created for a document can be inspected to track the changes - made in the document over time, and the document's live version can be reverted to any - of its recorded revisions. - - {INFO: } - Tracking document revisions allows you, for example, to check how an employee's - contract has changed over time, restore a single corrupted document without requiring - a backup file, or conduct a full-scale audit of your data. - {INFO/} - -* Revisions and their configuration can be managed via Client API methods or using Studio. - -* In this page: - * [Revisions Configuration](../../document-extensions/revisions/overview#revisions-configuration) - * [Default Settings and Collection-Specific Configurations](../../document-extensions/revisions/overview#default-settings-and-collection-specific-configurations) - * [Defining a Revisions Configuration](../../document-extensions/revisions/overview#defining-a-revisions-configuration) - * [Revisions Configuration Options](../../document-extensions/revisions/overview#revisions-configuration-options) - * [Revisions Configuration Execution](../../document-extensions/revisions/overview#revisions-configuration-execution) - * [Enabling and Disabling Revisions for Existing Documents](../../document-extensions/revisions/overview#enabling-and-disabling-revisions-for-existing-documents) - * [How it Works](../../document-extensions/revisions/overview#how-it-works) - * [Revisions Storage](../../document-extensions/revisions/overview#revisions-storage) - * [Force Revision Creation](../../document-extensions/revisions/overview#force-revision-creation) - -{NOTE/} - ---- - -{PANEL: Revisions Configuration} - -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. - -{NOTE: Conflict Revisions} -Revisions created for **conflicting documents** are a special case, that is -not covered in this article. - -* Conflict revisions are **Enabled** by default. -* Read about the conflict revisions API here: - [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration) -* Read about managing conflict revisions via Studio here: - [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions#editing-the-conflicting-document-defaults) - -{NOTE/} - - ---- - -#### 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. - {NOTE: } - If you apply no default settings, Revisions will be **disabled** for any - collection that a collection-specific configuration is not defined for. - {NOTE/} - ---- - -#### 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](../../studio/database/settings/document-revisions) - page. - * Inspect and manage the revisions created for each document using Studio's - Document View [Revisions tab](../../studio/database/document-extensions/revisions#revisions-tab). -* Via Client API: - [Read here](../../document-extensions/revisions/client-api/operations/configure-revisions) - 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](../../document-extensions/revisions/client-api/operations/configure-revisions#section-2) - 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](../../studio/database/settings/document-revisions#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. - {WARNING: } - - * 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. - {WARNING/} - ---- - -#### 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. - -{PANEL/} - -{PANEL: How it Works} - -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](../../studio/database/settings/document-revisions) - or the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions) - Store operation. - - ![Enable Revisions for the Users Collection](images\revisions_enable-revisions.png "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](../../studio/database/documents/create-new-document#create-new-document) - or the [session.Store](../../client-api/session/storing-entities#example) method. - - ![Create a Document](images\revisions_create-document.png "Create a Document") - -3. **Use Studio to inspect the new document's [Revisions tab](../../studio/database/document-extensions/revisions#revisions-tab)**. - Creating the document also created its first revision. - - ![Revision for Document Creation](images\revisions_document-created.png "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](images\revisions_modify-document.png "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](../../studio/database/document-extensions/revisions#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](images\revisions_revisions-bin.png "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](images\revisions_restored.png "Restored Revisions") - -{PANEL/} - -{PANEL: Revisions Storage} - -### 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](../../server/configuration/database-configuration#databases.compression.compressrevisionsdefault) - how to toggle this database option on and off. - * Learn [here](../../server/storage/documents-compression) how to apply Document Compression to revisions. - ---- - -### Revisions Document Extensions Storage - -Read [here](../../document-extensions/revisions/revisions-and-other-features#revisions-and-time-series) about revisions and **time series**. -Read [here](../../document-extensions/revisions/revisions-and-other-features#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features#revisions-and-attachments) about revisions and **attachments**. - -{PANEL/} - -{PANEL: Force Revision Creation} - -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](../../document-extensions/revisions/overview#force-revision-creation-via-api) - 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](images\revisions_create-revision-manually.png "Create a revision manually") - ---- - -#### Force Revision Creation via API - -To create a revision manually via the API, use the session `ForceRevisionCreationFor` method. - -`ForceRevisionCreationFor` overloads: -{CODE-BLOCK: csharp} -// Force revision creation by entity. -// Can be used with tracked entities only. -void ForceRevisionCreationFor(T entity, - ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); - -// Force revision creation by document ID. -void ForceRevisionCreationFor(string id, - ForceRevisionStrategy strategy = ForceRevisionStrategy.Before); -{CODE-BLOCK/} - -* **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`: - {CODE-BLOCK: csharp} -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 -} - {CODE-BLOCK/} - -* **Sample**: - {CODE-TABS} - {CODE-TAB:csharp:By_ID ForceRevisionCreationByID@DocumentExtensions\Revisions\Revisions.cs /} - {CODE-TAB:csharp:By_Entity ForceRevisionCreationByEntity@DocumentExtensions\Revisions\Revisions.cs /} - {CODE-TABS/} - - -{NOTE: When the Revisions feature is disabled:} - -Deleting a document that owns a manually-created revision -will not move the revision to the revisions bin. - -* A `delete revision` will Not be created. -* Manual revisions will not be kept in the revisions bin. - -{NOTE/} - - -{PANEL/} - -## Related Articles - -### Document Extensions - -* [Revert Revisions](../../document-extensions/revisions/revert-revisions) -* [Revisions and Other Features](../../document-extensions/revisions/revisions-and-other-features) - -### Client API - -* [Revisions: API Overview](../../document-extensions/revisions/client-api/overview) -* [Operations: Configuring Revisions](../../document-extensions/revisions/client-api/operations/configure-revisions) -* [Session: Loading Revisions](../../document-extensions/revisions/client-api/session/loading) - -### Studio - -* [Settings: Document Revisions](../../studio/database/settings/document-revisions) -* [Document Extensions: Revisions](../../studio/database/document-extensions/revisions) diff --git a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/overview.python.markdown b/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/overview.python.markdown deleted file mode 100644 index 190708ae4b..0000000000 --- a/Documentation/6.0/Raven.Documentation.Pages/document-extensions/revisions/overview.python.markdown +++ /dev/null @@ -1,304 +0,0 @@ -# Document Revisions Overview ---- - -{NOTE: } - -* **Document Revisions** are snapshots of documents and their extensions. - * Revisions can be created for documents **automatically** when the documents - are created, modified, or deleted. - * Revisions can also be created for documents [manually](../../document-extensions/revisions/overview#force-revision-creation). - -* Revisions will be automatically **created** and **purged** for a document - only if the Revisions feature is enabled for the document's collection. - To enable or disable the Revisions feature for collections, and to set - limits for the number of revisions that can be kept per document, - apply a [Revisions configuration](../../document-extensions/revisions/overview#revisions-configuration) - to all and/or specific collections. - -* The trail of revisions created for a document can be inspected to track the changes - made in the document over time, and the document's live version can be reverted to any - of its recorded revisions. - - {INFO: } - Tracking document revisions allows you, for example, to check how an employee's - contract has changed over time, restore a single corrupted document without requiring - a backup file, or conduct a full-scale audit of your data. - {INFO/} - -* Revisions and their configuration can be managed via Client API methods or using Studio. - -* In this page: - * [Revisions Configuration](../../document-extensions/revisions/overview#revisions-configuration) - * [Default Settings and Collection-Specific Configurations](../../document-extensions/revisions/overview#default-settings-and-collection-specific-configurations) - * [Defining a Revisions Configuration](../../document-extensions/revisions/overview#defining-a-revisions-configuration) - * [Revisions Configuration Options](../../document-extensions/revisions/overview#revisions-configuration-options) - * [Revisions Configuration Execution](../../document-extensions/revisions/overview#revisions-configuration-execution) - * [Enabling and Disabling Revisions for Existing Documents](../../document-extensions/revisions/overview#enabling-and-disabling-revisions-for-existing-documents) - * [How it Works](../../document-extensions/revisions/overview#how-it-works) - * [Revisions Storage](../../document-extensions/revisions/overview#revisions-storage) - * [Force Revision Creation](../../document-extensions/revisions/overview#force-revision-creation) - -{NOTE/} - ---- - -{PANEL: Revisions Configuration} - -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. - -{NOTE: Conflict Revisions} -Revisions created for **conflicting documents** are a special case, that is -not covered in this article. - -* Conflict revisions are **Enabled** by default. -* Read about the conflict revisions API here: - [Conflict Revisions Configuration](../../document-extensions/revisions/client-api/operations/conflict-revisions-configuration) -* Read about managing conflict revisions via Studio here: - [Editing the Conflicting Document Defaults](../../studio/database/settings/document-revisions#editing-the-conflicting-document-defaults) - -{NOTE/} - - ---- - -#### 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. - {NOTE: } - If you apply no default settings, Revisions will be **disabled** for any - collection that a collection-specific configuration is not defined for. - {NOTE/} - ---- - -#### 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](../../studio/database/settings/document-revisions) - page. - * Inspect and manage the revisions created for each document using Studio's - Document View [Revisions tab](../../studio/database/document-extensions/revisions#revisions-tab). -* Via Client API: - [Read here](../../document-extensions/revisions/client-api/operations/configure-revisions) - 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](../../document-extensions/revisions/client-api/operations/configure-revisions#section-2) - 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](../../studio/database/settings/document-revisions#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. - {WARNING: } - - * 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. - {WARNING/} - ---- - -#### 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. - -{PANEL/} - -{PANEL: How it Works} - -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](../../studio/database/settings/document-revisions) - or the [ConfigureRevisionsOperation](../../document-extensions/revisions/client-api/operations/configure-revisions) - Store operation. - - ![Enable Revisions for the Users Collection](images\revisions_enable-revisions.png "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](../../studio/database/documents/create-new-document#create-new-document) - or the [session.Store](../../client-api/session/storing-entities#example) method. - - ![Create a Document](images\revisions_create-document.png "Create a Document") - -3. **Use Studio to inspect the new document's [Revisions tab](../../studio/database/document-extensions/revisions#revisions-tab)**. - Creating the document also created its first revision. - - ![Revision for Document Creation](images\revisions_document-created.png "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](images\revisions_modify-document.png "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](../../studio/database/document-extensions/revisions#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](images\revisions_revisions-bin.png "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](images\revisions_restored.png "Restored Revisions") - -{PANEL/} - -{PANEL: Revisions Storage} - -### 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](../../server/configuration/database-configuration#databases.compression.compressrevisionsdefault) - how to toggle this database option on and off. - * Learn [here](../../server/storage/documents-compression) how to apply Document Compression to revisions. - ---- - -### Revisions Document Extensions Storage - -Read [here](../../document-extensions/revisions/revisions-and-other-features#revisions-and-time-series) about revisions and **time series**. -Read [here](../../document-extensions/revisions/revisions-and-other-features#revisions-and-counters) about revisions and **counters**. -Read [here](../../document-extensions/revisions/revisions-and-other-features#revisions-and-attachments) about revisions and **attachments**. - -{PANEL/} - -{PANEL: Force Revision Creation} - -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](../../document-extensions/revisions/overview#force-revision-creation-via-api) - 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](images\revisions_create-revision-manually.png "Create a revision manually") - ---- - -#### Force Revision Creation via API - -To create a revision manually via the API, use the advanced session `force_revision_creation_for` method. -{CODE:python force_revision_creation_for@DocumentExtensions\Revisions\Revisions.py /} - -{NOTE: When the Revisions feature is disabled:} -Deleting a document that owns a manually-created revision will not move the revision to the revisions bin. - -* A `delete revision` will Not be created. -* Manual revisions will not be kept in the revisions bin. - -{NOTE/} - -{PANEL/} - -## Related Articles - -### Document Extensions - -* [Revert Revisions](../../document-extensions/revisions/revert-revisions) -* [Revisions and Other Features](../../document-extensions/revisions/revisions-and-other-features) - -### Client API - -* [Revisions: API Overview](../../document-extensions/revisions/client-api/overview) -* [Operations: Configuring Revisions](../../document-extensions/revisions/client-api/operations/configure-revisions) -* [Session: Loading Revisions](../../document-extensions/revisions/client-api/session/loading) - -### Studio - -* [Settings: Document Revisions](../../studio/database/settings/document-revisions) -* [Document Extensions: Revisions](../../studio/database/document-extensions/revisions) diff --git a/Documentation/6.0/Samples/csharp/Raven.Documentation.Samples/DocumentExtensions/Revisions/Revisions.cs b/Documentation/6.0/Samples/csharp/Raven.Documentation.Samples/DocumentExtensions/Revisions/Revisions.cs index 91b6a8419a..eae660c4d6 100644 --- a/Documentation/6.0/Samples/csharp/Raven.Documentation.Samples/DocumentExtensions/Revisions/Revisions.cs +++ b/Documentation/6.0/Samples/csharp/Raven.Documentation.Samples/DocumentExtensions/Revisions/Revisions.cs @@ -92,41 +92,6 @@ await store.Maintenance.SendAsync(new ConfigureRevisionsOperation(new RevisionsC } } - public async Task ForceRevisionCreationForSample() - { - using (var store = new DocumentStore()) - { - string companyId; - using (var session = store.OpenSession()) - { - #region ForceRevisionCreationByEntity - // 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); - #endregion - } - - using (var session = store.OpenSession()) - { - #region ForceRevisionCreationByID - // Force revision creation by ID - session.Advanced.Revisions.ForceRevisionCreationFor(companyId); - session.SaveChanges(); - #endregion - - var revisionsCount = session.Advanced.Revisions.GetFor(companyId).Count; - } - } - } - public class Company { public string Id { get; set; } diff --git a/Documentation/6.0/Samples/python/DocumentExtensions/Revisions/Revisions.py b/Documentation/6.0/Samples/python/DocumentExtensions/Revisions/Revisions.py deleted file mode 100644 index 28e8b4ca44..0000000000 --- a/Documentation/6.0/Samples/python/DocumentExtensions/Revisions/Revisions.py +++ /dev/null @@ -1,23 +0,0 @@ -from ravendb.primitives import constants - -from examples_base import ExampleBase - -class Force(ExampleBase): - def setUp(self): - super().setUp() - - # region force_revision_creation_for - 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) - # endregion