This article provides a complete overview of the various data types you can use with your queries to retrieve, modify, and sync data in Ditto. In addition, you'll find an introduction to related concepts like conflict resolution strategies.

In Ditto, there's a clear distinction between traditional create, read, update, and delete (CRUD) database operations and data sync.

For CRUD operations, you interact with data stored locally in the Ditto store by invoking a single operation on the store namespace. Once executed, Ditto returns a response object encapsulating the results.

The following table provides a high-level overview of the different ways you can perform CRUD in Ditto:

For syncing, you set up remote listeners, or sync subscriptions, to monitor changes to the data you're interested in. When data changes, Ditto automatically syncs the delta changes to your local Ditto store.

In addition to setting up sync subscriptions to monitor mesh-wide data changes, you can establish local listeners known as store observers to monitor changes in the Ditto store operating locally.

A store observer is a DQL query that runs continuously and, once Ditto detects relevant changes, asynchronously triggers the callback function you defined when you set up your store observer. For instance, when the end user updates their profile, display the profile changes to the end user in realtime.

Ditto stores data in structured JSON-like document objects. Each document consists of human‑readable fields that identify and represent the information the document stores.

The following snippet provides an example of a basic JSON-encoded document object:

A single document consists of one or more fields that self‑describe the data it encodes; each field is associated with a value:

A grouping of related documents is referred to as a collection. Think of a collection as a table in a relational database table — but with greater flexibility in terms of the data it can hold — and the documents in a collection like table rows:

In the following structure, the location field property is logically grouped with details about the car, such as its make, year, and color.

It contains nested fields. also referred to as subfields, representing both the coordinates and the address where the car is located:

Ditto Query Language (DQL) is the platform's dedicated query language for defining criteria for local database operations and data sync with remote peers. For instance, you use DQL to perform various filter operations like traditional CREATE, READ, UPDATE, and DELETE (CRUD) and filter data for sync subscriptions. 

DQL is a familiar SQL‑like syntax designed specifically for Ditto's edge-sync features that enable the platform's offline-first capabilities. DQL offers features like:

The following table provides an overview of the types of statements you'll write in DQL and enclose within your API method operations to specify data selection criteria:



When writing queries with DQL, data formatting is categorized into two categories:

To use a DQL type other than a REGISTER — the default data type in Ditto — you must explicitly specify the type in your query; otherwise, Ditto defaults to the REGISTER type as follows.

Here is an example illustrating the same SELECT statement query explicitly expressed as a MAP structure. It specifies retrieval of the MAP structure storing the"features" collection with a "trim" field property set to a value of "standard":

As the foundation of how Ditto exposes and models data, these data types leverage conflict-free replicated data type (CRDT) technology to ensure that no data inconsistencies occur as a result of concurrent modifications; that is, simultaneous edits made to the same data types in multiples local Ditto stores.

All data types —REGISTER, MAP, and ATTACHMENT— adhere to the causal consistency model when resolving concurrency conflicts.

The causal consistency model is a guarantee that if there is an operation that must happen before another operation — for example, events A and B, where B is a result of A — all peers agree upon and observe the same sequential order of these operations; as in, A always executes before B.

In Ditto's implementation, conflicts are automatically resolved, merged, and synced across peers without the need for coordination or validation from a centralized authority.

Within this consistency model, there are two principles for guiding conflict resolution at merge:

The following table provides a quick overview of the data types you can use to write queries, along with their merge strategies, a brief description, and a common usage scenario:

When you want to embed a hierarchical structure to represent complex parent‑children data structures within a document in DQL, you have the option to nest either of the following:

The decision between the two depends on your specific use case.

For instance, to represent embedded values with dependencies, such as a GPS coordinate along with its corresponding address, structure your data in a JSON object, as follows:

This is because, unlike a MAP, a JSON object functions as a single unit. Managing both the coordinate and address as a cohesive unit ensures that any changes made to one automatically update the other.

To represent embedded values with no dependencies; that is, you want the flexibility to update each key-value pair independently, and structure your data as separate REGISTER fields in a MAP:

To represent highly complex data structures in which you need to establish additional hierarchies, embed a MAP within another MAP, as follows:

The following graphic and corresponding table aim to demonstrate the distinct capabilities and versatility of each DQL type.

An issue unique to MAP data types 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.

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

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

There are two ways of interacting with the Ditto store operating locally on end-user devices:

Establish sync subscriptions to monitor changes to the data you're interested in. The queries defining your data criteria run on all remote stores that are part of the subscription.

When you subscribe to a collection or a specific set of documents, the subscription query is distributed to all relevant stores in the network. Each store executes the query locally and sends updates to the subscriber whenever changes match the subscription criteria.

This topic provides an overview of lazy-load retrieval, memory management, ping-pong effect, and utilizing a MAP to sync concurrent changes.

Understanding these patterns will help you make informed design decisions in your app.

To improve performance, instead of storing a file that encodes large amounts of binary data within a document, consider storing a reference to it in a separate, explicitly fetched object (token) known as an ATTACHMENT.

With the ATTACHMENT data type, you can implement lazy loading. Lazy loading is when you delay retrieval until necessary rather than aggressively fetching the data in anticipation of hypothetical future use. This "on-demand" retrieval pattern enhances performance by optimizing resource usage.

Data storage management is essential for preventing unnecessary resource usage, which affects sync performance, battery life, and overall end-user experience.

Eviction is important for use cases like cabin crew apps where data from the last flight is not needed on the next flight.

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

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

At the same time, peer B calls the Update method to change the value of the mileage field:

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

Following is a table summarizing the risk associated with improperly implemented patterns: