The conflict-free replicated data type (CRDT) data structure enables smooth peer‑to‑peer offline replication and online sync in distributed systems.

When multiple offline Ditto stores make concurrent updates to the same CRDT object, the CRDT merge mechanism remediates the data collision so that, when sync takes place, they converge to a consistent state. For more information, see the Platform Manual > Sync and Replication Concepts.

This topic provides a catalog of the types of CRDTs you can use in Ditto:

To start building your mental model, think of a CRDT as a container holding two essential components: the actual data to store and some metadata that helps in resolving conflicts.

The register type holds the actual data to be stored; each set of fields in a document or key‑value pair embedded in a map function as a single register object.

For example, the following snippet consists of three separate registers:

Since each set of fields in a document and, if embedded within a map, each key-value pair act as a single register, you can structure, organize, and manage your data more efficiently.

You can encode simple data as well as highly-complex datasets in a register:

• To encode simple data in a registers, use primitive JSON-compatible types, such as string, boolean, number, and so on.
• To encode more complex datasets in a register, use a combination of primitive types and register and maps.

The following table provides an overview of the types you can use to store a single value in a register:

Each register adheres to the last-writer-wins principle at merge, ensuring conflict-free replication and data consistency throughout the distributed system.

With last-writer-wins merge semantics, when conflicting updates occur, the update made by the last writer always takes precedence and propagates across peers as the single source of truth — the definitive value.

An extension to the register type, an array is an ordered collection of items represented using any primitive JSON‑compatible data type enclosed within square brackets ([ ]). 

CRDT-based arrays, when compared to typical arrays, have certain strengths and limitations.

While CRDTs excel at managing unordered operations, maintaining a strict order is less efficient, which could potentially lead to data inconsistencies at merge.

The reason for this is because, unlike traditional arrays, the multiple elements within a CRDT-based arrayfunction collectively as a singleregister, and, as previously explained in Ditto Basics, a register is effectively a container that holds multiple elements — the actual data and various metadata — just like regular arrays.

In simple terms, imagine an arraylike a string. Much like a string, each element in a CRDT-based array plays a unique role in determining the final value that ultimately forms; just like the string characters that eventually form a word.

And similar to how you access elements in a typical array, you reference each individual element in a CRDT-based array (a register) by their index. If those indexes change while disconnected from the network, once network conditions improve, they may fail to merge due to concurrency conflicts, resulting in data inconsistencies.

Considering this, avoid using arrays in Ditto and opt for a map instead, which effectively functions as a set, or more commonly known as an associative array.

When managing data that requires unique identifiers and relationships, instead of using an array to encode your data, use a map with unique string keys and object values instead.

With conflict-free replicated data type (CRDT) technology, each document is represented as a map.

A map is a JSON-like object that serves as the basis of each Ditto document and is structured as a collection of field-value pairs:

• To represent simple values in a map, use any primitive data type, such as a string, boolean, number, and so on.
• To represent a highly-complex data structure in a map, use register, counter, array, or embed another map. Embedding a map within another map establishes an additional hierarchy.

Following are the key attributes of the map type:

• A map is represented in the document as a tree-like structure that establishes a hierarchical, parent-child relationship between the dataset in the document. 
• Use maps in scenarios where you want to create a list of items and update that list over time.
• If one peer creates a field within a document as an Array and another peer an object, such as a map or register, the values do not merge.

If you need to represent and organize data in a hierarchical structure, you can embed a map within another map to establish a parent-child relationship within a document:

When updating and adding fields to a map embedded within another map, use keypath indexing. Also referred to as dot syntax, a keypath index concisely specifies the fields to update when working with a map embedded within another map.

In a keypath index, each dot (.) represents a level in the map hierarchy. For example, friends.foo indicates that the foo field is a child of the parent friends map, as demonstrated in the following snippet.

By calling the .remove() API method, as follows, you omit only the foo field from the friends map within the document, while the other fields within the friends map remain unaffected:

The following snippet results in all of the values in the friends map being replaced with the new object:({ "beep": "boop" }):

Since CRDT map values merge with the existing document, simply omitting them from the CRDT map does not remove them.

Instead, the CRDT map creates an operation for that field and subsequently the existing fields remain unchanged.

By calling the .remove() API method, as follows, you omit only the foo field from the friends map within the document, while the other fields within the friends map remain unaffected:

When you want to clear the entire map structure embedded in the document, call the .set() method.

For example, the following snippet illustrates the process of removing the friends map through the .set() method, making it empty.

An issue unique to maps is the possibility for two offline peers to create a new document, in which one peer represents the field as an object (map), while the other peer represents the field as an array.

Because peer A and peer B use divergent data structures, combining an array with an object (map) is impossible. Rather than adhering to the default "last updated type" win principle, which might trigger a ping-pong alteration of types between the peers, retain both values for the address property.

A ping-pong alteration of types occur when distinct peers repeatedly modify the data type of a specific field in response to each other's updates, leading to a forever loop of back‑and‑forth behavior.

To avoid the ping-pong effect when conflicts between data types occur, retain both the array and the map object representations of the field in the document. For example, in the previous scenario, you keep both versions of the conflicting representation of the address field in the document.

Retaining both the array and map representations:

• Prevents back-and-forth, ping-pong behavior
• Ensures that there is no loss of data
• Provides flexibility, allowing you to choose the data type that is most appropriate for encoding data in JSON based on your specific requirements and use case

The best approach to handle conflicts that result from two peers making concurrent offline edits and then later rejoining online depends on your specific requirements and use case.

Following is an overview of best approaches for handling concurrency conflicts:

• Resolving concurrency conflicts — If you want to give priority to the "latest" change, use a register. Ditto's register type use Last-Write-Wins semantics so the value written last always becomes the current value.
• Auditing concurrency conflicts — If you want to keep track of the changes made by different peers over time, use the map type to model your list of operations. Each write operation is independently tracked as a field-value pair, with the field representing the unique identifier and the value storing only the specific changes made by a given peer.
• Prompting end users to choose — If you want your end users to resolve concurrency conflicts instead of Ditto, use the map type inside of your document and prompt end users to select the value to replicate.

The counter CRDT is a special type intended for use cases where multiple peers need to increment (or decrement) field values at the same time while maintaining consistency; for example, in scenarios such as inventory management or voting. 

There are two methods of modifying an existing counter value:

• Increment — Increases the counter value by the specific number you want to add to the counter value.
• Decrement — Decreases the counter value by the specific negative value that you want to subtract from the counter.

To create a counter, use the upsert method to ensure the document exists in Ditto, and then use the .update() method to increment the counter and ensure that the correct and accurate counter value is maintained across all peers during replication:

A counter is capable of recalling its previous increment and decrement calls; however, with a counter there is no concept of time. This is true even if you change the type of a counter to another field, such as number, and then back into a counter again.

Given this constraint, avoid resetting counters. Instead, create new documents or collections that have meaning and encapsulate a period of time.

With the attachment CRDT you can associate very large amounts of binary data, such as an image, video, and so on, with a document and replicate across peers without conflict.

If you have very large amounts of binary data, such as a high-resolution image, video, or some other file above 50 megapixels, or if you have a deeply-embedded or a large document object, use an attachment instead of a regular document.

Unlike documents, attachments store data outside of the Ditto store running locally in the end-user environment and must be explicitly fetched to replicate across distributed peers.

For more information about Ditto documents, see the Platform Manual > Document Model.

Maintain a strong reference to attachmentFetcher for the entirety of the asynchronous fetch operation by following these guidelines:

• Preserve the attachmentFetcher as a globally accessible instance
• Prevent the fetch operation from silently aborting

The following snippet demonstrates the process for creating, associating, and fetching anattachment.

1. Define a collection named 'foo'.
2. Using Base64-encoded image data and metadata, create an attachment object .
3. Upsert a document with an attachment in the collection.
4. Later, retrieve the document by _id and fetch the attachment using an attachmentFetcher.