Commands: Patches: How to work with patch requests?
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
/**
* Sends a patch request for a specific document, ignoring document's Etag and if it is missing
* @param key Key of the document to patch
* @param patches Array of patch requests
* @return
*/
public RavenJObject patch(String key, PatchRequest[] patches);
/**
* Sends a patch request for a specific document, ignoring the document's Etag
* @param key Key of the document to patch
* @param patches Array of patch requests
* @param ignoreMissing true if the patch request should ignore a missing document, false to throw DocumentDoesNotExistException
* @return
*/
public RavenJObject patch(String key, PatchRequest[] patches, boolean ignoreMissing);
/**
* Sends a patch request for a specific document
* @param key Key of the document to patch
* @param patches Array of patch requests
* @param etag Require specific Etag [null to ignore]
* @return
*/
public RavenJObject patch(String key, PatchRequest[] patches, Etag etag);
/**
* Sends a patch request for a specific document which may or may not currently exist
* @param key Id of the document to patch
* @param patchesToExisting Array of patch requests to apply to an existing document
* @param patchesToDefault Array of patch requests to apply to a default document when the document is missing
* @param defaultMetadata The metadata for the default document when the document is missing
* @return
*/
public RavenJObject patch(String key, PatchRequest[] patchesToExisting, PatchRequest[] patchesToDefault, RavenJObject defaultMetadata);
Parameters
public class PatchRequest {
private PatchCommandType type = PatchCommandType.SET;
private RavenJToken prevVal;
private RavenJToken value;
private PatchRequest[] nested;
private String name;
private Integer position;
private Boolean allPositions;
public PatchRequest() {
super();
}
public PatchRequest(PatchCommandType type, String name, RavenJToken value) {
super();
this.type = type;
this.name = name;
this.value = value;
}
public PatchCommandType getType() {
return type;
}
public void setType(PatchCommandType type) {
this.type = type;
}
public RavenJToken getPrevVal() {
return prevVal;
}
public void setPrevVal(RavenJToken prevVal) {
this.prevVal = prevVal;
}
public RavenJToken getValue() {
return value;
}
public void setValue(RavenJToken value) {
this.value = value;
}
public PatchRequest[] getNested() {
return nested;
}
public void setNested(PatchRequest[] nested) {
this.nested = nested;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public Integer getPosition() {
return position;
}
public void setPosition(Integer position) {
this.position = position;
}
public Boolean getAllPositions() {
return allPositions;
}
public void setAllPositions(Boolean allPositions) {
this.allPositions = allPositions;
}
}
public enum PatchCommandType {
/**
* Set a property
*/
SET,
/**
* Unset (remove) a property
*/
UNSET,
/**
* Add an item to an array
*/
ADD,
/**
* Insert an item to an array at a specified position
*/
INSERT,
/**
* Remove an item from an array at a specified position
*/
REMOVE,
/**
* Modify a property value by providing a nested set of patch operation
*/
MODIFY,
/**
* Increment a property by a specified value
*/
INC,
/**
* Copy a property value to another property
*/
COPY,
/**
* Rename a property
*/
RENAME;
}
Example I
// change FirstName to Robert
store.getDatabaseCommands().patch("employees/1", new PatchRequest[] {
new PatchRequest(PatchCommandType.SET, "FirstName", RavenJToken.fromObject("Robert"))
});
Example II
// change FirstName to Robert and LastName to Carter in single request
store.getDatabaseCommands().patch("employees/1", new PatchRequest[] {
new PatchRequest(PatchCommandType.SET, "FirstName", RavenJToken.fromObject("Robert")),
new PatchRequest(PatchCommandType.SET, "LastName", RavenJToken.fromObject("Carter")),
});
Example III
// add new property Age with value of 30
store.getDatabaseCommands().patch("employees/1", new PatchRequest[] {
new PatchRequest(PatchCommandType.ADD, "Age", RavenJToken.fromObject(30)),
});
Example IV
// increment Age property value by 10
store.getDatabaseCommands().patch("employees/1", new PatchRequest[] {
new PatchRequest(PatchCommandType.INC, "Age", RavenJToken.fromObject(10)),
});
Example V
// remove property Age
store.getDatabaseCommands().patch("employees/1", new PatchRequest[] {
new PatchRequest(PatchCommandType.UNSET, "Age", null),
});
Example VI
// rename FirstName to First
store.getDatabaseCommands().patch("employees/1", new PatchRequest[] {
new PatchRequest(PatchCommandType.RENAME, "FirstName", RavenJToken.fromObject("First")),
});
Example VII
// add a new comment to Comments
BlogComment blogComment = new BlogComment();
blogComment.setContent("Lore ipsum");
blogComment.setTitle("Some title");
store.getDatabaseCommands().patch("blogposts/1", new PatchRequest[] {
new PatchRequest(PatchCommandType.ADD, "Comments", RavenJToken.fromObject(blogComment)),
});
Example VIII
// insert a new comment at position 0 to Comments
BlogComment comment = new BlogComment();
comment.setContent("Lore ipsum");
comment.setTitle("Some title");
PatchRequest patchRequest = new PatchRequest(PatchCommandType.INSERT, "Comments", RavenJToken.fromObject(comment));
patchRequest.setPosition(0);
store.getDatabaseCommands().patch("blogposts/1", new PatchRequest[] {
patchRequest
});
Example IX
// modify a comment at position 3 in Comments
PatchRequest subPatch = new PatchRequest(PatchCommandType.SET, "Title", RavenJToken.fromObject("New title"));
PatchRequest mainPatch = new PatchRequest();
mainPatch.setType(PatchCommandType.MODIFY);
mainPatch.setPosition(3);
mainPatch.setName("Comments");
mainPatch.setNested(new PatchRequest[] { subPatch });
store.getDatabaseCommands().patch("blogposts/1", new PatchRequest[] {
mainPatch
});