Upserting and Updating

This article provides an overview of the Upsert and Update operations:

Key Distinctions

The following table provides an overview of key distinctions between the Update and Upsert methods:

	Upsert Operation	Update Operation¹
Fetching	Unlike Update, does not directly apply changes; you must first retrieve the document.	Directly applies changes to an existing document without needing to fetch it first.
Document Existence	Does not require the document to exist in Ditto — if the document does not already exist, Ditto automatically creates (inserts) one to store the given fields.	Requires that the document, with the given ID, already exists in Ditto.
Update Behavior	Unlike the update operation, if you perform an upsert with the entire document, rather than with only the specific fields that have changed, the upsert operation modifies all document fields, even if their values remain the same.² To maximize efficiency, when invoking the Upsert method to make changes, instead of upserting the entire document, only upsert the specific fields that have changed.	Maximum efficiency due to optimistic caching: Targets a field locally and, if changed, proceeds to apply the delta update to it. This behavior is the opposite of the upsert operation, which modifies all document fields provided in your upsert, even if their values remain unchanged.³
Performance	Ditto transmits only necessary data changes, the delta, during both upsert and update operations. However, upsert operations may result in network degradation due to their update behavior.³	More efficient since you do not first fetch a document and then apply updates to it separately.

¹Not supported in Java

²With Ditto’s conflict-free replicated data type (CRDT) technology, a field is not just the value itself but also the time at which the value was sent, known as the Hybrid Logical Clock (HLC). So although the actual value remains unchanged, at the system level, the field is marked as changed. (See Sync and Replication Concepts) ³In Ditto, the absence of data does not equate to the removal of data; therefore, when you upsert with only specific fields, Ditto updates only those fields; the data that is absent in your upsert operation is unchanged.

Upsert

Use the Upsert method to achieve any of the following:

Making changes only to targeted fields
Creating a new document
Configuring a custom document ID

For instructions on how to create a new document, see Upserting and Updating.

The following snippet provides the standard upsert syntax, consisting of the document object that you want to upsert and the options you want to set for the upsert:

let documentId = ditto.store
  .collection("your_collection_name")
  .upsert(document, options: options)

Creating New Documents

When writing updates by way of the Upsert function:

If the document already exists, Ditto updates the document with the delta changes.
If the document does not exist, Ditto automatically creates one.

If not manually supplied, Ditto automatically assigns the new document a unique ID as follows:

let docId = ditto.store.collection("your_collection_name").upsert(document)

Supplying a Custom ID

When invoking the Upsert method to create a new document, unless manually supplied, Ditto automatically generates and assigns the new document a 128‑bit Universally Unique Identifier (UUID).

To configure a custom identifier, when invoking upsert to create a new document, pass the _id parameter in your function.

If supplying your own document ID, you can encode your value in a string or, if forming a composite key, a JSON-object.

You can configure a custom document ID only at the time of document creation.

Once a document is created, to ensure consistency and uniqueness throughout the platform, the unique identifier that either Ditto automatically generated and assigned or you manually assigned becomes permanent and cannot be changed at a later time.

For more information about document IDs, see Platform Manual > Document Model.

String ID

For example, the following snippet demonstrates a new document assigned the custom ID abc123.

do {
    // upsert JSON-compatible data into Ditto
    let docID = try ditto.store["people"].upsert([
        "_id": "abc123",
        "name": "Susan",
        "age": 31
    ])
    print(docID) // "abc123"
} catch {
    //handle error
    print(error)
}

Following is the new abc123 document that results:

{
  "_id": "abc123",
  "name": "Susan",
  "age": 31,
}

Composite ID

The following snippet demonstrates combining the user_id and work_id fields to form the 456abc789 composite key:

To mitigate the risk of human error when working with composite keys during write operations, it is recommended to use no more than three fields to form your key.

do {
    let docID = try ditto.store["people"].upsert([
        "_id": [ "userId": "456abc", "workId": 789 ] as [String : Any],
        "name": "Susan",
        "age": 31
    ])
    print(docID) // "[ "userId": "456abc", "workId": 789 ]"
} catch {
    //handle error
    print(error)
}

Upserting Delta Updates

An upsert operation is a combination of the traditional update and insert operations, in which you can insert a new document if it doesn't already exist or update an existing document if it does. This allows you to handle both scenarios within a single operation.

Using the upsert method to update data can cause performance to degrade. To optimize performance and reduce unnecessary overhead, apply most updates in your app through the update method instead. For more information, see Optimizations.

For example, imagine you create the following document in the cars collection:

let docID = try ditto.store["cars"].upsert([
    "_id": "123456",
    "make": "Toyota",
    "color": "blue",
    "year": 2024
])

Once executed, the following document is created as a result:

{
  "_id": "123456",
  "model": "Toyota",
  "color": "blue",
  "year": 2024
}

When you upsert changes, only the fields you supplied will be modified; existing fields remain unchanged. For instance, consider the following Upsert in which you change the color "blue" to "red":

do {
    // find the document by ID
    let document = try ditto.store["cars"].findByID("123456")
    
    // change the color to "red"
    try document?.update({ mutableDoc in
        mutableDoc?["color"] = "red"
    })
} catch {
    // handle error
    print(error)
}

As a result, the color changes to "red"; however, make and year remain the same:

{
  "_id": "123456",
  "model": "Toyota",
  "color": "red",
  "year": 2024
}

Update

Update operations ensure that only the minimum data necessary to enforce all peers converge on one view of the data replicates across the mesh.

ditto.store["your_collection_name"]
  .findByID("document_ID")
  .update([your update function])

Overview of Behavior by CRDT

Updating an existing document is different depending on the CRDT you're updating:

Operation	Description
set register	Sets the value for a given field in the document.
set map	Sets value for a given field in the map.
remove register	Removes a value for a given field in the document.
remove map	Removes a value for a given key in the map structure.
replace with counter	Converts a number value for a given field into a counter.
increment counter	Unlike a number, increments the counter by the given positive integer value.
decrement counter	Unlike a number, decrements the counter by the given negative integer value.