Skip to Navigation
The Patch operation is used to perform partial document updates without having to load, modify, and save a full document. The whole operation is executed on the server side and is useful as a performance enhancement or for updating denormalized data in entities.
The current page deals with patch operations on single documents.
Patching has three possible interfaces: Typed Session API, Non-Typed Session API, and Operations API.
Patching can be done from the client as well as in the studio.
A type safe session interface that allows performing the most common patch operations.
The patch request will be sent to server only after the call to SaveChanges. This way it's possible to perform multiple operations in one request to the server.
Session.Advanced.Increment
void Increment<T, U>(T entity, Expression<Func<T, U>> fieldPath, U delta);
void Increment<T, U>(string id, Expression<Func<T, U>> fieldPath, U delta);| Parameters | ||
|---|---|---|
| T | Type |
Entity type |
| U | Type |
Field type, must be of numeric type or a string of char for string concatenation |
| entity | T |
Entity on which the operation should be performed. The entity should be one that was returned by the current session in a Load or Query operation, this way, the session can track down the entity's ID |
| entity id | string |
Entity ID on which the operation should be performed. |
| fieldPath | Expression<Func<T, U>> |
Lambda describing the path to the field. |
| delta | U |
Value to be added. |
Session.Advanced.Patch
void Patch<T, U>(string id, Expression<Func<T, U>> fieldPath, U value);
void Patch<T, U>(T entity, Expression<Func<T, U>> fieldPath, U value);| Parameters | ||
|---|---|---|
| T | Type |
Entity type |
| U | Type |
Field type |
| entity | T |
Entity on which the operation should be performed. The entity should be one that was returned by the current session in a Load or Query operation. This way the session can track down the entity's ID. |
| entity id | string |
Entity ID on which the operation should be performed. |
| fieldPath | Expression<Func<T, U>> |
Lambda describing the path to the field. |
| delta | U |
Value to set. |
Session.Advanced.Patch
void Patch<T, U>(T entity, Expression<Func<T, IEnumerable<U>>> fieldPath,
Expression<Func<JavaScriptArray<U>, object>> arrayMofificationLambda);
void Patch<T, U>(string id, Expression<Func<T, IEnumerable<U>>> fieldPath,
Expression<Func<JavaScriptArray<U>, object>> arrayMofificationLambda);| Parameters | ||
|---|---|---|
| T | Type |
Entity type |
| U | Type |
Field type |
| entity | T |
Entity on which the operation should be performed. The entity should be one that was returned by the current session in a Load or Query operation. This way the session can track down the entity's ID. |
| entity id | string |
Entity ID on which the operation should be performed. |
| fieldPath | Expression<Func<T, U>> |
Lambda describing the path to the field. |
| arrayMofificationLambda | Expression<Func<JavaScriptArray<U>, object>> |
Lambda that modifies the array, see JavaScriptArray below. |
JavaScriptArray allows building lambdas representing array manipulations for patches.
| Method Signature | Return Type | Description |
|---|---|---|
| Put(T item) | JavaScriptArray |
Allows adding item to an array. |
| Put(params T[] items) | JavaScriptArray |
Items to be added to the array. |
| RemoveAt(int index) | JavaScriptArray |
Removes item in position index in array. |
| RemoveAll(Func<T, bool> predicate) | JavaScriptArray |
Removes all the items in the array that satisfy the given predicate. |
The non-typed Session API for patches uses the Session.Advanced.Defer function which allows registering one or more commands.
One of the possible commands is the PatchCommandData, describing single document patch command.
The patch request will be sent to server only after the call to SaveChanges, this way it's possible to perform multiple operations in one request to the server.
Session.Advanced.Defer
void Defer(ICommandData[] commands);| Constructor | ||
|---|---|---|
| id | string |
ID of the document to be patched. |
| changeVector | string |
[Can be null] Change vector of the document to be patched, used to verify that the document was not changed before the patch reached it. |
| patch | PatchRequest |
Patch request to be performed on the document. |
| patchIfMissing | PatchRequest |
[Can be null] Patch request to be performed if no document with the given ID was found. |
We highly recommend using scripts with parameters. This allows RavenDB to cache scripts and boost performance. Parameters can be accessed in the script through the args object, and passed using PatchRequest's "Values" parameter.
| Members | ||
|---|---|---|
| Script | string |
JavaScript code to be run. |
| Values | Dictionary<string, object> |
Parameters to be passed to the script. The parameters can be accessed using the '$' prefix. Parameter starting with a '$' will be used as is, without further concatenation . |
An operations interface that exposes the full functionality and allows performing ad-hoc patch operations without creating a session.
Raven.Client.Documents.Operations.Send
Raven.Client.Documents.Operations.SendAsync
PatchStatus Send(PatchOperation operation);
Task<PatchStatus> SendAsync(PatchOperation operation,
SessionInfo sessionInfo = null,
CancellationToken token = default(CancellationToken));| Constructor | ||
|---|---|---|
| id | string |
ID of the document to be patched. |
| changeVector | string |
[Can be null] Change vector of the document to be patched, used to verify that the document was not changed before the patch reached it. |
| patch | PatchRequest |
Patch request to be performed on the document. |
| patchIfMissing | PatchRequest |
[Can be null] Patch request to be performed if no document with the given ID was found. Will run only if no changeVector was passed. |
| skipPatchIfChangeVectorMismatch | bool |
If false and changeVector has value, and document with that ID and change vector was not found, will throw exception. |
This is a list of a few of the javascript methods that can be used in patch scripts. See the more comprehensive list at Knowledge Base: JavaScript Engine.
| Method | Arguments | Description |
|---|---|---|
| load | string or string[] |
Loads one or more documents into the context of the script by their document IDs |
| loadPath | A document and a path to an ID within that document | Loads a related document by the path to its ID |
| del | Document ID; change vector | Delete the given document by its ID. If you add the expected change vector and the document's current change vector does not match, the document will not be deleted. |
| put | Document ID; document; change vector | Create or overwrite a document with a specified ID and entity. If you try to overwrite an existing document and pass the expected change vector, the put will fail if the specified change vector does not match the document's current change vector. |
| cmpxchg | Key | Load a compare exchange value into the context of the script using its key |
| getMetadata | Document | Returns the document's metadata |
| id | Document | Returns the document's ID |
| lastModified | Document | Returns the DateTime of the most recent modification made to the given document |
| counter | Document; counter name | Returns the value of the specified counter in the specified document |
| counterRaw | Document; counter name | Returns the specified counter in the specified document as a key-value pair |
| incrementCounter | Document; counter name | Increases the value of the counter by one |
| deleteCounter | Document; counter name | Deletes the counter |
// change FirstName to Robert
session.Advanced.Patch<Employee, string>(
"employees/1",
x => x.FirstName, "Robert");
session.SaveChanges();// change FirstName to Robert
session.Advanced.Defer(new PatchCommandData(
id: "employees/1",
changeVector: null,
patch: new PatchRequest
{
Script = @"this.FirstName = args.FirstName;",
Values =
{
{"FirstName", "Robert"}
}
},
patchIfMissing: null));
session.SaveChanges();// change FirstName to Robert
store.Operations.Send(new PatchOperation(
id: "employees/1",
changeVector: null,
patch: new PatchRequest
{
Script = @"this.FirstName = args.FirstName;",
Values =
{
{"FirstName", "Robert"}
}
},
patchIfMissing: null));// change FirstName to Robert and LastName to Carter in single request
// note that in this case, we create single request, but two seperate batch operations
// in order to achieve atomicity, please use the non generic APIs
session.Advanced.Patch<Employee, string>("employees/1", x => x.FirstName, "Robert");
session.Advanced.Patch<Employee, string>("employees/1", x => x.LastName, "Carter");
session.SaveChanges();// change FirstName to Robert and LastName to Carter in single request
// note that here we do maintain the atomicity of the operation
session.Advanced.Defer(new PatchCommandData(
id: "employees/1",
changeVector: null,
patch: new PatchRequest
{
Script = @"
this.FirstName = args.UserName.FirstName
this.LastName = args.UserName.LastName",
Values =
{
{
"UserName", new
{
FirstName = "Robert",
LastName = "Carter"
}
}
}
},
patchIfMissing: null));
session.SaveChanges();// change FirstName to Robert and LastName to Carter in single request
// note that here we do maintain the atomicity of the operation
store.Operations.Send(new PatchOperation(
id: "employees/1",
changeVector: null,
patch: new PatchRequest
{
Script = @"
this.FirstName = args.UserName.FirstName
this.LastName = args.UserName.LastName",
Values =
{
{
"UserName", new
{
FirstName = "Robert",
LastName = "Carter"
}
}
}
}, patchIfMissing: null));// increment UnitsInStock property value by 10
session.Advanced.Increment<Product, int>("products/1-A", x => x.UnitsInStock, 10);
session.SaveChanges();session.Advanced.Defer(new PatchCommandData(
id: "products/1-A",
changeVector: null,
patch: new PatchRequest
{
Script = @"this.UnitsInStock += args.UnitsToAdd",
Values =
{
{"UnitsToAdd", 10}
}
},
patchIfMissing: null));
session.SaveChanges();store.Operations.Send(new PatchOperation(
id: "products/1-A",
changeVector: null,
patch: new PatchRequest
{
Script = @"this.UnitsInStock += args.UnitsToAdd",
Values =
{
{"UnitsToAdd", 10}
}
},
patchIfMissing: null));// add a new comment to Comments
session.Advanced.Patch<BlogPost, BlogComment>("blogposts/1",
x => x.Comments,
comments => comments.Add(new BlogComment
{
Content = "Lore ipsum",
Title = "Some title"
}));
session.SaveChanges();// add a new comment to Comments
session.Advanced.Defer(new PatchCommandData(
id: "blogposts/1",
changeVector: null,
patch: new PatchRequest
{
Script = "this.Comments.push(args.Comment)",
Values =
{
{
"Comment", new BlogComment
{
Content = "Lore ipsum",
Title = "Some title"
}
}
}
},
patchIfMissing: null));
session.SaveChanges();// add a new comment to Comments
store.Operations.Send(new PatchOperation(
id: "blogposts/1",
changeVector: null,
patch: new PatchRequest
{
Script = "this.Comments.push(args.Comment)",
Values =
{
{
"Comment", new BlogComment
{
Content = "Lore ipsum",
Title = "Some title"
}
}
}
},
patchIfMissing: null));Inserting item into specific position is supported only by the non-typed APIs
// insert a new comment at position 1 to Comments
session.Advanced.Defer(new PatchCommandData(
id: "blogposts/1",
changeVector: null,
patch: new PatchRequest
{
Script = "this.Comments.splice(1,0,args.Comment)",
Values =
{
{
"Comment", new BlogComment
{
Content = "Lore ipsum",
Title = "Some title"
}
}
}
},
patchIfMissing: null));
session.SaveChanges();store.Operations.Send(new PatchOperation(
id: "blogposts/1",
changeVector: null,
patch: new PatchRequest
{
Script = "this.Comments.splice(1,0,args.Comment)",
Values =
{
{
"Comment", new BlogComment
{
Content = "Lore ipsum",
Title = "Some title"
}
}
}
},
patchIfMissing: null));Inserting item into specific position is supported only by the non-typed APIs
// modify a comment at position 3 in Comments
session.Advanced.Defer(new PatchCommandData(
id: "blogposts/1",
changeVector: null,
patch: new PatchRequest
{
Script = "this.Comments.splice(3,1,args.Comment)",
Values =
{
{
"Comment", new BlogComment
{
Content = "Lore ipsum",
Title = "Some title"
}
}
}
},
patchIfMissing: null));
session.SaveChanges();// modify a comment at position 3 in Comments
store.Operations.Send(new PatchOperation(
id: "blogposts/1",
changeVector: null,
patch: new PatchRequest
{
Script = "this.Comments.splice(1,0,args.Comment)",
Values =
{
{
"Comment", new BlogComment
{
Content = "Lore ipsum",
Title = "Some title"
}
}
}
},
patchIfMissing: null));// filter out all comments of a blogpost which contains the word "wrong" in their contents
session.Advanced.Patch<BlogPost, BlogComment>("blogposts/1",
x => x.Comments,
comments => comments.RemoveAll(y => y.Content.Contains("wrong")));
session.SaveChanges();// filter out all comments of a blogpost which contains the word "wrong" in their contents
session.Advanced.Defer(new PatchCommandData(
id: "blogposts/1",
changeVector: null,
patch: new PatchRequest
{
Script = @"this.Comments = this.Comments.filter(comment=>
comment.Content.includes(args.TitleToRemove));",
Values =
{
{"TitleToRemove", "wrong"}
}
},
patchIfMissing: null));
session.SaveChanges();// filter out all comments of a blogpost which contains the word "wrong" in their contents
store.Operations.Send(new PatchOperation(
id: "blogposts/1",
changeVector: null,
patch: new PatchRequest
{
Script = @"this.Comments = this.Comments.filter(comment=>
comment.Content.includes(args.TitleToRemove));",
Values =
{
{"TitleToRemove", "wrong"}
}
},
patchIfMissing: null));Loading documents supported only by non-typed APIs
// update product names in order, according to loaded product documents
session.Advanced.Defer(new PatchCommandData(
id: "orders/1",
changeVector: null,
patch: new PatchRequest
{
Script = @"this.Lines.forEach(line=> {
var productDoc = load(line.Product);
line.ProductName = productDoc.Name;
});"
}, patchIfMissing: null));
session.SaveChanges();// update product names in order, according to loaded product documents
store.Operations.Send(new PatchOperation(
id: "blogposts/1",
changeVector: null,
patch: new PatchRequest
{
Script = @"this.Lines.forEach(line=> {
var productDoc = load(line.Product);
line.ProductName = productDoc.Name;
});"
},
patchIfMissing: null));Removing property supported only by the non-typed APIs
// remove property Age
session.Advanced.Defer(new PatchCommandData(
id: "employees/1",
changeVector: null,
patch: new PatchRequest
{
Script = @"delete this.Age"
},
patchIfMissing: null));
session.SaveChanges();// remove property Age
store.Operations.Send(new PatchOperation(
id: "employees/1",
changeVector: null,
patch: new PatchRequest
{
Script = @"delete this.Age"
},
patchIfMissing: null));Renaming property supported only by the non-typed APIs
// rename FirstName to First
session.Advanced.Defer(new PatchCommandData(
id: "employees/1",
changeVector: null,
patch: new PatchRequest
{
Script = @" var firstName = this[args.Rename.Old];
delete this[args.Rename.Old];
this[args.Rename.New] = firstName",
Values =
{
{
"Rename", new
{
Old = "FirstName",
New = "Name"
}
}
}
},
patchIfMissing: null));
session.SaveChanges();store.Operations.Send(new PatchOperation(
id: "employees/1",
changeVector: null,
patch: new PatchRequest
{
Script = @" var firstName = this[args.Rename.Old];
delete this[args.Rename.Old];
this[args.Rename.New] = firstName",
Values =
{
{
"Rename", new
{
Old = "FirstName",
New = "Name"
}
}
}
},
patchIfMissing: null));Adding a new document is supported only by the non-typed APIs
session.Advanced.Defer(new PatchCommandData("employees/1-A", null,
new PatchRequest
{
Script = "put('orders/', { Employee: id(this) });",
}, null));
session.SaveChanges();store.Operations.Send(new PatchOperation("employees/1-A", null, new PatchRequest
{
Script = "put('orders/', { Employee: id(this) });",
}));In order to clone a document use put method as follows
session.Advanced.Defer(new PatchCommandData("employees/1-A", null,
new PatchRequest
{
Script = "put('employees/', this);",
}, null));
session.SaveChanges();store.Operations.Send(new PatchOperation("employees/1-A", null, new PatchRequest
{
Script = "put('employees/', this);",
}));The attachments and/or counters from source document will not be copied to the new one automatically.
In order to increment or create a counter use incrementCounter method as follows
var order = session.Load<Order>("orders/1-A");
session.CountersFor(order).Increment("Likes", 1);
session.SaveChanges();session.Advanced.Defer(new PatchCommandData("orders/1-A", null,
new PatchRequest
{
Script = "incrementCounter(this.Company, args.name, args.val);",
Values =
{
{ "name", "Likes" },
{ "val", 20 }
}
}, null));
session.SaveChanges();store.Operations.Send(new PatchOperation("orders/1-A", null, new PatchRequest
{
Script = "incrementCounter(this.Company, args.name, args.val);",
Values =
{
{ "name", "Likes" },
{ "val", -1 }
}
}));The method can be called by document ID or by document reference and the value can be negative
In order to delete a counter use deleteCounter method as follows
session.CountersFor("orders/1-A").Delete("Likes");
session.SaveChanges();session.Advanced.Defer(new PatchCommandData("products/1-A", null,
new PatchRequest
{
Script = "deleteCounter(this, args.name);",
Values =
{
{ "name", "Likes" },
}
}, null));
session.SaveChanges();store.Operations.Send(new PatchOperation("products/1-A", null, new PatchRequest
{
Script = "deleteCounter(this, args.name);",
Values =
{
{ "name", "Likes" },
}
}));The method can be called by document ID or by document reference
In order to get a counter while patching use counter method as follows
var order = session.Load<Order>("orders/1-A");
var counters = session.Advanced.GetCountersFor(order);session.Advanced.Defer(new PatchCommandData("orders/1-A", null,
new PatchRequest
{
Script = @"var likes = counter(this.Company, args.name);
put('result/', {company: this.Company, likes: likes});",
Values =
{
{ "name", "Likes" },
}
}, null));
session.SaveChanges();store.Operations.Send(new PatchOperation("orders/1-A", null, new PatchRequest
{
Script = @"var likes = counter(this.Company, args.name);
put('result/', {company: this.Company, likes: likes});",
Values =
{
{ "name", "Likes" },
}
}));The method can be called by document ID or by document reference
Dear User,
By browsing on this website you are agreeing to our ‘Terms & Conditions’ and the ‘Privacy Policy’ in regards to your rights and personal data handling.