DocumentMutation.set()

Either creates a field in a document and gives the field the specified value, or replaces the value of a field that already exists in a document.

Operations Performed

  1. Verifies that a field at the specified path exists.
    • If there is no field, creates the field and write the new value to it.
    • If there is a field, proceeds to the next step.
  2. Verifies that the passed value is of the same data type as the existing value.
    • If the data types are identical, writes the new value.
    • If the data types are not identical, returns an exception.

Example of Setting a Scalar Value

Original document
{ 
  "_id" : "000001",
  "a" : {
         "b" : 1 
         }
}
Example code
  public DocumentMutation buildDocumentMutation() {
    return MapRDB.newDocumentMutation()
      .set("a", ImmutableMap.of(
        "b", 2,
        "c", 3));
  }

  public void updateDoc(String tablePath, DocumentMutation mutation, String _id) {
    try(Table table = MapRDB.getTable(tablePath)) {
      table.update(_id, mutation);
    }
  }
Parameter Description
_id The value of the document's _id field.
tablePath The path of the table in the MapR file system. See Table Paths.
Revised document
{ 
  "_id" : "000001",
  "a" : {
         "b" : 2,
         "c" : 3
         }
}

Example of Setting an Element in an Array and Setting a New Array

Original document
{ 
  "_id" : "000001",
  "a" : {
         "b" : [1, "stringValue1"]
         }
}
Example code
  public DocumentMutation buildDocumentMutation() {
    return MapRDB.newDocumentMutation()
      .set("a", ImmutableMap.of(
        "b[2]", 2,
        "c", ImmutableList.of(3, ‘stringValue2’, 4));
  }

  public void update(String tablePath, DocumentMutation mutation, String _id) {
    try(Table table = MapRDB.getTable(tablePath)) {
      table.update(_id, mutation);
    }
  }
Revised document
{ 
  "_id" : "000001",
  "a" : {
         "b" : [1, "stringValue1", 2],
         "c" : [3, "stringValue2", 4]
         }
}
NOTE: If an application tries to set a new value in an array and gives the value an index higher than (current largest index) + 1, then the value is given the index (current last index) + 1. For example, suppose that an application tries to set a value at index 5 in an array for which the current largest index is 2. MapR-DB assigns the value an index of 3 when inserting the value into the array.

Permissions Required

Link to Javadoc

DocumentMutation

IMPORTANT: If a DocumentMutation object modifies a field two or more times, only the final operation on that field is applied.

Example One

table.update() in the last line fails with error code 22:

DBDocument doc = MapRDB.newDocument()
        .set("int", 100)
        .set("date", new Date(1000))
        .set("string", "a string");

table.insertOrReplace("doc1", doc);

// Set different fields
DocumentMutation mutation = MapRDB.newDocumentMutation();
mutation.setOrReplace("string", 1000);
mutation.set("string", 2000);

table.update("doc1", mutation);

Example Two

This code results in the document {"string":"a string add3"}, rather than the document {"string":"a string add1 add2 add3"}.

DBDocument doc = MapRDB.newDocument()
        .set("string", "a string");

table.insertOrReplace("doc1", record);

DocumentMutation mutation = MapRDB.newDocumentMutation();
mutation.append("string", " add1");
mutation.append("string", " add2");
mutation.append("string", " add3");

table.update("doc1", mutation);