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 introduction there are two primary ways to use dql within the ditto sdk /#dql for local crud operations /#dql for data sync subscriptions dql for local crud operations 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 key notes 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 best practices for adopting dql for local crud 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 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 crud operation reference example for more examples, see the docid\ fh0z1tkbbdgr5ppirrtvq legacy await ditto store collection('cars') find('color == "blue"') dql await ditto store execute(` select from cars where color = 'blue' `) dql for data sync subscriptions 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 key notes 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 best practices for adopting dql for data sync subscriptions 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 data sync subscription reference example legacy ditto store collection('cars') find('color == "blue"') subscribe() dql ditto sync registersubscription(` select from cars where color = 'blue' `) dql and the big peer dql is rolled out across all big peer deployments, and v4 5 with dql will work without any additional changes