> ## Documentation Index > Fetch the complete documentation index at: https://docs.ditto.live/llms.txt > Use this file to discover all available pages before exploring further. # Glossary > Here you'll find Ditto-specific terms and their definitions, as well as links to related information. ## A ### Actor Used by [conflict-free replicated data types](#conflict-free-replicated-data-type-crdt) (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](#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 Store](#blob-store) ### Authentication 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](#identity-service) uses this information to dynamically produce the required certificates. Configured through the [Portal](#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](#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](#transports). Bluetooth LE operates in two modes: [GATT](#gatt-generic-attribute-profile) (slower, wider compatibility) and [L2CAP](#l2cap-logical-link-control-and-adaptation-protocol) (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](#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](#service). ### 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](#document) 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](#register)**: Stores scalar values (strings, numbers, booleans, arrays) using last-write-wins strategy * **[MAP](#map)**: Stores object properties using add-wins strategy for automatic concurrent merge For more information, see Ditto's blog post: [An Inside Look at Ditto's Delta State CRDTs](https://www.ditto.com/blog/dittos-delta-state-crdts). ## D ### Database A named data store identified by a [Database ID](#database-id). All peers configured with the same database ID form a mesh and synchronize the database's [collections](#collection). 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](#portal). ### Database ID The unique identifier for a Ditto [database](#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](#dittoconfig) during initialization. ### DELETE A [DQL](#dql-ditto-query-language) statement that permanently removes documents and creates [tombstones](#tombstone), which propagate the deletion to other peers. Contrast with [eviction](#eviction), which removes data locally without syncing the removal. For documents that may be updated concurrently, prefer [logical deletion](#logical-deletion-soft-delete-pattern) to avoid [husked documents](#husked-document) and [zombie data](#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](#peer) when running multiple Ditto instances. Distinct from [Small Peer](#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](#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](#database-id) and a connect mode: `.server(url:)` to sync with a [Ditto Server](#ditto-server) (copy the URL from the [Portal](#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](#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](#conflict-free-replicated-data-type-crdt) type. ### DQL (Ditto Query Language) 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. ### 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](#register) by default; when disabled, objects are automatically treated as [MAPs](#map) 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). ### Eviction The process a peer takes to deliberately "forget" data locally. Unlike [DELETE](#delete), eviction is a local-only operation that does not propagate to other peers, does not create [tombstones](#tombstone), 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](#l2cap-logical-link-control-and-adaptation-protocol). ## H ### Husked Document A partially deleted document that results from concurrent [DELETE](#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](#logical-deletion-soft-delete-pattern) for documents that may be updated concurrently. ### Hybrid Logical Clock (HLC) Used to track when mutations occurred to a [CRDT](#conflict-free-replicated-data-type-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](#database) and what [permissions](#permission) it carries. In v5, identity is established at login through the auth namespace using a provider: `development` (formerly [Online Playground](#online-playground); development and testing only) or an Authentication Provider backed by an [Authentication Webhook](#authentication-webhook) and configured in the [Portal](#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](#certificate-authority-ca). Not to be confused with the v4 `DittoIdentity` configuration type, which was replaced by [DittoConfig](#dittoconfig) in v5. ### Identity Service The part of [Ditto Server](#ditto-server) which handles login requests, invoking [Authentication Webhooks](#authentication-webhook) if required, and generating the cryptographic material for peers to authenticate each other by acting as the [CA](#certificate-authority-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](#gatt-generic-attribute-profile). 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](#bluetooth-le-ble) and is one of the [transports](#transports) used to form the Ditto [mesh network](#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](#multi-hop-sync) via [Query Overlap Groups](#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](#local-store-observer). For migration guidance, see [Replacing Live Queries](/dql/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 via `ditto.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](#zombie-data) problems and [husked documents](#husked-document) that can occur with physical [DELETE](#delete) operations. ## M ### MAP A [CRDT](#conflict-free-replicated-data-type-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](#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](#peer), ensuring that only authorized peers can communicate within the [mesh network](#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](#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](#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](#peer) 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](#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 the `development` login provider in v5. ## P ### Peer An instance of the Ditto SDK running within an application. Each peer has a unique [identity](#identity) and participates in the [mesh network](#mesh-network) independently. A single [device](#device) can host multiple peers when running multiple Ditto-enabled databases. Peers synchronize data with other peers based on their [subscriptions](#subscription). See also: [Small Peer](#small-peer), [Ditto Server](#ditto-server) ### Peer 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](#actor) IDs. ### Peer-to-Peer Wi-Fi Any mechanism for establishing direct Wi-Fi connections between devices without needing a router in between. [AWDL](#awdl-apple-wireless-direct-link) is one such technology for Apple devices, and [Wi-Fi Aware](#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](#dql-ditto-query-language) 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](#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](#transports) mechanism (such as [Bluetooth LE](#bluetooth-le-ble), [LAN](#lan-local-area-network), or [WebSocket](#websocket)). Multiple Physical Connections can be combined by the [Multiplexer](#multiplexer) into a single [Virtual Connection](#virtual-connection) for improved reliability and throughput. ### Portal Self-service website ([https://portal.ditto.live/](https://portal.ditto.live/)) used to create and manage [Databases](#database) hosted on Ditto's cloud. ### Presence The awareness of other [peers](#peer) in the surrounding [mesh network](#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](#multi-hop-sync). See also: [Presence Viewer](#presence-viewer) ### Presence 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](#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](#peer) whose [subscriptions](#subscription) overlap, enabling them to relay documents to each other through [multi-hop sync](#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 from `ditto.store.execute()` containing a collection of [QueryResultItems](#queryresultitem). Treat QueryResults like database cursors that manage memory carefully. ### QueryResultItem An individual item within a [QueryResult](#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](#local-store-observer) callbacks. ## R ### REGISTER A [CRDT](#conflict-free-replicated-data-type-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](#hybrid-logical-clock-hlc) timestamp) wins. Arrays are REGISTERs, so the entire array is atomically replaced on update—prefer [MAP](#map) structures for data that multiple peers may modify concurrently. ### Replication The process of synchronizing data between [peers](#peer) in the Ditto [mesh network](#mesh-network). Replication is driven by [subscriptions](#subscription) and uses [Delta Sync](#delta-sync) to transmit only changed fields. The Replication [Service](#service) handles document sync over [Channels](#channel). ### 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](#subscription). ## S ### Service Handles [Channels](#channel) 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](#ditto-server). ### Store The local database component of the Ditto SDK, accessed via `ditto.store`. The Store provides methods for executing [DQL](#dql-ditto-query-language) queries, registering [Local Store Observers](#local-store-observer), and managing [attachments](#attachment). All data operations go through the Store, which maintains the local copy of synchronized data. ### Subscription A query from the [replication](#replication) perspective, whereby one [peer](#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. ### Sync The process of exchanging and merging data between [peers](#peer) in the Ditto [mesh network](#mesh-network). Sync operates automatically when peers are connected via any available [transport](#transports), using [subscriptions](#subscription) to determine which data to exchange and [CRDTs](#conflict-free-replicated-data-type-crdt) to merge concurrent changes. Sync continues to work in [offline-first](#offline-first) scenarios, queuing changes until connectivity is restored. See also: [Replication](#replication), [Delta Sync](#delta-sync), [Multi-hop Sync](#multi-hop-sync) ## T ### Tombstone A deletion marker created when documents are deleted with [DELETE](#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](#zombie-data). ### Transaction A mechanism for grouping multiple [DQL](#dql-ditto-query-language) 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. ### Transports The part of Ditto which involves the physical transport mechanisms such as Bluetooth LE ([GATT](#gatt-generic-attribute-profile)/[L2CAP](#l2cap-logical-link-control-and-adaptation-protocol)), WebSockets, [AWDL](#awdl-apple-wireless-direct-link), 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](#mesh-network). ## V ### Version Vector 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](#delta-sync) to transmit only changed fields. ### Virtual Connection A logical connection between two [peers](#peer) that may be composed of multiple [Physical Connections](#physical-connection) across different [transports](#transports). The [Multiplexer](#multiplexer) combines Physical Connections into a Virtual Connection, providing improved reliability and throughput by utilizing all available network paths simultaneously. ## W ### WebSocket A network transport protocol that enables bidirectional communication between [peers](#peer) over the internet. In Ditto, WebSocket connections are primarily used to communicate with [Ditto Server](#ditto-server) for cloud-based [synchronization](#sync) when local [transports](#transports) (Bluetooth, LAN) are not available. ### Wi-Fi Aware 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](#awdl-apple-wireless-direct-link) on Apple devices and is one of the [transports](#transports) used to form the Ditto [mesh network](#mesh-network). ## Z ### Zombie Data Deleted data that reappears from previously disconnected devices after [tombstone](#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. Prevent this by using [logical deletion](#logical-deletion-soft-delete-pattern) or by ensuring the tombstone TTL exceeds the maximum expected offline duration.