CRUD Fundamentals
Ditto Query Language (DQL) — the dedicated query language you'll use to perform various filter operations to carry out traditional CREATE, READ, UPDATE, and DELETE (CRUD) database operations — is a familiar SQL‑like syntax designed specifically for Ditto's edge sync features that enable the platform's offline-first capabilities.
For a list of API references by language, see the Directory of Ditto Technical Documentation in the Platform Manual.
To execute CRUD operations, call the Ditto SDK's execute API method as follows:
The following table provides a high-level overview of the different ways you can perform CRUD in Ditto:
Operation | Description |
|---|---|
CREATE | Using the INSERT statement, either insert a new document or update an existing document for a given document ID. (See Creating) |
READ | Using the SELECT statement, retrieve documents based on the specific criteria you pass as parameters in your function. (See Reading) |
UPDATE | Using the UPDATE method, write changes to Ditto. (See Updating) |
DELETE | Using the EVICT method, remove local data from your store. (See Deleting) In addition, using a soft-delete pattern, indicate data as deleted without physically removing it from Ditto. |
For detailed information on CRUD, see CRUD Operations.
For an overview of the various operators and path navigations you can use to construct sophisticated queries in your app, see Ditto Query Language.
To create a new document in your local Ditto store, call INSERT. Following is an example of how to perform an INSERT operation using Ditto's SDK:
For more information and how-to instructions, see CRUD Operations > CREATE.
To retrieve data in Ditto, depending on your goals and use case, use any of the following query types:
- Single Execution query — Using the execute method and a SELECT query, execute a single read operation. (See Single Execution Query)
- Store Observer query — Using the addObserver method, establish a listener to watch your local changes in realtime. (See Store Observer Query)
With the execute API method and SELECT query, search for documents within your local Ditto store:
For more information and how-to instructions, see CRUD Operations > READ.
When you need to actively monitor changes within your local Ditto store and respond to them immediately; for example, watching updates to end-user profiles, use a store observer.
A store observer is a DQL query that runs continuously and, once Ditto detects relevant changes, asynchronously triggers the callback function you defined when you set up your store observer. For instance, when the end user updates their profile, display the profile changes to the end user in realtime.
Following is a snippet demonstrating how to establish a store observer in Ditto:
For more information and how-to instructions, see CRUD Operations > READ.
With the UPDATE statement, you can update fields within one or more documents in your local Ditto store.
For example, executing an UPDATE operation within the cars collection, changing the color to 'blue' and the mileage to 3001 in documents where the _id field is '123':
For more information and how-to instructions, see CRUD Operations > UPDATE.
Data storage management is essential for preventing unnecessary resource usage, which affects not only performance but also battery life and overall end-user experience.
Call the Evict method to clear one or more documents from the local Ditto store. Once invoked, the documents are no longer accessible by local queries; however, they remain accessible from other peers connected in the mesh.
EVICT can be used with soft-delete patterns to safely coordinate the deletion of data across peers.
The following snippet shows how to write a basic EVICT operation to purge the document with an _id field of '123' from the local Ditto store:
For more information and how-to instructions, see CRUD Operations > DELETE.