ditto.store.execute()
method in each of the Ditto SDKs, or via the /store/execute
endpoint in the Ditto HTTP API.
You can read more about DQL in the DQL documentation.
Creating Data
Creating data in Ditto involves inserting new documents into a collection in the local database. A collection in Ditto is similar to a table, and a document is a JSON-like object representing one record. To add a document, you typically call an insert operation on Ditto’s store. This is done using anINSERT INTO
DQL statement.
For example, you can execute a query like:
Reading Data
Reading data from Ditto is done by querying the documents in the local store using a DQLSELECT
statement.
For example:
WHERE
clause allows you to filter the results based on specific criteria.
For example:
Observing Changes
If new data arrives (via sync) or local data changes, Ditto can notify your app directly, without needing to periodically run a query, so you can update the UI in real-time. This is done using Ditto’s store observers, which is a change listener to a query that will be notified when the results of the query are updated. This is called using theditto.store.registerObserver()
method in each of the Ditto SDKs.
By specifying a DQL SELECT
statement, Ditto will notify the observer when the results of the query change. It will provide these results as a callback containing the full dataset of the results of the query, which can then be passed directly to the UI framework of your choice, which will often handle efficient updates to the UI based on the changes.
For more examples of reacting to data changes in your language of choice, please see Observing Data Changes.
Updating Data
Updating data in Ditto means modifying existing documents in a collection. You can change one or more fields of a document by executing an UPDATE statement through DQL. The syntax follows a familiar SQL pattern: you specify the target collection, set new values for one or more fields, and include a WHERE clause to select which document(s) to update. For example, suppose we have a cars collection and we want to change the color of the car with_id
123
to blue. We could run:
_id
to update a specific record, but you could update multiple documents at once if they match a filter.
Only the specified fields are modified — all other fields in the document remain unchanged.
When you execute an update, the changes are applied to the local store immediately. Ditto tracks this change and will propagate it to other peers on the network during the next sync. This means your update is done offline-safe: you can update data with no internet, and Ditto will queue that change to send out when connectivity is available. Each update operation in Ditto is idempotent on the target documents (applying the same update again will have no effect if the data is already updated) and will be merged with any concurrent changes from other devices. In essence, updating documents with Ditto is straightforward - you specify what to change and let Ditto handle applying it locally and syncing it globally.
For more examples of updating data in your language of choice, please see Updating Documents.
Removing Data
Removing data in Ditto is the process of removing documents from a collection. There are typically two reasons that you want to delete data in Ditto:- Logical Deletes
- Local Eviction
Logical Deletes
Logical deletes are a way to remove data from Ditto where the removal has a semantic meaning within your application. For example deleting a user’s account from the app. In this scenario you want to remove a document from the local store, but you also want the device to tell all other devices that it’s replicating with to remove the same document. In short, you need that delete to be propagated throughout the entire system. This can be achieved in one of two ways, depending on if you need to retain the previous value of the document for any reason.Soft-Delete Pattern
If you wish to retain the previous value of the document then we recommend following a soft-delete pattern. This is where you add a field to the document to indicate that it has been deleted, so that it can be handled appropriately throughout the rest of your system. For example you can add anisDeleted
field to the document to indicate that it has been deleted, and then when specifying your subscription and setting up local queries/observers you can filter out documents where isDeleted
is true.
For example:
Tombstones
If you do not need to retain the previous value of the document then you can use a tombstone pattern. This is where you remove the document from the local store entirely. This can be done using the.remove()
method in the Ditto SDK, and in Ditto Server using the TOMBSTONE
DQL operation:
These two different mechanisms will be collapsed into a single
DELETE
operation in Ditto 4.10.Tombstones will also be cleaned up automatically in Ditto 4.10.Local Eviction
There are many scenarios where you may want to remove data from the local store without it being propagated to other devices. For example, in point-of-sales systems, it is not necessary to keep more than a few days of transaction data on the device, but you still need to retain the data upstream for reporting purposes. This local purging is achieved using theEVICT
DQL operation.
For example: