@font-face {
    font-family: '__aeonik_8efdfc';
    src: url('https://ditto.live/_next/static/media/99d6c1192238c32a-s.p.woff2');
    font-display: swap;
    font-weight: 400;
    font-style: normal
}

h1,h2,h3,h4{
  font-family: '__aeonik_8efdfc';
  letter-spacing: normal !important;
}


Accessing & Syncing Data

Guides, setup, and SDK documentation for Ditto

SDK Home

SDK Homepage

Ditto

Get started with Ditto's Edge Sync Platform, a mobile database with built-in edge device connectivity and resiliency

Quickstart

Ditto is the only mobile database with built-in edge device connectivity and resiliency, enabling apps to synchronize without relying on a central server or constant cloud connectivity. Through the use of CRDTs and P2P mesh replication, Ditto allows you to build collaborative, resilient applications where data is always available and up-to-date for every user. This allows you to keep mission-critical systems online when it matters most.

What is Ditto?

Ditto stores data records as documents (specifically JSON-like documents) which are gathered together in collections. An application stores one or more collections of documents.

Apps and Collections

Ditto stores data records as JSON-like documents. Internally these documents are CRDTs, which are a binary representation of JSON documents designed for automatic conflict resolution.

Document Model

Learn how to access data in Ditto, including creating, reading, updating, and removing data.

Accessing Data

Ditto automatically synchronizes data between devices in your mesh. Devices are able to express which data they would like to synchronize using subscription queries.

Syncing Data

Ditto provides a flexible identity system to control which devices can participate in data synchronization, and who they identify as (authentication), and what they can do (authorization). Ditto provides 3 authentication mechanisms: Shared Key, Online Playground, and Online with Authentication.

Authentication and Authorization

The _mesh_ is an underlay for data sync within Ditto, operating independently of your queries and sync subscriptions. Data updates propagate through the mesh automatically to devices with matching subscriptions.

Mesh Networking

Here you'll find Ditto-specific terms and their definitions, as well as links to related information.

Glossary

This article provides expert answers to frequently asked questions (FAQs) for the following Ditto topics:

FAQs

laptop-mobile

Ditto Query Language (DQL) is a powerful, flexible query language designed specifically for use with the Ditto platform. It allows you to perform complex data operations with ease, enabling real-time synchronization and efficient data management.

Overview

Ditto Query Language Overview

The `SELECT` operation, once executed, retrieves documents from a collection and uses clauses like `WHERE` to specify conditions for filtering the documents to return.

SELECT

INSERT

The `UPDATE` operation modifies the content of existing documents in a collection.

UPDATE

The `EVICT` operation removes one or more documents from the local Ditto store, deleting them entirely without flagging (`tombstone`) as deleted to remote peers:

EVICT

Ditto Query Language (DQL) offers a set of *data types* designed to accommodate any edge sync scenario.

Types and Definitions

IDs, Paths, Strings, and Keywords

Operators perform a specific operation on the input values or expressions.

Operator expressions

This document outlines functionality in the DQL language that is in active development. This is not an exhaustive list of the features and functionality the Ditto team is tracking concerning DQL and aims to address larger functionality gaps.

DQL Roadmap Functionality

file-magnifying-glass

The *Big Peer* refers to the trusted cloud deployment of the Ditto sync engine and its associated services that facilitate advanced platform capabilities.

Cloud Platform Overview

browser

A Ditto account provides seamless access to manage your Ditto tenants and utilize Ditto’s cloud capabilities.

Creating a Ditto Account

An App ID in Ditto functions like a tenant in the traditional cloud sense. It serves as a unique identifier for each distinct application environment, isolating data, and configurations within that specific context.

Creating a New App

Getting SDK Connection Details

Ditto's Data Browser and DQL Editor are graphical interfaces you can use to monitor, write, validate, and interact with your queries in a streamlined way.

Data Browser and Editor

Control access to your Ditto apps in the portal with role-based access control (RBAC).

Role-Based Access Control

The Portal Device Dashboard provides insights into devices that have been deployed with an application embedded with the Ditto SDK.  With the Device Dashboard, you can gather and store peer-to-peer sync and network details automatically rather than needing to continuously query Ditto for this data.

Using the Device Dashboard

globe

Ditto offers an HTTP API to programmatically interact with transactional data generated in the mesh network and stored within the *Big Peer*.

Getting Started

The HTTP API is protected by an API key, passed in as an Authorization header. A number of other parameters are also permitted for each request.

Auth and Parameters

Execute a Ditto Query Language (DQL) statement against your data store. DQL is a powerful query language that supports complex queries, updates, and data manipulation. This endpoint serves as the primary interface for running DQL operations. See the comprehensive DQL guide at https://docs.ditto.live/dql-guide for detailed syntax and examples.

Execute a DQL query

With the `ATTACHMENT` data type, you can link extensive binary data, such as avatar images, videos, and PDFs, to a document.

HTTP API - Attachments

Enable realtime event streaming from Ditto to your own third-party data products by upgrading and implementing Apache Kafka change data capture (CDC) in your system architecture.

Change Data Capture

The Ditto MongoDB Connector, built in partnership with MongoDB, provides seamless bidirectional synchronization between Ditto apps and MongoDB databases. It allows you to extend your data in MongoDB's developer platform to the edge via Ditto's powerful edge synchronization capabilities, effectively bridging the gap between edge and cloud data management.

MongoDB Connector

Release Notes

Cloud Compatibility Map

cloud

Whether you're building a new app or integrating Ditto's **offline-first**, **peer-to-peer sync** capabilities into an existing solution, this guide provides everything you need to design, develop, and optimize applications with **real-time collaboration** and **seamless offline support**.

Best Practices

Inventory

Meal Ordering

Chat

Point-of-Sale

Install BlueZ package version 5.66 or higher. The BlueZ package is the official Linux stack and provides all the modules you’ll need to enable data sync with Bluetooth Low Energy (LE).

Bluetooth on Linux

This installation guide provides step-by-step instructions on installing and setting up the Ditto SDK in your C++ project.

C++ Quickstart (Temp)

C# Tutorials temp

Swift Tutorials temp

This article provides an overview of how-to tutorials you can use to expand your Ditto skills.

Tutorials Overview

list-check

Ditto's Edge Sync Platform is a real-time database platform for mobile, web, IoT, and server apps that can magically sync even when offline.

Welcome to Ditto Docs

Ditto is an _edge-sync_ platform, orchestrating data flow between points A and B across diverse environments, including peer‑to‑peer, client‑server, and hybrid setups. 

About Ditto

Install the Ditto SDK in just a few steps using any of the following guides.

Directory of Install Guides

You can integrate the Ditto SDK into Swift projects to develop native apps for Apple iOS and macOS platforms. 

Swift

You can integrate the Ditto SDK into Kotlin projects to develop native apps for the Android platform.

Kotlin

You can integrate the Ditto SDK with your web and Node.js projects developed using JavaScript and [TypeScript](https://www.typescriptlang.org/ "TypeScript") languages.

JavaScript Web

To get started right away without having to build an app from scratch, explore with the Ditto ready-to-use demo task app.

Node.js

This article provides instructions on adding the Ditto package to your project by importing, initializing, and preparing Ditto to be integrated successfully with your React Native apps.

React Native

You can integrate the Ditto SDK into Kotlin projects to develop for the Android platform.

Java

You can integrate the Ditto SDK into C# projects to develop for platforms, including mobile apps for iOS and Android, desktop apps, Linux-enabled server systems, and more.

You can integrate the Ditto SDK into C++ projects to develop for Linux and Android platforms.

This article provides step-by-step instructions on how to set up a new Rust project, integrate the Ditto SDK, cross-compile for any target platform, and more:

Rust

A document consists of sets of fields that self-describe the data it encodes.

Fields

Ditto syncs and queries documents through a combination of collection names and document identifiers (`_id`). A collection is a grouping of documents, like *tables* in a relational database system but far simpler and more flexible.

Collections

Every document has an identifier field `_id`. The identifier field serves as the primary key for the document and can be either auto-generated or custom-assigned.

Identifiers

Relationships in Ditto are used to link related data items and organize them for easy lookup.

Relationships

The `REGISTER` type is the core building block of every app built on Ditto.

Register

An alternative approach to using a JSON object as a `REGISTER` to represent and organize data in a hierarchical structure within a document is to use a `MAP`.

This article provides conceptual information for the `ATTACHMENT` data type. For instructions on how to work with an `ATTACHMENT`, see *CRUD Operations* > [CREATE](../crud/create), [READ](../crud/read), [UPDATE](../crud/update), and [DELETE](../crud/delete).

Attachment

This article provides how-to instructions for creating and organizing documents, linking them to associated files, called *attachments*, and creating MAP structures for additional document hierarchies.
Attachments in Ditto are represented using the ATTACHMENT data type, which you can use to store binary data, such as images, alongside queryable descriptive information, such as file name and description.

Create

This article provides an overview of essential methods for reading documents within Ditto.

Read

This article provides an overview and how-to instructions for updating documents within Ditto.

Update

This article provides an overview and how-to instructions for deleting documents within Ditto.

Delete

This article provides an overview and how-to instructions for observing data changes within Ditto.

Observing Data Changes

Required only once, initiating the sync process automatically connects you with the mesh network. Once connected, you immediately begin receiving updates from set sync subscriptions and sending updates to subscribing remote peers.

Starting and Stopping Sync

Syncing with MongoDB

Using Mesh Presence

This article provides an introduction to Ditto's methods for authentication, as well as step‑by‑step instructions on how to use the online playground authentication mode to initialize Ditto and start prototyping.

Cloud Authentication

Ditto offers an intermediate level of security for applications where all users and devices are trusted. For example, this could be appropriate for an enterprise application run on centrally managed devices.

Shared Key Authentication

Many apps require access controls to manage end-user authorization for reading and writing specific data.

Data Authorization

All communications are consistently protected by modern and robust encryption for all of Ditto's communication methods.

Certificate-Based Security

Directory of API References

JavaScript | Web and Node.js | React Native

Flutter

Directory of Release Notes

Directory of Compatibility Maps

Install the Ditto SDK in just a few steps using any of the following guides to support you along the way:

You can integrate the Ditto SDK into Kotlinprojects to develop native apps for the Android platform.

You can integrate the Ditto SDK into C++ projects to develop for Linux and iOS platforms..

This article provides an overview of the different relationships you can form in Ditto, as well as a brief description, list of possible approaches you can take, and links to related content.

This article provides conceptual information for the `ATTACHMENT` data type. For instructions on how to work with an `ATTACHMENT`, see *CRUD Operations* > [CREATE](/sdk/v4-8/crud/create), [READ](/sdk/v4-8/crud/read), [UPDATE](/sdk/v4-8/crud/update), and [DELETE](/sdk/v4-8/crud/delete).

This article provides an overview of essential methods for reading data from Ditto.

This article provides an overview and how-to instructions for deleting documents using the `EVICT` DQL operation.

Sync Credentials

This article provides instructions on how to add the Ditto package to your project, import and initialize Ditto, and prepare React Native apps targeting iOS and Android for usage with the Ditto SDK:

You can integrate the Ditto SDK into C++ projects to develop for Linux and iOS platforms.

Mesh Networking 101

This article provides a complete overview of the various data types you can use with your queries to retrieve, modify, and sync data in Ditto. In addition, you'll find an introduction to related concepts like conflict resolution strategies.

Data-Handling Essentials

Once you've set up your environment, try on Ditto and perform your first peer‑to‑peer sync.

'Hello, World!' Sync

This article provides an overview of essential methods for data retrieval.

DELETE

This article provides instructions on how to create, retrieve, and cancel subscriptions:

Managing Sync Subscriptions

Authentication

End-User Access

At a high-level, queries operate on collections rather than individual documents. Filter, search, and retrieve specific information based on various criteria using Boolean operators, equal and unequal operators, comparison operators, and match operators.

Query Syntax (Legacy)

Ditto is a NoSQL database that organizes JSON-like documents into collections. Unlike JSON, with Ditto you can apply updates directly to the document, ensuring sync across all connected peers.

Documents and IDs (Legacy)

This article covers example mappings from Legacy Query APIs to DQL for basic CRUD operations as well as syncing data with the SDK.

Legacy-to-DQL Reference

Recently released, the Ditto SDK version 4.5 introduces the Ditto Query Language (DQL) — a simple SQL-like query language designed specifically for the features and capabilities of the Ditto platform.

Legacy-to-DQL Adoption Guide

Query documents in a collection using a flexible query language. This endpoint supports pagination, sorting, and complex queries to help you efficiently retrieve exactly the data you need.

Find docs with Legacy QL

Retrieve a single document by its unique identifier. This is the most efficient way to fetch a specific document when you know its ID.

Lookup docs by ID with Legacy QL

Perform one or more write operations (updates, upserts, or removals) in a single atomic transaction. This endpoint ensures all operations either succeed or fail together, maintaining data consistency.

Write docs with Legacy QL

Count the number of documents in a collection that match a specified query. This endpoint is useful for pagination, analytics, and understanding the size of your dataset.

Count docs with Legacy QL

Backend Architecture

Cloud-Optional Design

This article provides a detailed overview of the various timestamps the Big Peer uses to enforce causal consistency and high availability.

Timestamps

The Big Peer’s replication engine enforces causal consistency. 

Causally Consistent Transactions

There are many failure scenarios in any distributed system. Big Peer leans heavily on a durable transaction log for many failure scenarios, and replicated copies of data for many others.

Failure Handling

Incorporating Ditto's offline-first and peer-to-peer sync capabilities requires thoughtful planning to ensure seamless integration into your app's overall architecture.

1. Planning and Architecture Design

When implementing sync in a peer-to-peer mesh network, handling synchronization efficiently is crucial.

Overview & Setup

Accessing Data

Syncing Data

Authentication and Authorization

Managing the Mesh

Advanced

Reference

SDK Homepage

Quickstart Apps

Install Guides

Accessing & Syncing Data

Creating Documents

Reading Documents

Updating Documents

Deleting Documents

Observing Document Changes

Syncing Documents

Overview & Setup

Accessing Data

Syncing Data

Authentication and Authorization

Managing the Mesh

Advanced

Reference

Quickstart Apps

Install Guides

​Accessing & Syncing Data

Creating Documents

Reading Documents

Updating Documents

Deleting Documents

Observing Document Changes

Syncing Documents

Accessing & Syncing Data