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.
For a high-level overview of the data types you can use when writing queries in DQL, see Data Types.
A REGISTER stores a single scalar value. You can encode the value using any JSON‑compatible 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:
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
true or false
Signed 64-bit integer
Embedded JSON blob
Represents an absence of a value
Unsigned 64-bit integer
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.
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.
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.
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.
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:
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: