Legacy-to-DQL Adoption Guide
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.
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.
There are two primary ways to use DQL within the Ditto SDK:
Local Crud Operations using DQL can be used without any coordination across versions.
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 for ones using .subscribe()
- For example: find(...) , findById(...) , upsert(...) , and so on.
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.
To introduce DQL in a phased approach, we recommend you consider:
- Using DQL for new local CRUD operations
- Upgrading all usage of a specific operation. For example only evict, update, or findById operations in a single change
- Updating complex operations or queries one at a time
For more examples, see the Legacy-to-DQL Reference.
Legacy
DQL
Data Sync Subscriptions using DQL 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.
This is because v4.4 and earlier clients don’t have the ability to understand DQL subscriptions so don’t know how to correctly respond.
- v4.0-4.4 clients will continue to communicate with each other
- v4.0-4.4 will not sync with v4.5 clients that use DQL data sync subscriptions
- v4.0-4.4 will log a DQLError log when they receive a DQL data sync subscription request
- 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 versions including v4.5 e.g. ditto.store.collection("cars").find("cars == 'blue'").subscribe()
- Legacy query subscriptions will work alongside DQL subscriptions
- All versions v4.0 and later can communicate with the Big Peer
If you want to adopt DQL for data sync operations and need to ensure communication between previous versions, do the following:
- Upgrade to v4.5 without adopting DQL for data sync subscriptions
- Release v4.5 to all devices in your production environment
- Ensure all devices in your production environment are using v4.5
- Success! Now you are safe to start using DQL via the ditto.sync.registerSubscription(...)
To adopt DQL for data sync operations, just start using the ditto.sync.registerSubscription(...) API.
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
Legacy
DQL
DQL is rolled out across all Big Peer deployments, and v4.5 with DQL will work without any additional changes.