You are currently browsing legacy 3.0 version of documentation. Click here to switch to the newest 5.0 version.

We can help you with migration to the latest RavenDB

Contact Us Now
see on GitHub

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