Data Structures and Types

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 objects and /#advanced data types for an overview of the various operators and path navigations you can use to construct sophisticated queries in your app, see platform manual > docid\ mmtismykr3hxzmys1bi2w schema flexible document objects ditto stores data in structured json like document objects each document consists of sets of human‑readable fields that identify and represent the information the document stores 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 supported types 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 > docid\ yxemkh1com3csuumqcnlf and docid\ amty0ophec33hdf 1iohz the following snippet provides an example of a basic json‑like document object { " id" "123abc", "name" "sam", "age" 45, "isonline" false } document size and sync performance syncing large documents can significantly impact network performance instead of storing files exceeding 250kb directly within a document object, carefully consider using attachments caution is advised when handling large binary data, such as a high‑resolution image or video exceeding 50 megapixels; a deeply embedded document; or a very large document for more information, see any of the following ditto basics > /#attachment objects , as follows platform manual > document model docid 8knpxrwcdkfknw8zeaijr docid\ iduhisa7kwnfaowgqwrp9 docid\ lqgzvvhtqzybx ald5b8j platform manual > data types > docid\ slqobcnxtyf keli7l8f8 fields a document consists of sets of fields that self‑describe the data it encodes each set signifies a single pair of two associated elements the name identifying the data (see docid 01cwczyxg4mgpz90xn6oe ) the value that holds the actual data to store (see docid 01cwczyxg4mgpz90xn6oe ) required and randomly generated and assigned by default upon creation, the first set of fields identifies the document (see /#document identifiers ) document identifiers the first set of fields within each document uniquely identifies the data that its document object encodes when grouped in a collection, this id serves as the primary key identifying the document in the collection 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 docid\ byukq4ekkuevjbx feuog ) 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 > docid 1cexfnswhjeqa r6yyl 8 > docid\ l2hfjvzuyynu5ahzxhwaj collection indexes 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 const carscollection = ditto store collection('cars') to help better understand, think of a collection like a sql database table and the documents it holds like table rows attachment objects 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 a realworld usage scenario, see either the demo chat app for ios or android in the getditto > https //github com/getditto/demoapp chat/tree/main github repository for instance, in the https //github com/getditto/demoapp chat/tree/main/ios , you can see a savvy implementation of attachment with a full resolution avatar image from a collection named user for more comprehensive information and how to instructions, see the platform manual > data types > docid\ yxemkh1com3csuumqcnlf relationship models there are several methods for linking related data items and organizing them for easy lookup embedded json object that acts as a register type embedded map field referencing another document all three approaches use a foreign key relationship to establish a structure resembling a parent child hierarchy in this hierarchy, the key functions as the parent, and its encapsulated values, represented as a set of key value pairs, serve as children the choice between a map and an embedded json object that functions as a register depends on your app's usage patterns and the specific conflict resolution requirements in your data model the following table provides a complete overview of the relationships you can establish in ditto relationship description approaches one to many associates a parent element with children elements to establish a hierarchy embed a map reference a field to a document reference a document to a collection many to many associates multiple entities in one collection with multiple entities in another collection embed a map list items in an array create references between documents in different collections many to one associates two or more collections, where one collection refers to the primary key of another collection to create a meaningful relationship between the datasets embed a map create references between documents in different collections for more information, see ditto basics > docid\ byukq4ekkuevjbx feuog and platform manual > docid 1cexfnswhjeqa r6yyl 8 advanced data types 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 the register type is the most common and simple type to use for more information, see platform manual > docid\ yxemkh1com3csuumqcnlf overview 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 in ditto’s document model, the supported primitive data types depend on the crdts associated with the document for an overview of the data types that each crdt allows, see platform manual > docid\ yxemkh1com3csuumqcnlf type merge semantics description use case register last‑write‑wins register, delta state replication stores a single value and allows for concurrent updates updates associated with later temporal timestamps always win map add wins map, delta state replication working in conjunction with the register, stores the mapping of temporal timestamps to the values written in the register to help resolve concurrency conflicts make a list of items in a document and update those items over time counter positive or negative counter, the sum of all site id counters, delta state replication converts a number value for a given key into a counter unlike a primitive number , value increments and decrements merge without conflict manage inventory and handle votes, such as stock details and survey results attachment last write‑wins register, merges only when explicitly fetched stores very large amounts of binary data, such as an image file, and allows for concurrent updates reduce small peer resource usage by storing data outside of memory array last‑write‑wins register, delta state replication an extension of the register type,