@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;
}


Ditto

Home

Query Language (DQL)

Cloud Platform

Best Practices

Support

Get Started

Log in

v4.9

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

An error occurred that prevented the query from executing or completing successfully

Indicates any run-time warnings that might arise during query execution

Request parameters for executing a DQL statement. DQL is Ditto's powerful query language that supports complex queries and data modifications.

api key or jwt token

Response from executing a DQL statement. Contains query results, affected document IDs, and any warnings or errors that occurred.

The Ditto Big Peer acts as a central synchronization point and data store in your Ditto network. It coordinates data replication between peers and provides a consistent view of your data.

Your unique Ditto application endpoint URL, found in the Ditto Portal under Application Settings. Replace REPLACE_WITH_MY_APP_ID with your actual app ID.

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 Data

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.

Overview

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

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.

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

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

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

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

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

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

HTTP API - Attachments

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

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

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

Release Notes

Cloud Compatibility Map

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**.

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.

Sync Handling

In mesh networking, where multiple devices share and sync data, conflict handling is crucial for data consistency.

Conflict Handling

In a mesh network, the efficiency and reliability of data flow depend on key principles of transport, synchronization, and routing.

Data Flow Management

Getting Ditto properly integrated into your app involves configuring the SDK for your specific platform, ensuring it communicates correctly with peers and supports your app's network topology. This section provides guidance for setting up the Ditto SDK and includes platform-specific configuration best practices for iOS, Android, and Web.

2. Setup and SDK Configuration 

Optimizing Bundle Sizes for Android

This section focuses on designing your app’s data model to support Ditto’s peer-to-peer sync across devices. Properly structuring your data is crucial to ensure efficient and reliable sync behavior, especially in decentralized environments. We’ll explore how to model data for local persistence and eventual consistency in a distributed network.

3. Data Modeling and Sync Logic

Use a write transaction when you want to combine multiple database operations into a single atomic transaction.

Batch Write Transactions

In a typical single-server setup, timestamps remain consistent; however, in a Ditto mesh where there are multiple Small Peer devices distributed across the network, each device may operate on its own time. This can lead to discrepancies where a document's timestamp may seem ahead or documents created simultaneously have different timestamps.

In a distributed environment, data structures, schemas, and documents organically undergo changes over time, which can lead to data inconsistencies.

Schema Versioning

If you have a large amount of binary data, or perhaps just a large file, that you want to sync between devices then instead of inserting this into a document as bytes you should make use of the attachments feature.

Large Binary Files

Securing data in a peer-to-peer environment requires careful consideration of how information is accessed, shared, and protected.

 4. Security, Access Control, and Privacy

Maintaining privacy in peer-to-peer (P2P) communication requires robust mechanisms to protect user data and limit exposure.

Maintaining Privacy in Peer-to-Peer Communication

Securing peer-to-peer (P2P) communication requires robust encryption, authentication, and trust mechanisms.

Secure Peer-to-Peer Communication

Implementing Role-Based Access Control (RBAC)

Thorough testing ensures your app performs reliably in real-world conditions, including scenarios with poor connectivity or complex network topologies. This section covers best practices for simulating real- world conditions, testing sync behavior, and ensuring optimal performance during development.

5. Testing and Optimization

Follow this guide to help you test changes you make to your Ditto integration code, data models, and business logic.

Overview

Cloud Portal

HTTP Data API

Data Integration

Reference

Execute a DQL query

Authorizations

Headers

Body

Response