@font-face {
    font-family: 'Kairos Sans';
    src: url('https://cdn.prod.website-files.com/6761335affb7c1ca9aae00dd/676134b94c85d94594f80209_KairosSans_Variable.ttf');
    font-display: swap;
    font-weight: 500;
    font-style: normal
}

@font-face {
    font-family: 'Aeonik Fono';
    src: url('https://cdn.prod.website-files.com/6761335affb7c1ca9aae00dd/6761352bf250ec43e156773b_AeonikFono-Medium.woff2');
    font-display: swap;
    font-weight: 400;
    font-style: normal
}

#header a, .eyebrow {
    font-family: 'Aeonik Fono';
    text-transform: uppercase;
}

#header p {
  font-weight: 500;
}


#navbar a, button {
    font-family: 'Aeonik Fono';
    text-transform: uppercase;
}

h1 {
  font-family: 'Kairos Sans';
  letter-spacing: normal !important;
  font-variation-settings: "wdth" 112;
}

#table-of-contents {
    font-family: 'Aeonik Fono';
    text-transform: uppercase;
}

/* headers inside boxes */
a.card.block h2 {
  font-family: 'Aeonik Fono';
  font-weight: 400;
  text-transform: uppercase;
}


// Example taken from https://docs.inkeep.com/integrations/mintlify

// Custom workflow to get a user started with an app
const integrateWithMyAppWorkflow = {
  id: "ikp_integrate_with_my_app",
  displayName: "Help me integrate Ditto in my application",
  goals: [
    "Identify the platform(s) that the user is looking to add Ditto to. This can be iOS, Android, Desktop, Server, or Web, or any combination of these.",
    "Identify the language that the user wants to build their application in, this can be one of any of Ditto's supported SDK languages.",
    "Explain key concepts within Ditto, including: subscriptions and syncing, accessing data in the local database, and reacting to live changes in data within the application.",
    "Provide code snippets and explanations on how to add the SDK to their application in their language of choice, after explaining the key concept.",
    "Provide code snippets and explanations on how to initiate sync and create subscription queries with Ditto in their language of choice, after explaining the key concept.",
    "Provide code snippets and explanations on how to perform local data access within the application using DQL in their language of choice, including using store observers to react to data change, after explaining the key concept.",
  ],
  botPersona: "You are an expert solutions engineer with a lot of knowledge about building mobile applications and using the Ditto SDK",
  informationToCollect: [
    {
      description: "Platform(s) and language they are using to build their mobile application",
      required: true,
    }
  ],
  guidance: [
    "If not clear from the user's message, ask clarifying questions to understand the underlying platform (e.g. iOS vs Android vs Server vs Web vs Desktop, or a combination of any of these).",
    "If not clear from the user's message, ask clarifying questions to understand the language being used to build the application (e.g. Swift vs Kotlin vs Flutter vs Rust), you should expect only a single language even if multiple platforms are being used.",
    "Prefer content from the quickstart github repository (https://github.com/getditto/quickstart) if it exists for the platform(s) and language(s) they are using. If it doesn't exist, then the requested platform are likely not supported yet.",
    "Ignore all content under the the `/best-practices` URL, these are outdated and will only cause confusion."
  ],
  initialReplyMessage:
    "I'd be happy to help you integrate Ditto in your application. What platform(s) (e.g. iOS, Android, Desktop, Web, Server) are you using, and which language (e.g. Swift, Kotlin, Flutter) are you using?",
};

const inkeepSettings = {
  baseSettings: {
    apiKey: "0a7225010a13d0efffb09f01d707689d32bea957ec3636a2",
    integrationId: "cm7c62vri0000s6018cp7usuv",
    organizationId: "org_0VGKnvN4zy8MgDqS",
    primaryBrandColor: "#eaf044",
    theme: {
      tokens: {
        fonts: {
          heading: "'Inter'",
          body: "'Inter'",
        }
      }
    }
  },
  aiChatSettings: {
    chatSubjectName: "Ditto",
    botAvatarSrcUrl: "https://storage.googleapis.com/organization-image-assets/dittolive-botAvatarSrcUrl-1740477640436.svg",
    botAvatarDarkSrcUrl: "https://storage.googleapis.com/organization-image-assets/dittolive-botAvatarDarkSrcUrl-1740477639767.svg",
    getHelpCallToActions: [
      {
        name: "Contact Us",
        url: "https://support.ditto.live/hc/en-us",
        icon: {
          builtIn: "IoChatbubblesOutline"
        }
      }
    ],
    quickQuestions: [
      "Which languages does Ditto support?",
      "What are the differences between a Big Peer and a Small Peer?",
      "What are good use cases for Ditto?"
    ],
    workflows: [integrateWithMyAppWorkflow]
  }
};

// The Mintlify search triggers, which we'll reuse to trigger the Inkeep modal
const searchButtonContainerIds = [
  "search-bar-entry",
  "search-bar-entry-mobile",
];

// Clone and replace, needed to remove existing event listeners
const clonedSearchButtonContainers = searchButtonContainerIds.map((id) => {
  const originalElement = document.getElementById(id);
  const clonedElement = originalElement.cloneNode(true);
  originalElement.parentNode.replaceChild(clonedElement, originalElement);

  return clonedElement;
});

// Load the Inkeep component library
const inkeepScript = document.createElement("script");
inkeepScript.type = "module";
inkeepScript.src =
  "https://unpkg.com/@inkeep/uikit-js@0.3.20/dist/embed.js";
document.body.appendChild(inkeepScript);

// Once the Inkeep library is loaded, instantiate the UI components
inkeepScript.addEventListener("load", function () {
  // Customization settings

  // for syncing with dark mode
  const colorModeSettings = {
    observedElement: document.documentElement,
    isDarkModeCallback: (el) => {
      return el.classList.contains("dark");
    },
    colorModeAttribute: "class",
  };

  // Instantiate the 'Ask AI' pill chat button. Optional.
  Inkeep().embed({
    componentType: "ChatButton",
    colorModeSync: colorModeSettings,
    properties: inkeepSettings,
  });

  // Instantiate the search bar modal
  const inkeepSearchModal = Inkeep({
    ...inkeepSettings.baseSettings,
  }).embed({
    componentType: "CustomTrigger",
    colorModeSync: colorModeSettings,
    properties: {
      ...inkeepSettings,
      isOpen: false,
      onClose: () => {
        inkeepSearchModal.render({
          isOpen: false,
        });
      },
    },
  });

  // When the Mintlify search bar elements are clicked, open the Inkeep search modal
  clonedSearchButtonContainers.forEach((trigger) => {
    trigger.addEventListener("click", function () {
      inkeepSearchModal.render({
        isOpen: true,
      });
    });
  });

  // Open the Inkeep Modal with cmd+k
  window.addEventListener(
    "keydown",
    (event) => {
      if (
        (event.metaKey || event.ctrlKey) &&
        (event.key === "k" || event.key === "K")
      ) {
        event.stopPropagation();
        inkeepSearchModal.render({ isOpen: true });
        return false;
      }
    },
    true
  );
});

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

The DQL statement to execute, along with any parameterized arguments. Using parameterized queries with the args field helps prevent injection attacks and improves query performance through statement caching.

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

The DQL statement executed successfully. The response includes the results of the query, any mutated document IDs, the transaction ID, and any warnings that occurred during execution. For SELECT queries, results appear in the items array. For mutations, affected IDs appear in mutatedDocumentIds.

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

The DQL statement was invalid or malformed. This could be due to syntax errors, invalid collection names, type mismatches, or other query validation failures. Check the error response for detailed information about what went wrong.

Authentication failed. Ensure you're providing a valid API key or JWT token in the Authorization header and that it has sufficient permissions for the requested operation.

The requested transaction ID (if specified) is not available on the Big Peer. This typically means the Big Peer has not yet reached that transaction ID or the transaction has been garbage collected.

The query execution timed out. This can happen with complex queries over large datasets or when the system is under heavy load. Consider optimizing your query or adding appropriate indexes.

An unexpected server error occurred while executing the query. This could be due to resource constraints, internal errors, or temporary service disruptions. The operation may succeed if retried.

The service is temporarily unavailable, typically due to maintenance or capacity issues. Clients should implement exponential backoff and retry the request later.

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

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

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

Task List

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

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. 

Overview

Cloud Portal

HTTP Data API

Data Integration

Reference

Execute a DQL query

Authorizations

Headers

Body

Response