Document Model
Data Types

REGISTER

The REGISTER type is the core building block of every app built on Ditto. This article provides an overview of the REGISTER type, including its merge strategy and the various scalar subtypes you can use to encode single values within a REGISTER.

Supported Scalar Subtypes

A REGISTER stores a single scalar value. You can encode the value using any JSONcompatible scalar subtype, such as a string, boolean, JSON object to represent two or more fields as a single object, and so on.

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

Data Type

Corresponding Values

array

An ordered list of values, where each value represents any primitive type, as well as nested collection types such as other arrays or MAP type

boolean

true or false

float

64-bit floating-point

int

Signed 64-bit integer

JSON-object

Embedded JSON blob

null

Represents an absence of a value

string

UTF-8 encodable

unsigned int

Unsigned 64-bit integer

Example Updating a REGISTER

For example, the following snippet shows a basic UPDATE statement query setting the values of two separate REGISTERS:

  • A REGISTER storing a string set to the value 'blue'.
  • A REGISTER storing an integer set to the value 3001.
DQL


Limitations to Arrays

Unlike typical arrays, the multiple elements within an array scalar subtype function collectively as a single REGISTER with last-write-wins merge behavior. An array scalar subtype is an ordered collection of items represented using any primitive JSON‑compatible data type enclosed within square brackets ([ ]). 

The array scalar subtype, while great at managing unordered operations, such as a GPS coordinate where both latitude and longitude values change together, as follows, maintaining a strict order could potentially lead to data inconsistencies at merge.

JSON


Considering this, when managing collections of data that have concurrent editors, opt for a MAP instead, which effectively functions as a set, more commonly known as an associative array. For more information, see MAP.

Last-Write-Wins Merge Strategy

The REGISTER type adheres to the last-write-wins principle when handling concurrency conflicts. This means that when changes occur, all peers observing the change will sequence these changes in the same order. This ensures that only a consistent single value syncs across the entire peer-to-peer mesh.

For example, one flight attendant updates a customer's seat number to 6 and another to seat 9. When the two conflicting versions merge, the edit with the highest timestamp wins.

Put another way, by enforcing the last-write-wins merge strategy, for events A and B, where B is a result of A, event A always occurs before B.

Syncing with REGISTER

Each REGISTER in a document syncs independently. When the value that the REGISTER holds changes, the entire REGISTER value syncs across the mesh.

For example, the following code, once executed, results in the field color being changed and the value 'blue' being synced across peers:

DQL


Since a REGISTER acts as a single object, to update just the color, you'd need to update the entire object by providing the entire set of nested key-value pairs, including the modified color , as follows:

Swift
Kotlin
JS
Java
C#
C++
Rust




Updated 13 Mar 2024
Did this page help you?