A
Actor
Used by conflict-free replicated data types (CRDTs) to identify the source or author of a data mutation. Actors enable Ditto to track which peer made each change, allowing proper conflict resolution during data merges. An actorâs identity changes whenever its peer begins a new epoch.Attachment
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 StoreAuthentication Webhook
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.AWDL (Apple Wireless Direct Link)
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.B
Backend
The underlying key-value store which Ditto uses for database-like persistence.Big Peer
Previous name for Ditto Server. Indicates that Ditto Server acts as a peer in the meshed network of devices.Blob Store
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.Bluetooth LE (BLE)
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.BYOC
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.C
Certificate Authority (CA)
The cryptographic root of trust for all identities and certificates within a Ditto Database. 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.Change Data Capture (CDC)
A system for tracking data modifications for integration purposes, enabling external systems to receive notifications when data changes in Ditto.Channel
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.Chooser
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.Collection
A grouping of documents under a name. Loosely equivalent to a table in SQL terms. A database may have many collections. Each document within a collection must have a unique_id field (primary key).
Conflict-Free Replicated Data Type (CRDT)
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:- REGISTER: Stores scalar values (strings, numbers, booleans, arrays) using last-write-wins strategy
- MAP: Stores object properties using add-wins strategy for automatic concurrent merge
D
Database
A named data store identified by a Database ID. All peers configured with the same database ID form a mesh and synchronize the databaseâs collections. In v4 this was called an âappâ; v5 renamed it to avoid confusion with mobile applications. Databases hosted on Dittoâs cloud are created and managed in the Portal.Database ID
The unique identifier for a Ditto database, formerly called âApp IDâ in v4. All peers with the same database ID will automatically form a mesh network and synchronize data. Passed to the DittoConfig during initialization.DELETE
A DQL statement that permanently removes documents and creates tombstones, which propagate the deletion to other peers. Contrast with eviction, which removes data locally without syncing the removal. For documents that may be updated concurrently, prefer logical deletion to avoid husked documents and zombie data.Delta Sync
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.Device
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 instances. Distinct from Small Peer, which refers to a Ditto SDK instance rather than the hardware it runs on.Ditto Server
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.DittoConfig
The configuration object used in v5 to initialize a Ditto instance, replacing the v4 identity types. A DittoConfig takes the database ID and a connect mode:.server(url:) to sync with a Ditto Server (copy the URL from the Portal), or .smallPeersOnly(privateKey:) for peer-to-peer-only and air-gapped deployments. Authentication credentials are no longer part of the configuration; they are supplied through the auth namespace at login.
Document
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.
DQL (Ditto Query Language)
A SQL-like query language for interacting with Ditto documents. DQL uses string-based queries executed viaditto.store.execute(). It features SQL-like syntax, schema-less document orientation, and does not support JOIN operations in current versions.
DQL Strict Mode
A configuration option (DQL_STRICT_MODE) that enforces structure and CRDT type safety in collections. When enabled, all fields are treated as REGISTER by default; when disabled, objects are automatically treated as MAPs with field-level merging. Strict mode defaults to true in SDK 4.x and false in SDK 5.0 and later. All peers must use the same setting for consistent behavior.
E
Epoch
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.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.G
GATT (Generic ATTribute Profile)
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.H
Husked Document
A partially deleted document that results from concurrent DELETE and UPDATE operations on the same document. When the operations merge, Dittoâs CRDT combines them field-by-field: fields touched by the update keep their new values while the rest become null, leaving a âhuskâ. Prevent this by using logical deletion for documents that may be updated concurrently.Hybrid Logical Clock (HLC)
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).I
Identity
Who a peer is: how it proves itself to other peers in the same database and what permissions it carries. In v5, identity is established at login through the auth namespace using a provider:development (formerly Online Playground; development and testing only) or an Authentication Provider backed by an Authentication Webhook and configured in the Portal for production permissions (the successor to v4âs onlineWithAuthentication identity type). Air-gapped deployments use a shared private key via .smallPeersOnly(privateKey:) instead. Some modes rely on the database having a common CA. Not to be confused with the v4 DittoIdentity configuration type, which was replaced by DittoConfig in v5.
Identity Service
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.Index
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.INITIAL Documents
A DQL keyword for INSERT statements that creates documents treated as âdefault data from the beginning of timeâ across all peers, such as seed data, form templates, or category lists that every peer should initialize independently. Documents inserted with INITIAL do nothing if the_id already exists locally, preventing unnecessary synchronization traffic.
L
L2CAP (Logical Link Control and Adaptation Protocol)
A faster mode of Bluetooth LE transport at a lower level/complexity than GATT. Platforms that support it have much faster speeds (~20 kB/s).LAN (Local Area Network)
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.Link
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.Live Query
The legacy query builderâs mechanism for observing query results over time (observeLocal), replaced by DQL-based Local Store Observers. For migration guidance, see Replacing Live Queries.
Local Store Observer
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 viaditto.store.registerObserver(), which automatically signals readiness for the next callback once your handler returns. If your handler needs time to process resultsâsuch as expensive rendering or batch operationsâuse the overload with a signalNext callback to control when the next update is delivered.
Logical Deletion (Soft-delete pattern)
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.
M
MAP
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.Mesh Network
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.mTLS (Mutual TLS)
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.Multi-hop Sync
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.Multiplexer
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.O
Offline-First
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.Online Playground
The older term used in v4 for 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. Replaced by thedevelopment login provider in v5.
P
Peer
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 databases. Peers synchronize data with other peers based on their subscriptions. See also: Small Peer, Ditto ServerPeer Key
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.Peer-to-Peer Wi-Fi
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.Permission
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. Permissions can be locked down when using an Authentication Provider for identity (onlineWithAuthentication in v4); other modes have no CA and let everybody access anything.
Physical Connection
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.Portal
Self-service website (https://portal.ditto.live/) used to create and manage Databases hosted on Dittoâs cloud.Presence
The awareness of other peers in the surrounding mesh network, including information about which peers are available and how they are connected. Presence data is used to determine optimal paths for multi-hop sync. See also: Presence ViewerPresence Viewer
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.Q
Query Overlap Groups
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.QueryResult
The result returned fromditto.store.execute() containing a collection of QueryResultItems. Treat QueryResults like database cursors that manage memory carefully.
QueryResultItem
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.R
REGISTER
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. Arrays are REGISTERs, so the entire array is atomically replaced on updateâprefer MAP structures for data that multiple peers may modify concurrently.Replication
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.Replication Query
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.S
Service
Handles Channels to provide a particular functionality. The most important example is the Replication service, which performs document sync.Small Peer
An instance of the Ditto SDK embedded in an application, typically running on a device such as a smartphone, tablet, or IoT device. Small Peers form the edge of the mesh and synchronize directly with each other and with Ditto Server.Store
The local database component of the Ditto SDK, accessed viaditto.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.
Subscription
A query from the replication perspective, whereby one peer requests any data that matches this query from other peers to synchronize. Created viaditto.sync.registerSubscription(). Subscriptions tell Ditto what to sync; without active subscriptions, you may only see locally cached data.