Upserting and Updating

23min

This article provides an overview of the upsert and update operations:
﻿Key Distinctions﻿﻿
﻿Update﻿﻿
﻿Upsert﻿﻿
Key Distinctions 
Following are key distinctions between the update and upsert API methods:
﻿
upsert
update¹
Purpose
Does not directly apply changes; you must first retrieve the document. 
Directly apply changes to an existing document without needed to first fetch it.
Document Existence
Does not require the document to exists in Ditto — if the document does not already exists, Ditto automatically creates (inserts) one to store the given fields.
Requires that the document, with the given ID, already exists in Ditto.
Performance
Less efficient since upserting involves checking whether a document with the given ID already exists and then, as a separate operation, applying the given updates. 
More efficient since you do not first fetch a document and then apply updates to it separately.
Behavior
Optimistic caching: Targets a field locally and, if changed, applies the delta update. 
Updates an entire document, even the document fields that remain unchanged.
¹Not supported in Java
﻿
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:
Swift
Kotlin
JS
Java
C#
C++
Rust
|
let documentId = ditto.store
  .collection("your_collection_name")
  .upsert(document, options: options)
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: 
Swift
Kotlin
JS
Java
C#
C++
Rust
|
let docId = ditto.store.collection("your_collection_name").upsert(document)

// documentId = "507f191e810c19729de860ea"
let docId = ditto.store.collection("your_collection_name").upsert(document)

// documentId = "507f191e810c19729de860ea"
﻿
Supplying a Custom ID
Each document must be assigned a unique identifier. 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 stringor, if forming a composite key, a JSON blob object made up of two or more values of the string or number type. 
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.
Swift
Kotlin
JS
Java
C#
C++
Rust
|
do {
    // upsert JSON-compatible data into Ditto
    let docID = try ditto.store["people"].upsert([
        "_id": "abc123",
        "name": "Susan",
        "age": 31
    ])
    XCTAssertEqual(docID, "abc123")
} catch {
    //handle error
    print(error)
}
do {
    // upsert JSON-compatible data into Ditto
    let docID = try ditto.store["people"].upsert([
        "_id": "abc123",
        "name": "Susan",
        "age": 31
    ])
    XCTAssertEqual(docID, "abc123")
} catch {
    //handle error
    print(error)
}
﻿
Following is the new abc123 document that results:
JSON
|
{
  "_id": "abc123",
  "name": "Susan",
  "age": 31,
}
{
  "_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.
Swift
Kotlin
JS
Java
C#
C++
Rust
|
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)
}
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:  
Swift
Kotlin
JS
Java
C#
C++
Rust
|
let docID = try ditto.store["cars"].upsert([
    "_id": "123456",
    "make": "Toyota",
    "color": "blue",
    "year": 2024
])
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:
JSON
|
{
  "_id": "123456",
  "model": "Toyota",
  "color": "blue",
  "year": 2024
}
{
  "_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":
Swift
Kotlin
JS
Java
C#
C++
Rust
|
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)
}
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:
JSON
|
{
  "_id": "123456",
  "model": "Toyota",
  "color": "red",
  "year": 2024
}
{
  "_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.
﻿
Swift
Kotlin
JS
Java
C#
C++
Rust
|
let collection = ditto.store["your_collection_name"];
let document = collection.findByID("document_ID");

if let Some(document) = document {
    let updatedDocument = your_update_function(&document);
    collection.update(updatedDocument);
}
let collection = ditto.store["your_collection_name"];
let document = collection.findByID("document_ID");

if let Some(document) = document {
    let updatedDocument = your_update_function(&document);
    collection.update(updatedDocument);
}
﻿
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.
﻿
﻿

Updated 29 Sep 2023

Did this page help you?

Finding and Observing

Evicting and Removing

Docs powered by

Archbee

TABLE OF CONTENTS

Key Distinctions

Upsert

Creating New Documents

Supplying a Custom ID

String ID

Composite ID

Upserting Delta Updates

Update

Overview of Behavior by CRDT

	upsert	update¹
Purpose	Does not directly apply changes; you must first retrieve the document.	Directly apply changes to an existing document without needed to first fetch it.
Document Existence	Does not require the document to exists in Ditto — if the document does not already exists, Ditto automatically creates (inserts) one to store the given fields.	Requires that the document, with the given ID, already exists in Ditto.
Performance	Less efficient since upserting involves checking whether a document with the given ID already exists and then, as a separate operation, applying the given updates.	More efficient since you do not first fetch a document and then apply updates to it separately.
Behavior	Optimistic caching: Targets a field locally and, if changed, applies the delta update.	Updates an entire document, even the document fields that remain unchanged.

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.