Used by conflict-free replicated data types (CRDTs) to identify the source or author of a data mutation. An actor is composed of a SiteID and the site’s current epoch. Actors enable Ditto to track which peer made each change, allowing proper conflict resolution during data merges.
A component for storing large binary files separately from documents. Attachments are referenced by documents via attachment tokens but must be explicitly fetched—they do not automatically sync with document subscriptions. Once created, attachments are immutable; to update, create a new attachment and replace the token in the document.See also: Blob Store
An HTTP service hosted by the developer which receives credentials and responds with metadata about the user and which permissions they should have. The Identity Service uses this information to dynamically produce the required certificates. Configured through the Portal.
A proprietary Apple-developed technology that establishes a point-to-point Wi-Fi connection between two Apple devices. When available in their environment, Small Peers utilize AWDL to create a mesh network connection and replicate data. AWDL provides faster transfer speeds than Bluetooth LE.
An internal component which offers general blob storage. Used by any internal Ditto components which need to persist “files”. The blob store does not necessarily require a true filesystem and might operate purely in memory.
A wireless technology for short-range communication that serves as one of Ditto’s primary transports. Bluetooth LE operates in two modes: GATT (slower, wider compatibility) and L2CAP (faster, newer devices). It enables peer-to-peer synchronization without internet connectivity.
Bring Your Own Cloud. A model for deploying the Ditto Platform managed by Ditto in your own cloud account where you (the customer) share responsibility and control over the account—and therefore the cost, security, and compliance needs—with Ditto.
The cryptographic root of trust for all identities and certificates within a Ditto Application. Originally this was a standard X.509 CA for peer TLS certificates, but its role has expanded to include JWT and In-Band Certificate signatures. It is by knowing the public keys of the CA that one offline peer can verify the authenticity of another offline peer.
A bidirectional message-oriented data flow running over the top of a Virtual Connection. These can offer reliable or lossy delivery characteristics and be opened either mutually or as a client/server type relationship. Channels are protocol-agnostic, like TCP/UDP, and are consumed by Services.
Also known as the “Mesh Chooser”, a stateful algorithm which decides at any moment which outgoing connections should be made. This considers the peers currently connected, the peers whose advertisements have been detected by transports, and past failures.
A grouping of documents under a name. Loosely equivalent to a table in SQL terms. An app may have many collections. Each document within a collection must have a unique _id field (primary key).
An advanced class of data type designed to manage and replicate data changes in a way that allows multiple distributed peers to make updates concurrently without the need to reach consensus. CRDTs automatically merge to form a single meaningful value.Ditto implements several CRDT types:
A bandwidth optimization technique where only field-level changes (not entire documents) are transmitted between peers. This minimizes network usage and is especially important for battery-constrained devices and low-bandwidth connections like Bluetooth LE.
A physical hardware unit (smartphone, tablet, IoT device, etc.) that can run Ditto-enabled applications. A single device can host multiple peers when running multiple Ditto-enabled applications or multiple Ditto instances within one application. Distinct from Small Peer, which refers to a Ditto SDK instance.
A cluster of servers that can run on-premises or in the cloud, augmenting the SDK’s local-first capabilities with cloud-based synchronization, identity management, monitoring, and data integration features. Previously called Big Peer.
A schema-flexible unit of data contained in a collection; analogous to a row in a table. Each document must have a unique _id field (primary key) which is immutable after creation, and each field is backed by a specific CRDT type.
A SQL-like query language for interacting with Ditto documents. DQL uses string-based queries executed via ditto.store.execute(). It features SQL-like syntax, schema-less document orientation, and does not support JOIN operations in current versions.
A configuration option (SDK 4.11+) that enforces structure and CRDT type safety in collections. When enabled (default), all fields are treated as REGISTER by default. When disabled, objects are automatically treated as MAPs with field-level merging. All peers must use the same DQL_STRICT_MODE setting for consistent behavior.
A concept which identifies a “version” of a peer’s CRDT knowledge. Used by replication and CRDT to identify whenever a peer has changed in some fundamental way that obsoletes prior knowledge of them. An Epoch changes each time a peer performs data Eviction.
The process a peer takes to deliberately “forget” data locally. Unlike DELETE, eviction is a local-only operation that does not propagate to other peers, does not create tombstones, and immediately frees disk space. Evicted data may resync if an active subscription matches it. Important for use cases like cabin crew apps where data from the last flight is not needed on the next flight.
An older, slower mode of Bluetooth LE data transfer with typical speed of 3 to 6 kB/s. Works back to very old Android and iOS phones. Where possible, the Bluetooth transport upgrades a connection to L2CAP.
A partially deleted document that results from concurrent DELETE and UPDATE operations on the same document. When these operations merge, Ditto’s CRDT combines them field-by-field, resulting in a document with some fields set to null and others containing updated values.Example scenario:
Device A executes DELETE (sets all fields to null)
Device B executes UPDATE concurrently (updates specific fields)
After sync: Document has mix of null and updated fields
Prevention: Use logical deletion instead of DELETE for documents that may be updated concurrently.
Used to track when mutations occurred to a CRDT, or component thereof. A Ditto HLC combines a physical clock portion (the local timestamp on a peer as Unix milliseconds) together with a logical portion (a number unique to each peer that increases by one with each change they make).
A complex parameter passed to Ditto at startup which defines how you will authenticate yourself and verify who other peers are, and whether they’re using the same Application as you. Modes include Online Playground (development only), Online with Authentication (production with granular permissions), and Shared Key (air-gapped environments). Some modes rely on the application having a common CA.
The data which the CA asserts about a participant in the mesh. It includes their Peer Key, SiteID, permissions, and other arbitrary data returned by the Authentication Webhook such as email address, job title, and so on.
The part of Ditto Server which handles login requests, invoking Authentication Webhooks if required, and generating the cryptographic material for peers to authenticate each other by acting as the CA.
A bespoke binary format that a Certificate Authority can sign to assert that a given Identity Data is valid and matches a particular key. Plays the role of a TLS X.509 certificate in non-TLS situations.
A data structure (SDK 4.12+) that improves query performance for large datasets by enabling faster lookups on specific fields. Currently supports simple indexes on single fields only, and is most effective for highly selective queries that return a small percentage of documents.
As per the Random Slicing algorithm, the keyspace is the range 0 to 1. The capacity of the cluster is used to divide 1, determining how much of the keyspace each partition owns.
A network transport that enables Ditto peers to communicate over a shared local network, such as Wi-Fi or Ethernet. LAN provides higher throughput than Bluetooth LE and is one of the transports used to form the Ditto mesh network.
An encrypted connection between two peers who are not directly connected, with traffic routed via intermediate peers. Used for multi-hop sync via Query Overlap Groups, and Ditto Bus.
An object that monitors database changes in the local store matching a given query over time, enabling real-time UI updates as data changes locally or syncs from other peers. Previously referred to as “Observer” or “Live Query.” Created via registerObserverWithSignalNext (recommended, with backpressure control) or registerObserver (simpler, without backpressure control).
A soft-delete pattern where documents are marked as deleted (e.g., isDeleted: true) but not physically removed from the database. This approach avoids zombie data problems and husked documents that can occur with physical DELETE operations.
A CRDT type that stores object properties using an “add-wins” strategy. When multiple offline peers make concurrent updates to different keys in a MAP, both changes are preserved after sync (field-level merging). Prefer MAP structures over arrays for data that may be updated concurrently by multiple peers.
A network topology where peers connect directly to each other (peer-to-peer) without requiring a central server. Ditto creates mesh networks using multiple transports including Bluetooth LE, P2P Wi-Fi (AWDL/Wi-Fi Aware), LAN, and WebSockets.
Mutual Transport Layer Security, a security protocol where both parties in a connection authenticate each other using certificates. Ditto uses mTLS (TLS 1.3) by default to encrypt data in transit between peers, ensuring that only authorized peers can communicate within the mesh network.
The ability for Ditto to relay documents through intermediate devices that are not directly connected. An intermediate device can only relay documents it has in its local store—if a device’s subscription is too narrow, it won’t store certain documents and cannot relay them to other devices.
A synchronous machine inside a Virtual Connection to a single remote peer, performing packet fragmentation and reassembly for all of the Physical Connections arriving from various transports.
An architectural approach where applications are designed to function fully without network connectivity. In Ditto, this means the local database remains readable and writable offline, and data automatically merges with other peers when connectivity is restored. This is a core design philosophy of the Ditto platform.
A type of Identity where peers do not need unique credentials to log in and everybody has read and write access to everything. Development and testing only—not secure for production use.
An instance of the Ditto SDK running within an application. Each peer has a unique identity and participates in the mesh network independently. A single device can host multiple peers when running multiple Ditto-enabled applications. Peers synchronize data with other peers based on their subscriptions.See also: Small Peer, Ditto Server
A P-256 private key generated and persisted on every device that runs Ditto. This is the primary unique identifier for each peer and its ECDSA signatures are used to prove authenticity. It is unrelated to CRDT actor IDs.
Any mechanism for establishing direct Wi-Fi connections between devices without needing a router in between. AWDL is one such technology for Apple devices, and Wi-Fi Aware is another for Android devices.
A specification of which documents a given peer can read or write. This is presented as a list of specific collection names, and a sublist of query strings for each collection. Documents must match one of those DQL queries to be readable or writable. Permissions can only be specified on the immutable _id field. If using an Online with Authentication identity, permissions can be locked down; other identity types have no CA and let everybody access anything.
A low-level network connection established through a specific transport mechanism (such as Bluetooth LE, LAN, or WebSocket). Multiple Physical Connections can be combined by the Multiplexer into a single Virtual Connection for improved reliability and throughput.
The part of Ditto responsible for building a picture of all peers in the surrounding mesh, including rich peer info such as SDK version, device names, and which transports are active. This information is used as the basis for routing and can be visualized with the presence viewer.
A set of peers whose subscriptions overlap, enabling them to relay documents to each other through multi-hop sync. When peers share overlapping queries, they can act as intermediaries for data synchronization even if the source and destination peers are not directly connected.
The result returned from ditto.store.execute() containing a collection of QueryResultItems. Treat QueryResults like database cursors that manage memory carefully.
An individual item within a QueryResult. Uses lazy-loading for memory efficiency—items materialize into memory only when accessed. QueryResultItems should be treated like database cursors; extract needed data immediately and do not retain them between Local Store Observer callbacks.
A CRDT type that stores scalar values (strings, numbers, booleans) and arrays using a last-write-wins strategy. When multiple peers update the same REGISTER field concurrently, the most recent write (by HLC timestamp) wins.Important for arrays: Arrays are treated as REGISTERs—the entire array is atomically replaced on update. Avoid using arrays for data that multiple peers may modify concurrently; use MAP structures instead.
The process of synchronizing data between peers in the Ditto mesh network. Replication is driven by subscriptions and uses Delta Sync to transmit only changed fields. The Replication Service handles document sync over Channels.
A query that runs on connected peers that results in changes being sent back to the initial peer when changes are made to the remote peers’ local database. See Subscription.
A unique identifier for a peer which identifies any CRDT document mutations they author. Also has been used as unique peer identifier generally, but this is being phased out in favor of the Peer Key.
A device running applications built with Ditto SDK. Implies that all devices running on Ditto SDK are potential peers in the meshed network. Also referred to as “Edge Peers.”
The local database component of the Ditto SDK, accessed via ditto.store. The Store provides methods for executing DQL queries, registering Local Store Observers, and managing attachments. All data operations go through the Store, which maintains the local copy of synchronized data.
A query from the replication perspective, whereby one peer requests any data that matches this query from other peers to synchronize. Created via ditto.sync.registerSubscription(). Subscriptions tell Ditto what to sync; without active subscriptions, you may only see locally cached data.
The process of exchanging and merging data between peers in the Ditto mesh network. Sync operates automatically when peers are connected via any available transport, using subscriptions to determine which data to exchange and CRDTs to merge concurrent changes. Sync continues to work in offline-first scenarios, queuing changes until connectivity is restored.See also: Replication, Delta Sync, Multi-hop Sync
A deletion marker created when documents are deleted with DELETE DQL statements. Tombstones have a configurable TTL (Time To Live) and eventually expire. If a device reconnects after tombstone TTL expires, its data will be treated as new inserts, causing zombie data.
A mechanism for grouping multiple DQL operations into a single atomic database commit. Transactions provide atomicity (all operations complete or none execute), consistency (all statements see identical data snapshots), and serializable isolation. Only one read-write transaction can execute at a time; long-running transactions block other read-write transactions.
The part of Ditto which involves the physical transport mechanisms such as Bluetooth LE (GATT/L2CAP), WebSockets, AWDL, Wi-Fi Aware, and LAN. Transports are concerned with finding other Ditto peers and establishing secured connections. These lowest-level transports are then weaved together at a higher level to form a Ditto mesh.
The unique identifier assigned to every write transaction indicates its order in the sequence of events, a causal relationship to other events, conflict resolution mechanisms to handle concurrency conflicts, and enables non-blocking reads.
A tracking mechanism for document state across peers. Each change increments the document version, enabling peers to determine if incoming changes are new or already seen. Used by Delta Sync to transmit only changed fields.
A logical connection between two peers that may be composed of multiple Physical Connections across different transports. The Multiplexer combines Physical Connections into a Virtual Connection, providing improved reliability and throughput by utilizing all available network paths simultaneously.
A network transport protocol that enables bidirectional communication between peers over the internet. In Ditto, WebSocket connections are primarily used to communicate with Ditto Server for cloud-based synchronization when local transports (Bluetooth, LAN) are not available.
A peer-to-peer Wi-Fi technology for Android devices that enables direct device-to-device connections without requiring a router or access point. Wi-Fi Aware serves a similar purpose to AWDL on Apple devices and is one of the transports used to form the Ditto mesh network.
Deleted data that reappears from previously disconnected devices after tombstone TTL has expired. When a device with old data reconnects after the tombstone has expired, its data is treated as new inserts rather than being suppressed by the deletion.Prevention strategies:
