​

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

​

Kotlin-Specific Changes

​

Data Streams Public Preview

​

Observability and lifecycle improvements

• Kotlin and Kotlin Multiplatform applications can opt into OpenTelemetry spans for DQL, transaction, and attachment operations.
• Slow Flow collectors now receive a single coalesced, up-to-date result instead of a backlog of stale observer results.
• DQL argument maps accept additional Kotlin scalar, collection, attachment, and serializable values.
• Memory and lifecycle fixes cover observers, diffs, attachments, query results, subscriptions, presence, and authentication handlers.

​

Kotlin Specific Changelog

• Data Streams Public Preview: low-latency, bidirectional byte streams between reachable Android peers. See Data Streams for requirements and usage guidance.
• transports_wifi_aware_instant_communication_enabled system parameter (default: true). Set it to false to disable Wi-Fi Aware Instant Communication Mode on single-radio devices that experience Wi-Fi instability from multi-channel switching. (#21321)
• transports_ble_warm_gatt_cache_enabled system parameter (Android, default: false). When enabled before sync starts, a cleanly disconnected peripheral’s GATT connection is kept warm so reconnecting to a known peer skips BLE service discovery. (#NETW-1976)
• Opt-in OpenTelemetry tracing for DQL queries, transactions, and attachment operations, configured through the new DittoInstrumentation.configure() API. (#SDKS-3219)
• Enum, Char, UByte, Short, Byte, and UInt values can now be individually converted to DittoCborSerializable or DittoJsonSerializable. (#SDKS-3823)
• DittoTransportConfig.PeerToPeer.MulticastBeta and DittoTransportConfig.PeerToPeer.multicastBeta for configuring the beta reliable UDP multicast transport. The transport is disabled by default, with availability limited to supported platforms during the beta. On Android and iOS, changes requested while sync is active take effect after sync is stopped and successfully started again, when Ditto validates platform prerequisites. (#SDKS-4471)
• DittoConnectionType.Multicast enum option representing beta reliable UDP multicast connections. Transport availability is limited to supported platforms during the beta. (#SDKS-4471)

• DittoStore.observe() and DittoStore.observeWithDiff() now coalesce writes that arrive while a slow collector is busy, delivering a single up-to-date emission rather than a backlog of stale results. (#SDKS-3836)

• The DittoPresence.connectionRequestHandler setter no longer leaks the previous handler and its captured user closure on every reassignment. (#22500)
• Memory leak in DittoStore.fetchAttachment and DittoStore.newAttachment on repeated calls for the same attachment. (#SDKS-1898)
• Memory leak in DittoStoreObserver when the supplied onClose callback throws. (#SDKS-1898)
• Memory leaks in DittoStore.observe, DittoStore.collect, DittoStore.registerObserver, and DittoStore.fetchAttachment when a callback races with a closing Ditto instance. (#SDKS-1898)
• Memory leak on each access to DittoConfig.default, DittoTransaction.info, DittoSync.subscriptions, DittoSyncSubscription.queryArgumentsCborData, and DittoSyncSubscription.queryArgumentsJsonString. (#SDKS-1898)
• Memory leak in the DittoDiff-receiving overloads of DittoStore.observe, DittoStore.collect, and DittoStore.registerObserver. (#SDKS-4018)
• DittoAuthenticator now releases its expirationHandler binding promptly when the parent Ditto instance is closed. (#SPO-651)

• Wi-Fi Aware TCP sync on Android no longer breaks when the shared TCP listener is bound to IPv4 or disabled. (#22612)
• Android BLE central connections with 2M PHY enabled no longer start GATT service discovery while PHY negotiation is still in flight, which could silently leave the connection unusable on devices that are slow to negotiate PHY. (#NETW-1452)
• Wi-Fi Aware peer-to-peer connections between Android 13+ devices no longer fail when each side independently selects a different security configuration even though a mutually supported one is available. (#NETW-900)
• NullPointerException in StableBluetoothPlatform.onCharacteristicRead and onCharacteristicChanged on Android 12 and below when BluetoothGattCharacteristic.getValue() returns null. (#SPO-862)

• The DQL query arguments parameter is Map<String, Any?>? (nullable) again across the Kotlin SDK, matching v4. Pass null to indicate no arguments. (#SDKS-3820)
• Enum, Char, Short, Byte, UByte, UInt, Array<*>, and Set<*> values can now be used as DQL query arguments. Previously these types caused an IllegalArgumentException at runtime. (#SDKS-3823)
• APIs using Map<String, Any?>? arguments now correctly accept DittoAttachment and DittoCborSerializable values inside the map, matching the documented attachment-insert pattern. (#SDKS-4195)

• DittoStoreObserver race condition where the observer would never close when the event handler threw an exception, caused by the observer reference not being set before the FFI callback fired. (#21923)
• Android apps with isMinifyEnabled = true no longer crash on Ditto initialization. The published Kotlin AARs now bundle the required consumer-rules.pro keep rules. (#SDKS-2626)
• Ditto.sync().stop() no longer crashes the app with ForegroundServiceDidNotStartInTimeException on Android 14+ when the foreground service is enabled. (#SPO-941)

• DittoPeerOs.Tvos. The entry is retained so peers running older SDK versions on tvOS can still be identified in the presence graph. (#SDKS-3944)

​

5.0.3 Kotlin Specific Changes

​

5.0.2 Kotlin Specific Changes

​

5.0.1 Kotlin Specific Changes

​

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

​

Migration Guidance

​

Kotlin Migration Guide

• Updating from DittoIdentity to DittoConfig-based initialization
• Replacing legacy query builder operations with DQL statements
• Migrating collection observers to DQL observers
• Updating authentication patterns

​

Kotlin-Specific Changes

​

Major Architectural Changes

• store.registerObserver(query, args) { result -> ... } — the change-handler lambda is now suspend. The function still returns a DittoStoreObserver you can close manually.
• store.observe(query, args) { result -> transform } — NEW. Returns a Flow<T> that requires a transform lambda. Collecting it in a CoroutineScope (e.g. lifecycleScope) auto-cancels the observer when the scope ends.
• store.collect(query, args) { result -> ... } — NEW. A suspending function that delivers events to your handler and signals Ditto for the next event only after the handler returns, providing back-pressure via coroutine suspension.
• Presence observers: presence.observe(handler) → presence.observe(): Flow<DittoPresenceGraph> — collect in a scope.
• Disk-usage observers: diskUsage.observe(handler): Closeable → diskUsage.observe(): Flow<DittoDiskUsageItem> — collect in a scope.
• Transport-condition observers: ditto.callback = DittoCallback { ... } → ditto.transportCondition: Flow<DittoTransportConditionEvent>.

• DittoAndroidConfig → DittoConfig (no longer requires context parameter)
• DittoConfig.Connect.Server now takes String instead of URI
• Import package changed from live.ditto.* to com.ditto.kotlin.*

• DQL query arguments can be passed as a plain Map<String, Any?>, a DittoCborSerializable.Dictionary, or any @Serializable data class.
• DittoQueryResultItem.value is now DittoCborSerializable.Dictionary (was Map<String, Any>). Read field values with typed accessors — for example item.value["color"].string, .stringOrNull, .intOrNull, .longOrNull, .doubleOrNull, .booleanOrNull, .listOrNull, .dictionaryOrNull, .attachmentTokenOrNull, .isNull — or call item.jsonString() and decode with kotlinx.serialization.
• The cast item.value["color"] as String no longer works because value[key] returns a DittoCborSerializable, not Any.

• Internal types under com.ditto.internal.* are no longer part of the public Kotlin API surface — only com.ditto.kotlin.* is supported for application code.
• DittoExperimental-annotated APIs are no longer publicly exposed.
• DittoPanicException is a new exception type raised when the native core panics (requires DittoConfig.Experimental(coreExceptionBridgingEnabled = true) to surface as a JVM exception).

​

Platform Support

• Added Linux aarch64 platform support
• Enables deployment on ARM64-based Linux devices such as Raspberry Pi and AWS Graviton instances

​

Android: Next Generation Networking

• Added Next Generation Networking UDP transport on WiFi Aware
• Transport only attempts to start on devices that support it
• Respects system data path limits to prevent resource exhaustion
• Never crashes even when required permissions are missing
• Added configuration option to reset device WiFi stack in Android profile owner scenarios for improved reliability

​

API Changes

• DittoSyncSubscription.queryArguments no longer guaranteed to be strictly equal to original arguments due to serialization roundtrip
• Added queryArgumentsCborData and queryArgumentsJsonString properties for custom deserialization
• Added DittoSync.registerSubscription() overload accepting serializable arguments with accompanying serializer

• Flow-based DittoStoreObserver.observe() refactored to require transform function that doesn’t return DittoQueryResult
• Suspend-based DittoStoreObserver.observe() renamed to collect()
• Restored DittoStoreObserver.registerObserver() function in Kotlin
• DittoQueryResult automatically closed by DittoStoreObserver to prevent leaking

• Renamed DittoConnection.getPeer{1,2}Key() to getPeer{1,2}()
• Renamed DittoConnectionRequest.getPeerKeyString() to getPeerKey()
• DittoPeer.os now returns DittoPeerOs? enum instead of String? for type-safe OS representation
• Renamed isConnectedToDittoCloud to isConnectedToDittoServer

• Changed Ditto.startSync() moved to DittoSync.start() - Use ditto.sync.start() instead
• Changed Ditto.stopSync() moved to DittoSync.stop() - Use ditto.sync.stop() instead
• Changed Ditto.isSyncActive moved to DittoSync.isActive - Use ditto.sync.isActive instead

• Removed DittoAuthenticationCallback interface and DittoAuthenticator.setCallback() method
• Use DittoAuthenticator.expirationHandler property with lambda instead
• Fixed clientInfo not being returned on auth failure (#SDKS-1656)

• Added Ditto.smallPeerInfo property for configuring metadata shared with other peers during synchronization

• Removed DittoLogger.isEmojiLogLevelHeadingsEnabled - Setting had no effect since 4.8.0

• Removed ditto.sdkVersion - Use static Ditto.VERSION instead

​

Memory Management

• Fixed memory leak in DittoQueryResult.close() which now also closes DittoQueryResultItem instances
• Eliminates need for manual cleanup and resolves excessive memory usage with large query results
• Removed Ditto.runGarbageCollection() - Memory now fully managed using AutoCloseable types

​

Migration Example

val config = DittoConfig(
    databaseId = "your-database-id",  // was: appId
    connect = DittoConfig.Connect.Server(url = "https://your-database-id.cloud.ditto.live"),
)
val ditto = DittoFactory.create(config)

// Set up authentication. `auth` is null when using Connect.SmallPeersOnly.
ditto.auth?.let { auth ->
    auth.expirationHandler = { ditto, timeUntilExpiration ->
        // The lambda is suspend — call login() directly.
        ditto.auth?.login(
            token = "YOUR_PLAYGROUND_TOKEN",
            provider = DittoAuthenticationProvider.development(),
        )
    }
}

ditto.sync.start()  // was: ditto.startSync()

val identity = DittoIdentity.OnlinePlayground(
    appId = "your-app-id",
    token = "your-token"
)
val ditto = Ditto(DefaultAndroidDittoDependencies(context), identity)

ditto.startSync()

​

Accessing Configuration at Runtime

val persistenceDir: String = ditto.absolutePersistenceDirectory

​

Migration Path

ditto.store.execute(
    "UPDATE cars SET miles = 50000 WHERE _id = 'abc123'"
)

ditto.store.collection("cars")
    .findByID("abc123")
    .update { doc ->
        doc["miles"].set(50000)
    }

ditto.store.registerObserver(
    "SELECT * FROM cars WHERE miles > 100000"
) { result ->
    // handle changes
}

ditto.store.collection("cars")
    .find("miles > 100000")
    .observe { docs, event ->
        // handle changes
    }

​

How It Works

// Objects are automatically inferred as MAPs - no definition needed
ditto.store.execute("""
    INSERT INTO products
    DOCUMENTS ({
        _id: '123',
        name: 'Widget',
        metadata: {
            manufacturer: 'Acme Corp',
            warehouse: 'East'
        }
    })
""")

// Query without type definitions
ditto.store.execute("SELECT * FROM products WHERE _id = '123'")

// Must explicitly define MAP types to use objects
ditto.store.execute("""
    INSERT INTO COLLECTION products (metadata MAP)
    DOCUMENTS ({
        _id: '123',
        name: 'Widget',
        metadata: {
            manufacturer: 'Acme Corp',
            warehouse: 'East'
        }
    })
""")

// Query with explicit MAP definition
ditto.store.execute("""
    SELECT * FROM COLLECTION products (metadata MAP)
    WHERE _id = '123'
""")

​

Migration

// Database ID (was App ID in v4)
val config = DittoConfig(
    databaseId = "your-id",  // was: appId
    connect = DittoConfig.Connect.Server(url = "https://your-id.cloud.ditto.live"),
)
val ditto = DittoFactory.create(config)

// Presence API — peer connection check
if (peer.isConnectedToDittoServer) {
    // handle connection
}

// App ID
val identity = DittoIdentity.OnlinePlayground(
    appId = "your-id",
    token = "your-token"
)
val ditto = Ditto(DefaultAndroidDittoDependencies(context), identity)

// Presence API — peer connection check
if (peer.isConnectedToDittoCloud) {
    // handle connection
}

​

Kotlin Specific Changes

• WiFi Aware transport will only attempt to be started on devices that support it (#18484)
• WiFi Aware should never crash even when required permissions are missing (#18705)
• DittoQueryResult is automatically closed by DittoStoreObserver to prevent it from leaking (#19214)
• BLE platform GATT disconnect watchdog restart loop on Android when remote peers disconnect or connectGatt fails (#21687)
• WifiAwarePlatform no longer blocks the first reset attempt after initialization (#NETW-1399)
• Memory leak in DittoQueryResult.close(), which now also closes its DittoQueryResultItem instances. This eliminates the need for manual cleanup and resolves excessive memory usage with large query results (#SDKS-1463)
• clientInfo not returned on auth failure (#SDKS-1656)
• WifiAwarePlatform no longer calls getNumberOfSupportedDataPaths() on Android versions below API 33, preventing NoSuchMethodError on Android 12 devices (#SDKS-2753)
• DittoDiskUsageItem.sizeInBytes now uses Long instead of Int to support sizes greater than 2.1GB (#SDKS-2854)
• Potential crashes on 32-bit ARM Android devices (e.g., Samsung SM-T380 running Android 9) (#SDKS-3118)
• Moved BLE operations off the main thread to prevent ANR exceptions (#SPO-139)
• NoClassDefFoundError crash during Ditto initialization in production builds (#SPO-379)

• The queryArguments property on DittoSyncSubscriptions is no longer guaranteed to be strictly equal to the original arguments passed when registering the sync subscription. This is due to a serialization roundtrip, which may affect equality checks, particularly for non-primitive values. If you want to decode query arguments into a specific type, then use the queryArgumentsCborData or queryArgumentsJsonString properties now available on DittoSyncSubscription instances and decode things as required (#17003)
• WiFi Aware now respects system data path limits to prevent resource exhaustion (#18503)
• The Flow-based DittoStoreObserver.observe() function is refactored to force the user to provide a transform function that doesn’t return the DittoQueryResult (#19214)
• The queryArguments property on DittoStoreObservers is no longer guaranteed to be strictly equal to the original arguments passed when registering the store observer. This is due to a serialization roundtrip, which may affect equality checks, particularly for non-primitive values. If you want to decode query arguments into a specific type, then use the queryArgumentsCborData or queryArgumentsJsonString properties now available on DittoStoreObserver instances and decode things as required (#CORE-862)
• Renamed DittoConnection.getPeer{1,2}Key() to getPeer{1,2}() (#SDKS-1184)
• Renamed DittoConnectionRequest.getPeerKeyString() to getPeerKey() (#SDKS-1184)
• Nested all DittoTransportConfig sub-config classes (PeerToPeer, Connect, Listen, Global, BluetoothLE, Lan, WifiAware, TcpConfig, HttpConfig) inside their parent classes with shortened names (#SDKS-1674)
• Ditto.startSync() moved to DittoSync.start(). Use ditto.sync.start() instead (#SDKS-1875)
• Ditto.stopSync() moved to DittoSync.stop(). Use ditto.sync.stop() instead (#SDKS-1875)
• Ditto.isSyncActive moved to DittoSync.isActive. Use ditto.sync.isActive instead (#SDKS-1875)
• Presence graph Peers have renamed the isConnectedToDittoCloud property to isConnectedToDittoServer to clarify that it reflects a connection to any Big Peer rather than specifically those in the Ditto cloud service (#SDKS-2188)
• Default persistence directory now uses platform-standard locations: %LOCALAPPDATA% on Windows (with %ProgramData% for system services), $XDG_DATA_HOME on Linux, unchanged on macOS. Apps with existing local data can set persistenceDirectory explicitly to preserve prior behavior (#SDKS-2464)
• DittoPeer.os property now returns DittoPeerOs? enum instead of String? for type-safe operating system representation (#SDKS-2619)
• DittoStore.execute() and DittoTransaction.execute() are now scoped APIs that auto-close DittoQueryResult. The previous execute() that returned a raw DittoQueryResult has been renamed to executeRaw() (#SDKS-2825)
• DittoException package from com.ditto.kotlin.error to com.ditto.kotlin, aligning with the Java API’s com.ditto.java.DittoException (#SDKS-2855)

• queryArgumentsCborData and queryArgumentsJsonString properties to DittoSyncSubscription instances. If you want to decode query arguments into a specific type, then use these and decode things as required (#17003)
• An overload of DittoSync’s registerSubscription method that takes an arguments value that is serializable and an accompanying serializer (#17003)
• Next Generation Networking UDP transport on WiFi Aware (#18045)
• The new transport_tcp_client_android_bind_interface system parameter which enables use of multiple NICs on Android (#20782)
• queryArgumentsCborData and queryArgumentsJsonString properties to DittoStoreObserver instances. If you want to decode query arguments into a specific type, then use these and decode things as required (#CORE-862)
• WiFi Aware transport configuration option to reset the device WiFi stack in Android profile owner scenarios, improving reliability (#NETW-435)
• API overloads on DittoStore, DittoTransaction, and DittoSync functions that take a DittoCborSerializable.Dictionary argument, so that an arbitrary map can be passed instead (#SDKS-1507)
• DittoSyncSubscription.queryArgumentsCborData property for accessing query arguments as a CBOR-encoded byte array (#SDKS-2007)
• DittoSyncSubscription.queryArgumentsJsonString property for accessing query arguments as a JSON-encoded string (#SDKS-2007)
• Linux aarch64 platform support for the Java SDK, enabling deployment on ARM64-based Linux devices such as Raspberry Pi and AWS Graviton instances (#SDKS-2463)
• Diff-aware overloads of DittoStore.registerObserver(), DittoStore.collect(), and DittoStore.observe() that deliver a DittoDiff alongside the DittoQueryResult. The differ lifecycle is tied to the observer — closing the observer frees the differ automatically (#SDKS-3002)
• DittoPresence.setPeerMetadata(Map<String, Any?>) convenience method for setting peer metadata from a plain map, matching the ergonomic pattern used by DittoStore.execute() (#SDKS-3021)
• DittoJsonSerializable.ObjectValue.toMap() method that recursively unwraps to Map<String, Any?> (#SDKS-3021)
• DittoJsonSerializable.toAny() method that converts any JSON value to its plain Kotlin equivalent (#SDKS-3021)

• DittoTransportConfig() constructor and DittoTransportConfig.Builder() no-arg constructor, which create a transport config with all transports disabled. Prefer Ditto.updateTransportConfig() to modify the existing transport configuration (#SDKS-2787)

• Ditto.runGarbageCollection(). Memory is now fully managed using AutoClosable types in the SDK (#SDKS-1851)
• DittoLogger.isEmojiLogLevelHeadingsEnabled. The setting had no effect since 4.8.0 (#SDKS-1886)
• ditto.sdkVersion. Use static Ditto.VERSION instead (#SDKS-2105)
• Ditto.getTransportDiagnostics(), DittoTransportDiagnostics, DittoTransportSnapshot, and TransportExceptionReason.FailedToDecodeTransportDiagnostics, as these APIs are now obsolete (#SDKS-2368)
• Support for Intel Macs (#SDKS-2459)
• DittoSmallPeerInfoSyncScope enum and DittoSmallPeerInfo.syncScope property. Sync scopes are now controlled via DQL ALTER SYSTEM commands (#SDKS-2683)