Legacy-to-DQL Adoption Guide
A simple SQL-like query language designed specifically for the features and capabilities of the Ditto platform.
Intended for those developers already using Ditto with their app to sync, this guide provides an overview of how to adopt DQL and the corresponding usage APIs.
Introduction
There are two primary ways to use DQL within the Ditto SDK:
DQL for Local CRUD Operations
Local CRUD operations using DQL include the ditto.store.execute(...)
and
ditto.store.observeLocal(...)
APIs. These operations are only performed
against the local data store and can be used alongside existing legacy builder
queries.
- Local CRUD operations are backward-compatible
- Local CRUD operations can be used alongside legacy builder queries
- Local CRUD operations include all operations except those using
.subscribe()
- For example:
find(...)
,findById(...)
,upsert(...)
, and so on.
- For example:
Update to 4.11
Upgrade to v4.11 and disable DQL_STRICT_MODE
on all devices
This enables backward compatibility with Legacy builder to ensure that Ditto returns the most up-to-date version of your document fields.
Read Operations
DQL for CRUD operations can be adopted quickly or slowly depending on your business needs.
For most customers, it will be best to take a phased approach to adopting DQL where there are both legacy queries and DQL queries used together. This is because it’s often not practical to change all operations in a single pass, either due to complexity or risk of introducing regressions.
- Replace
observe
: Use DQL’sregisterObserver
statements instead of the legacyobserve
method. - Replace
exec
queries: Update your legacy execution queries to their DQL equivalents. - Test Compatibility: Verify that your application behaves correctly between mixed versions of your app.
Upsert Operations
INSERT ... DO MERGE
statements behave the same as the legacy query builder upsert
.
Update Operations
The new update operations mimic the legacy behavior while allowing for more flexible document updates. Consider these examples:
Updating a single document
Updating multiple documents in the same collection
Updating multiple documents in multiple collections in a single transaction
Use the transaction()
method if you need to execute multiple database operations
in one atomic transaction. Read more at Transactions
Handling placeholders in field identifiers
It isn’t possible to use a placeholder in a field identifier in an UPDATE
statement in DQL. Instead, use INSERT ... DO MERGE
as follows:
Serialization
When reading and writing documents from the database, the serialization format
(CBOR
) is the same as the legacy query builder, so on-disk format is comatible between both query engines.
However, when using DQL, you must implement your own serialization for the
INSERT
and SELECT
statements. Ditto no longer supports built-in variations
such as Codable in Swift.
For example, the following code shows how to use Swift’s JSONDecoder
to serialize
a document before inserting it into the database:
This example shows how to use JSONDecoder
to deserialize a document when reading
a QueryResultItem
from the database:
DQL for Data Sync Subscriptions
DQL Subscriptions are forward-compatible starting at v4.5.
This means that devices using DQL and the ditto.sync.registerSubscription(...)
API on v4.5 or later will only be able to sync with other devices on v4.5 or later.
Ensure all devices in your production environment are using v4.5 and above
This is the minimum version required to use DQL for data sync subscriptions.
Success!
Now you are safe to start using DQL via the ditto.sync.registerSubscription(...)
To introduce DQL for data subscriptions in a phased approach, we recommend you consider:
- Using DQL for new subscriptions
- Updating existing subscriptions one at a time
Reference Example
Legacy
DQL
Key Notes
- Subscriptions behave the same regardless of whether strict mode is enabled or disabled.
- v4.0-v4.4 clients will not fail or crash when they receive a DQL request from a v4.5 client
- v4.5 clients will continue to send data to v4.0-4.4 clients
- Legacy query subscriptions will continue to work across all v4 versions including v4.5 e.g.
ditto.store.collection("cars").find("cars == 'blue'").subscribe()
- Legacy query subscriptions will work alongside DQL subscriptions
DQL and Ditto Server
DQL is rolled out across all Ditto Server deployments, and v4.5 and above with DQL will work without any additional changes.