Platform Manual
Data Types

Map

With conflict-free replicated data type (CRDT) technology, each document is represented as a map. A map is useful when you want to create a list of items and update items over time within a document.

Basic Structure

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.

The following snippet demonstrates a Ditto document with an embedded map:

JSON


Characteristics and Behaviors



Embedding a Map

To create a single map represented as a JSON-like root object in the document, use the following data model:

Swift
Kotlin
JS
Java
C#
C++
Rust


JSON


Updating a Map



Preferred: Set Specific Value

By calling the Remove 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:

pseudocode


Not Recommended: Update Entire Map

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

pseudocode


Removing a Map

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.

Preferred: Update Specific Value

By calling the Remove 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:

pseudocode


Not Recommended: Update Entire Map

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.

pseudocode


Handling Type-Level Concurrency Conflicts

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.

Example Scenario: Divergent Types Preventing Merge

The following snippets illustrate a scenario of a type-level conflict unique to maps. Peer A creates the following new document:

JSON


While at the same time Peer B creates the following new document:

JSON



Preventing the Ping-Pong Effect



Managing Concurrency Conflicts: Update History



Example Scenario: Using a Map for Concurrent Updates

Imagine a scenario in which two Ditto stores, peer A and peer B, have the following document:

JSON


Peer A calls the Upsert method to change the field-value color:red to color:blue:

Kotlin
JS


While at the same time peer B calls the Update method to change the value of the mileage field:

Kotlin
JS


When the changes replicate across the distributed peers, both changes merge resulting in both peer A and peer B Ditto stores having the mileage increment of 200 and the color change to blue:

JSON




Updated 11 Mar 2024
Did this page help you?