CRUD Operations
Ditto's query engine and API methods allow you to perform traditional create, read, update, and delete (CRUD) operations.
This article provides an introduction to querying operations in Ditto and the fundamental concepts to know.
For comprehensive information, how-to instructions, as well as code examples in each language, see any of the following children articles:
In Ditto, you use queries to read data from local Ditto stores, and various methods to perform CRUD operations.
When interacting with the platform, you'll notice that Ditto's query language is quite similar to what you'd expect in most if statements.
You'll use familiar techniques like using an update statement to modify existing data, dot notation to navigate levels in a hierarchy, upon other intuitive query condition operators typical for performing standard CRUD.
For a complete overview of the syntax you can use in your queries, see Query Syntax.
The Ditto SDK provides a comprehensive set of methods and functions to facilitate data interaction and perform a wide range of operations in your app:
- For read operations, use the Find and Observe Local methods.
- For write operations, use the Update, Upsert, Evict, and Delete methods.
At a high-level, queries operate on collections rather than individual documents. This approach to data management enhances retrieval efficiency and ensures seamless data replication among connected peers.
For an overview of the syntax you can use to filter your queries, see Ditto Basics > Syntax .
The following table provides an overview of the three types of queries you use to fetch documents and set up listeners in your app:
Type | Description | Use Case |
|---|---|---|
Local query |
| You want to quickly search or retrieve specific data, such as an attachment, recent activities, and so on, that is stored within a particular local Ditto store. |
Live query |
| You want to display realtime updates to your end user any time you receive an incoming remote change sent from another connected peer. |
Replication query |
When these conditions are observed within the mesh, Ditto automatically triggers a subscribe callback object that executes your subsequent processes and actions in your app. | You want to receive notification whenever changes are made by any peer participating in the mesh, so you can respond as appropriate to ensure realtime collaboration with remote peers. |
There are two methods you can use to retrieve documents stored at your local Ditto store:
- find— Returns all local documents that match your criteria.
- findById— Returns only the local document assigned the _id you provide.
If you're interested in actively listening for changes and events in the data so you can react accordingly, convert the local query to a live query by adding the observeLocal method in the enclosure.
When working with data subject to change at runtime, instead of building or interpolating query strings, you can query with runtime variables through an $args map object.
For more information and how-to instructions, see Finding and Observing.
Unlike the Observe Local method, which establishes a local listener, the subscribe method establishes a mesh-wide listener so you can stay up-to-date with data changes happening across remote peers.
Once you've initiated data replication by invoking the Start Sync method, you can set up a subscription to signal which data you're interested in automatically receiving updates for, as well as the subsequent actions for Ditto to perform in your app.
Given this subscription-driven approach, you eliminate the need to perform traditional resource‑intensive and time‑consuming methods of data retrieval in your app, such as repeatedly executing HTTP requests and polling a queue for data updates.
For more information and how-to instructions, see Finding and Observing.
There are two ways you can write changes to Ditto: upsert the changes or update the changes.
Choosing which to use depends on what you're trying to achieve:
- With the Update method:
- You can query a property locally, and then make changes to each individual property only if that property has changed.
- You can create fine-grained changes to a single document or make batch changes to a set of documents.
- Due to Ditto’s conflict-free eventual consistency data model, there is no concept of “insert”; instead, each device assumes that their write transaction already exists somewhere in the broader Ditto system. Therefore, with the Upsert method:
- You can upsert only the fields within the document that have changed.
- If all of the fields in the document are new, Ditto creates an entirely new document object and, unless manually supplied, generates and assigns that document a unique identifier, the _id.
For more comprehensive information, see For more information, see Upserting and Updating.
There are two approaches to removing data in Ditto, and the decision of which to choose depends on your specific requirements and use case:
- Remove — Permanently deletes one or more specified documents from a collection throughout the entire Ditto platform.
- Evict — Physically eliminates the specified documents from its Ditto store to free up local memory or on-disk storage, prevents any pending changes affected by the eviction from being sent across the mesh network, and leaves the documents stored in remote Ditto stores intact so they remain accessible to all connected peers.
- Soft-delete pattern — Adds a "forget" flag to the specified documents indicating that, although still accessible to remote peers for inspection and viewing, write operations, are restricted.
For more information and how-to instructions, see Evicting and Removing.
You can model relationships between your data using foreign‑key relationships and key‑value pair relationships by way of embedded maps and arrays.
Ditto does not support nesting documents within documents. If you need to create relationships between documents, use a foreign-key relationship by referencing the document ID. For more information, see Foreign-Key Relationship.
For more information, see any of the following: