Ditto provides a flexible and efficient way to store and manage data so you can efficiently sync data for a wide range of use cases.

Different data structures in Ditto have distinct behaviors and characteristics that you'll need to be familiar with to achieve your specific goals.

This article provides a quick overview of Ditto's schema-flexible document model and advanced data types.

Each document is nested with a hash-stable tree structure that self-describes the data to be stored and provides the predetermined rules that ensure data consistency and accuracy.

In simpler terms, each document in Ditto is essentially a key-value pair, where the key is a name (string) and the value can be any supported type in Ditto, which includes maps. For more information, see Fields, as follows.

In Ditto’s document model, the supported data types depend on the CRDTs associated with the document. For more information about CRDTs, see the Platform Manual > Data Types and Document Model.

The following snippet provides an example of a basic JSON‑like document object:

Syncing large documents can significantly impact network performance. Instead of storing files exceeding 250kb directly within a document object, carefully consider using attachments .

For more information, see any of the following:

A document consists of sets of fields that self‑describe the data it encodes. Each set signifies a single pair of two associated elements:

Required and randomly generated and assigned by default upon creation, the first set of fields identifies the document. (See Document Identifiers)

Ditto automatically generates and assigns each new document a unique identifier, or _id.

However, if desired, you can pass your own custom _id as a parameter in the upsert function you use to create a new document. (See CRUD Fundamentals)

In addition to having the option to supply your own _id, in complex scenarios where you want to create a more intricate and unique identifier for your documents, you can combine two or more distinct elements to form a composite key.

For more comprehensive information and how-to instructions, see the Platform Manual > CRUD Operations > Upserting and Updating.

If there is a set of documents that contain the same commonly-queried field, such as a string reference to cars, you can optimize query speed and reduce peer storage usage by grouping them in an index, or a collection.

The following snippet and corresponding table provide an example of a string reference to the collection cars.

To help better understand, think of a collection like a SQL database table and the documents it holds like table rows: 

To improve performance, instead of storing a file that encodes large amounts of binary data as a document, you can opt to store it as a separate, explicitly fetched object known as an attachment.

With the attachment CRDT, you can sync between peers without querying and merging.

For more comprehensive information and how-to instructions, see the Platform Manual > Data Types > Attachment.

The following table provides a complete overview of the relationships you can establish in Ditto:

For more information, see Ditto Basics > CRUD Fundamentals and Platform Manual > CRUD Operations.

As a semi-structured distributed database, Ditto leverages conflict‑free replicated data types (CRDT) technology to enable advanced data exchange capabilities. 

To get the most out of Ditto, you'll need to work with one or more CRDTs. Theregister type is the most common and simple type to use. 

For more information, see Platform Manual > Register.

The following table provides a quick overview of the advanced data types you can use in Ditto, along with their guiding principles for conflict resolution, or merge semantics, a brief description, and a common usage scenario: