​

Ditto SDK 5.1 — Faster Local Queries. More Capable Query Engine.

• Evictions are 53.6× faster and deletes are 43.0× faster on average. This speeds up routine local data clean-up, like clearing the orders from a point-of-sale terminal.
• A full-collection COUNT(*) fell from 149.03 ms to 0.89 ms, which is 167× faster on average. This speeds up badge counts and dashboard totals across an app.

• JOIN combines local collections in a single SELECT, removing the need to run separate queries and merge their results in application code.
• ADVISE looks at a query and tells you the indexes to create to make it faster, all without running it or reading a document.

• If a device is lost or stolen, it’s easier to revoke the device’s certificate, disconnect it from the mesh, and prevent the device from sending or receiving data.
• Revocations travel peer to peer and reach devices even when they can’t see the cloud. Connections from revoked peers are terminated and refused.

• Identifying problems is easier with better tools for analyzing deployed devices, starting with support bundles that capture the device’s effective configuration.
• Corrupted replication metadata is detected and rebuilt automatically, so field issues can be solved without a site visit.

• Multicast allows Ditto to scale to large networks with many edge devices. Edge devices subscribe to a shared group for data sync, which has lower connection cost at scale.
• Opt-in beta capability in the Swift, Kotlin/KMP, Flutter, and Rust SDKs. Support will expand to additional SDKs in the future.

• Upgrading to Ditto SDK 5.1 changes the on-disk index format.
• If you need to downgrade from Ditto SDK 5.1 or later, migrate through Ditto 5.0.2+. You can also migrate through Ditto 4.14.6+.

​

1. Performance: Faster Queries, Lower Memory Use

​

Android retail benchmark

​

Dramatically faster document counts

​

Lower memory use

​

2. Query Engine: New Ditto Query Capabilities

​

Join collections locally

SELECT task._id, task.title, project.name
FROM tasks AS task
JOIN projects AS project ON task.projectId = project._id
WHERE task.status = 'open'

​

Create composite indexes

CREATE INDEX IF NOT EXISTS status_created_idx
ON tasks (status, createdAt DESC)

SELECT * FROM tasks
WHERE status = 'open'
ORDER BY createdAt DESC

​

Find the right indexes with ADVISE

ADVISE SELECT * FROM tasks WHERE estimateHours > 8

{
  "advice": {
    "statement": "select * from tasks where estimateHours > 8",
    "suggestedIndexes": [
      {
        "collection": "tasks",
        "reason": "range predicates on `estimateHours`",
        "statement": "CREATE INDEX IF NOT EXISTS adv_tasks_estimateHours ON default:`tasks` (`estimateHours` ASC)"
      }
    ]
  }
}

​

Return changed documents with RETURNING

UPDATE tasks
SET status = 'done'
WHERE projectId = 'proj-42' AND status = 'open'
RETURNING _id, status

​

Control long-running requests

​

3. Security: Expanded Certificate Revocation

​

4. Troubleshooting: Identify Problems and Recover Automatically

• A configurable Unix debug_socket lets you remotely run DQL diagnostics against an edge device.
  • You can inspect a live device directly rather than reproducing the problem in a lab.
• Nine new network counters under ditto.network.dsoq.* surface Ditto Sync over QUIC (DSOQ) protocol failures in your existing production metrics, without debug logs.
• SQLite metrics distinguish the application data store from replication metadata databases on supported Unix platforms, showing which one is driving disk activity.

​

5. Transport at Scale: Multicast Beta

​

Upgrading to 5.1

​

Tested rollback compatibility

​

DQL for All Data Operations

​

DQL for All Data Operations

​

What Changed

• Legacy query builder removed: All store.collection() methods and fluent query APIs are no longer available
• Full feature parity: Every legacy operation has a DQL equivalent
• Single query language: DQL handles reads, writes, subscriptions, and observers
• Works everywhere: Same syntax across mobile, server, and web
• SQL-familiar: Standard SQL patterns for immediate productivity

​

Why One Query Language

​

Core Improvements

​

Simplified Initialization & Configuration

​

What’s New

• Unified configuration object: All initialization parameters are set through DittoConfig factory methods
• Fallible initialization: Explicit error handling during setup catches configuration issues early
• Asynchronous patterns: Native async/await support where appropriate for each platform
• Simplified authentication: Clearer authorization client that’s easier to understand and implement

​

What This Solves

​

Accessing Configuration at Runtime

// Example: Access database ID
const config = ditto.config;  // or ditto.getConfig() depending on SDK
const databaseID = config.databaseID;

​

Availability

​

Schema-Free Data Modeling

​

What’s New

• Field-level sync: Ditto syncs individual field changes instead of replacing entire objects
• Automatic type inference: No need to pre-define collection schemas or CRDT types
• Nested structures: Insert complex JSON-like documents without type definitions
• Concurrent updates merge: When peers update different fields simultaneously, both changes are preserved

​

What This Solves

• Add-wins behavior on objects: When peers create or modify objects, additions are preserved rather than overwritten
• Field-level delta sync on all nodes: Every field in your document syncs independently, reducing bandwidth and enabling fine-grained conflict resolution throughout the entire document structure

​

New Customers

​

Migrating Customers

ALTER SYSTEM SET DQL_STRICT_MODE = true

​

Migration Considerations

• Data syncs successfully between peers regardless of different strict mode settings
• Each peer interprets data based on its own strict mode setting when reading/writing
• With DQL_STRICT_MODE=false: Objects are inferred as MAPs (field-level merging)
• With DQL_STRICT_MODE=true: Objects without explicit type definitions are treated as REGISTERs (whole object replacement)

• Collections/documents created, modified, or read while strict mode is disabled will use inferred types (objects → MAPs by default)
• Collections/documents created, modified, or read while strict mode is enabled use default REGISTER type and require explicit definitions for other types

• If mixing settings, explicitly define MAP types in collection definitions on peers with strict mode enabled

​

New DQL Query Features

​

CASE Statements

-- Match a field against multiple values
SELECT CASE a
  WHEN 1 THEN 'one'
  WHEN 2 THEN 'two'
  ELSE 'neither'
END
FROM test

-- Use conditional expressions
SELECT CASE
  WHEN a = 1 THEN 'one'
  WHEN a = 2 THEN 'two'
  ELSE 'neither'
END
FROM test

​

BETWEEN Expressions

<expr> BETWEEN <low-expr> AND <high-expr>

SELECT * FROM test WHERE a BETWEEN 1 AND 10

​

Array & Object Search Syntax

(ANY|EVERY|ANY AND EVERY) [name:] value (IN|WITHIN) expression SATISFIES condition END

• IN - Searches the array/object directly
• WITHIN - Searches recursively through nested structures
• ANY - Returns true if at least one element matches
• EVERY - Returns true if all elements match (empty arrays/objects pass)
• ANY AND EVERY - Like EVERY, but empty arrays/objects fail

-- Check if any element in an array equals 2
SELECT ANY x IN [1,2,3] SATISFIES x = 2 END
FROM system:dual

-- Check if any nested element equals 2
SELECT ANY x WITHIN [1,[2],3] SATISFIES x = 2 END
FROM system:dual

-- Check if all elements equal 1 (or are arrays)
SELECT EVERY x WITHIN [1,[1],1]
SATISFIES x = 1 OR type(x) = 'array' END
FROM system:dual

-- Check if any field value equals 2
SELECT ANY x IN {'a':1,'b':2,'c':3} SATISFIES x = 2 END
FROM system:dual

-- Check if any nested field value equals 2
SELECT ANY x WITHIN {'a':1,'b':{'d':2},'c':3} SATISFIES x = 2 END
FROM system:dual

-- Find documents where first array element is less than zero
SELECT * FROM test
WHERE ANY n:v IN test.array_field SATISFIES n = 0 AND v < 0 END

-- Find documents where any nested field is NULL
SELECT * FROM test
WHERE ANY v WITHIN test.details SATISFIES v IS NULL END

-- Find orders where items were modified after order date
SELECT * FROM orders o
WHERE ANY v IN o.items SATISFIES v.modified > o.order_date END

​

Array & Object Transformation Syntax

ARRAY valueExpr FOR [name:] value IN source [WHEN condition] END

OBJECT nameExpr:valueExpr FOR name:value IN source [WHEN condition] END

-- Transform array elements to objects with index
ARRAY {"index":i,"val":v} FOR i:v IN [1,2,3] WHEN v%2 = 0 END
-- Result: [{"index":1,"val":2}]

-- Convert numbers to strings, excluding value 1
ARRAY cast(v,'string') FOR v IN [1,2,3] WHEN v != 1 END
-- Result: ["2","3"]

-- Transform string characters with conditional logic
ARRAY CASE WHEN i%2 = 0 THEN "foo" ELSE "bar" END
FOR i:v IN split("hello","") END
-- Result: ["foo","bar","foo","bar","foo","bar"]

-- Extract values from object into array
ARRAY v FOR n:v IN {"a":"one","b":"two"} END
-- Result: ["one","two"]

-- Transform object keys to uppercase, filter by value length
OBJECT upper(n):v FOR n:v IN {"a":"one","b":"two","c":"three"}
WHEN len(v) = 3 END
-- Result: {"A":"one","B":"two"}

-- Convert array to object with generated field names
OBJECT "field_"||cast(i,"string"):v FOR i:v IN [1,2,3] END
-- Result: {"field_0":1,"field_1":2,"field_2":3}

-- Filter object by value type
OBJECT n:v FOR n:v IN {"a":1,"b":[],"c":2}
WHEN type(v) != 'array' END
-- Result: {"a":1,"c":2}

• If source evaluates to MISSING, the result is MISSING
• For arrays: if source is not an array/object, the result is NULL
• For objects: duplicate field names will overwrite previous values
• Elements/fields where valueExpr evaluates to MISSING are excluded from the result

​

Extended String Literals

-- Use escape sequences in string literals
SELECT * FROM messages
WHERE content = 'Line 1\nLine 2\tTabbed'

-- [PLACEHOLDER: Add more escape sequence examples if needed]

​

Hexadecimal Numeric Constants

-- Use hexadecimal literals
SELECT * FROM config
WHERE flags = 0xFF

-- [PLACEHOLDER: Add more hex literal examples if needed]

​

Performance & Platform

​

DQL Query Performance Improvements

​

Query Planner Enhancements

• Automatic ID scan conversion: Equality filters on _id fields automatically convert to ID scans, bypassing index lookups when exact document IDs are known
• Deferred document fetching: Query planner can defer fetching full documents until after sorting and applying offset/limit when index access supports it
• Improved covering index support: More scenarios where the query planner can satisfy queries entirely from index data without retrieving documents
• Index-only queries: Additional cases where queries can be answered using only index scans

​

Streaming Query Execution

• Reduced memory overhead: Results are streamed rather than fully materialized where possible
• DISTINCT operator streaming: DISTINCT queries now stream results, reducing memory usage for large result sets
• Improved operator inlining: Query operators can be inlined into producers for better performance

​

Shared Statement Cache

• Plan reuse: Compiled query plans are cached and reused for identical or similar statements, eliminating redundant parsing and planning overhead
• Automatic validation: Cached plans are automatically verified and invalidated when collection schemas or system directives change
• Dynamic sizing: The cache automatically resizes based on workload patterns
• Improved large statement performance: Particularly benefits complex queries and larger statements by avoiding expensive re-compilation

​

Data Sync Performance Improvements

​

What’s New

• Tiered blob storage: Smaller sync updates avoid unnecessary disk I/O by using optimized storage tiers
• Improved session handling: Better avoidance of session resets on reconnection when in-flight updates were lost
• Optimized fsync policy: Document sync avoids forcing files to disk by default, decreasing I/O and improving latency

​

Impact

• Faster sync operations: Reduced disk I/O overhead leads to quicker data synchronization
• Lower latency: Optimized file handling decreases sync latency across the board
• Better reconnection handling: Fewer redundant updates after temporary disconnections
• Improved efficiency: Reduced disk operations lower memory and CPU pressure during sync

​

Local System Observability

​

New Virtual Collections

• Query performance metrics and diagnostics in real-time
• Access counters, timers, and other operational metrics via DQL
• Monitor system health and performance without external tools

• Query peer_key, database_id, and configuration settings
• Inspect runtime configuration and system parameters
• Useful for debugging and operational awareness

• Inspect the query plan cache
• View cached statements and their execution plans
• Supports DELETE operations to clear specific cached statements
• Helps optimize query performance and troubleshoot query planning

​

Usage Example

-- Query system information
SELECT * FROM system:system_info

-- View cached query statements
SELECT * FROM system:shared_statements

-- Access metrics
SELECT * FROM system:metrics
WHERE metric_name = 'sync.documents_synced'

-- Clear a specific cached statement
DELETE FROM system:shared_statements
WHERE statement_id = 'abc123'

​

Additional Improvements

​

Reliability & Error Handling

• Enhanced diagnostics: Improved logging when peers receive data that cannot be deserialized
• Recovery mechanisms: Additional recovery paths for document deserialization errors
• Smart log levels: Connection failures start at warning level, escalate to error only after repeated failures
• Panic messages: Filtered to remove internal Rust machinery frames for improved readability

​

Networking Improvements

• Graceful shutdown: Network connections close cleanly when Ditto is stopped
• Faster disconnection detection: When a peer crashes, Ditto stops attempting to connect within 15 seconds (previously up to 75 minutes)
• mDNS improvements: More reliable mDNS discovery, configurable service names, better address filtering
• BLE improvements: Fixed connection issues on Android 9 and earlier devices
• WebSocket BYOD support: Bring Your Own Discovery now supports WebSocket connections
• Connection cleanup: Fixed deadlock where devices could fail to establish new P2P connections until restarted

​

DQL Engine Improvements

• Better error messages: Improved parser error messages for invalid DQL syntax
• Transaction safety: Fixed deadlock scenarios in concurrent transactions
• Index correctness: Fixed issues where index scans could yield incorrect results on document deletion

​

Logging & Diagnostics

• Better disk utilization: On-disk logs resume writing to incomplete files, making better use of available space
• Compressed size limits: Log file limits now apply to compressed size, significantly increasing retention
• Explicit flushing: Logs explicitly flushed before aborting due to panic
• Virtual collections: New system:metrics and system:system_info collections for DQL access to metrics and system information

​

Platform Support

• Linux aarch64: Kotlin SDK now supports ARM64 Linux (Raspberry Pi, AWS Graviton, etc.)
• Swift 6: Full Swift 6 support with Sendable conformance
• 16KB alignment: React Native Android meets Google Play’s November 2025 requirement

​

Upgrading to v5

​

Terminology Updates

​

Database ID (formerly App ID)

• appID → databaseID in all configuration methods
• getAppId() → getConfig().databaseId in SDK APIs
• Portal and documentation updated to use “Database ID” terminology

​

Ditto Server (formerly Ditto Cloud)

• isConnectedToDittoCloud → isConnectedToDittoServer in presence APIs
• Documentation updated to use “Ditto Server” terminology

​

Breaking Changes

​

Removed APIs

​

Legacy Query Builder (All SDKs)

• store.collection() → Use DQL INSERT, UPDATE, EVICT statements
• collection.find() → Use DQL SELECT queries
• collection.findById() → Use DQL with _id filter
• Live queries → Use DQL observers with store.registerObserver()
• Write transactions → Use store.transaction() with DQL

​

Legacy Initialization (All SDKs)

• Identity classes and all subclasses removed
• Ditto(identity:, persistenceDirectory:) constructors removed
• Use DittoConfig factory methods and Ditto.open() instead

​

Sync Methods Moved

• ditto.startSync() → ditto.sync.start()
• ditto.stopSync() → ditto.sync.stop()
• ditto.isSyncActive → ditto.sync.isActive

​

Other Removals

• disableSyncWithV3() - no longer needed, v3 sync removed entirely
• AttachmentToken - use dictionary variant
• Transport diagnostics APIs - obsolete, removed
• Various deprecated presence properties (queryOverlapGroup, meshRole, etc.)
• Emoji log level headings - setting had no effect, removed

​

Behavioral Changes

• DQL strict mode: Now defaults to false - no schema definitions required, automatic CRDT type inference
• String literals in DQL: Double quotes now delimit strings (not identifiers) for JSON compatibility
• Subscription queries: Reject LIMIT and ORDER BY unless DQL_RESTRICT_SUBSCRIPTION=false
• Observer ordering: Observers require explicit ORDER BY clause for stable ordering
• WebSocket sync: Disabled by default in new TransportConfig instances - must explicitly enable
• Document IDs: null is no longer allowed as a document ID

​

SDK Size Reduction

• Smaller application binary sizes
• Reduced memory usage
• Faster SDK initialization
• Simpler maintenance and debugging

​

Authentication & Initialization

• Offline Initialization: Initialize Ditto instances without requiring network connectivity, enabling immediate local-first operations
• Authentication Support: Authenticate with Ditto Cloud using standard authentication flows
• Standard Initialization: Full initialization with network connectivity and cloud integration

​

Data Operations with DQL

• DQL Execute: Run Ditto Query Language (DQL) queries to perform data operations including SELECT, INSERT, UPDATE, UPSERT, and DELETE
• Live Queries (Observers): Register observers on queries to receive real-time updates when matching documents change
• Subscriptions: Create sync subscriptions to control which data syncs between peers
• Transactions: Execute multiple DQL operations atomically within transactions for data consistency

​

Peer-to-Peer Networking

• Presence: Detect and monitor connected peers in your mesh network with presence observers
• Differ: Track and sync document changes efficiently between peers

​

Developer Tools

• Logging: Configurable logging system to monitor SDK operations and debug sync behavior
• Small Peer Info: Access metadata about connected peers
• Ditto Properties: Inspect SDK configuration and runtime properties
• Serialization: Serialize and deserialize Ditto documents and data types

​

Platform Support