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
});