see on GitHub

Commands : Patches: How to use JavaScript to patch your documents?

Patch command is used to perform partial document updates without having to load, modify, and save a full document. This is usually useful for updating denormalized data in entities.

Syntax

/// <summary>
/// Sends a patch request for a specific document, ignoring document's Etag and if it is missing
/// </summary>
/// <param name="key">Key of the document to patch</param>
/// <param name="patch">The patch request to use (using JavaScript)</param>
RavenJObject Patch(string key, ScriptedPatchRequest patch);

/// <summary>
/// Sends a patch request for a specific document, ignoring the document's Etag
/// </summary>
/// <param name="key">Key of the document to patch</param>
/// <param name="patch">The patch request to use (using JavaScript)</param>
/// <param name="ignoreMissing">true if the patch request should ignore a missing document, false to throw DocumentDoesNotExistException</param>
RavenJObject Patch(string key, ScriptedPatchRequest patch, bool ignoreMissing);

/// <summary>
/// Sends a patch request for a specific document
/// </summary>
/// <param name="key">Key of the document to patch</param>
/// <param name="patch">The patch request to use (using JavaScript)</param>
/// <param name="etag">Require specific Etag [null to ignore]</param>
RavenJObject Patch(string key, ScriptedPatchRequest patch, Etag etag);

/// <summary>
/// Sends a patch request for a specific document which may or may not currently exist
/// </summary>
/// <param name="key">Id of the document to patch</param>
/// <param name="patchExisting">The patch request to use (using JavaScript) to an existing document</param>
/// <param name="patchDefault">The patch request to use (using JavaScript)  to a default document when the document is missing</param>
/// <param name="defaultMetadata">The metadata for the default document when the document is missing</param>
RavenJObject Patch(string key, ScriptedPatchRequest patchExisting, ScriptedPatchRequest patchDefault, RavenJObject defaultMetadata);

Parameters

public class ScriptedPatchRequest
{
	/// <summary>
	/// JavaScript function that will patch a document
	/// </summary>
	/// <value>The type.</value>
	public string Script { get; set; }

	/// <summary>
	/// Additional values that will be passed to function
	/// </summary>
	public Dictionary<string, object> Values { get; set; }
}

Methods, objects and variables

Before we will move to the examples, let's look at the methods, objects, and variables available:

__document_id variable Id for current document
this object Current document (with metadata)
LoadDocument(key) method Allows document loading, increases maximum number of allowed steps in script. See Raven/AdditionalStepsForScriptBasedOnDocumentSize here.
PutDocument(key, data, metadata) method Allows document putting, returns generated key
IncreaseNumberOfAllowedStepsBy(number) method Will increase the maximum allowed number of steps in script by given value. Only available if Raven/AllowScriptsToAdjustNumberOfSteps is set to true.
_ object Lo-Dash 2.4.1
trim() string.prototype trims the string e.g. this.FirstName.trim()
output(...) method Allows debug your patch, prints passed messages in output tab
indexOf(...) Array.prototype wrapper for _.indexOf
filter(...) Array.prototype wrapper for _.filter
Map(...) Array.prototype wrapper for _.map
Where(...) Array.prototype wrapper for _.filter
RemoveWhere(...) Array.prototype wrapper for _.remove returning Array for easier chaining
Remove(...) Array.prototype wrapper for _.pull returning Array for easier chaining

Custom functions

Beside built-in functions, custom ones can be introduced. Please visit this page if you want to know how to add custom functions.

Example I

// change FirstName to Robert
store
	.DatabaseCommands
	.Patch(
		"employees/1",
		new ScriptedPatchRequest
			{
				Script = "this.FirstName = 'Robert';"
			});

Example II

// trim FirstName
store
	.DatabaseCommands
	.Patch(
		"employees/1",
		new ScriptedPatchRequest
		{
			Script = "this.FirstName = this.FirstName.trim();"
		});

Example III

// add new property Age with value of 30
store
	.DatabaseCommands
	.Patch(
		"employees/1",
		new ScriptedPatchRequest
		{
			Script = "this.Age = 30;"
		});

Example IV

// add new property Age with value of 30 using LoDash
store
	.DatabaseCommands
	.Patch(
		"employees/1",
		new ScriptedPatchRequest
		{
			Script = "_.extend(this, { 'Age': '30'});"
		});

Example V

// passing data and loading different document
store
	.DatabaseCommands
	.Patch(
		"employees/1",
		new ScriptedPatchRequest
		{
			Script = @"
						var employee = LoadDocument(differentEmployeeId);
						this.FirstName = employee.FirstName;",
			Values = new Dictionary<string, object>
				         {
					         { "differentEmployeeId", "employees/2" }
				         }
		});

Example VI

// accessing metadata (added ClrType property with value from @metadata)
store
	.DatabaseCommands
	.Patch(
		"employees/1",
		new ScriptedPatchRequest
		{
			Script = @"this.ClrType = this['@metadata']['Raven-Clr-Type'];"
		});

Example VII

// creating new document with auto-assigned key e.g. 'Comments/100'. Document key will be returned by PutDocument.
store
	.DatabaseCommands
	.Patch(
		"employees/1",
		new ScriptedPatchRequest
		{
			Script = @"var commentKey = PutDocument('Comments/', { 'Author': this.LastName }, { });"
		});

Example VIII

// add a new comment to Comments
store
	.DatabaseCommands
	.Patch(
		"blogposts/1",
		new ScriptedPatchRequest
		{
			Script = @"this.Comments.push({ 'Title': 'Some title', 'Content': 'Lore ipsum' });"
		});

Example IX

// removing comments with 'Some title' as a title
store
	.DatabaseCommands
	.Patch(
		"blogposts/1",
		new ScriptedPatchRequest
		{
			Script = @"
						this.Comments.RemoveWhere(function(comment) {
							return comment.Title == 'Some title';
						});"
		});

Example X

// modifying each comment
store
	.DatabaseCommands
	.Patch(
		"blogposts/1",
		new ScriptedPatchRequest
		{
			Script = @"
						this.Comments.Map(function(comment) {
							comment.Title = 'New title';
							return comment;
						});"
		});

Example XI

// increasing maximum number of allowed steps
store
	.DatabaseCommands
	.Patch(
		"employees/1",
		new ScriptedPatchRequest
		{
			Script = @"
						var employee = LoadDocument(differentEmployeeId);
						if (employee) {
							IncreaseNumberOfAllowedStepsBy(10);
							this.FirstName = employee.FirstName;
						}",
			Values = new Dictionary<string, object>
				         {
					         { "differentEmployeeId", "employees/2" }
				         }
		});