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 docid\ hvfmp8tx4cwki4h2xotuy docid\ l2hfjvzuyynu5ahzxhwaj docid\ q6vsbhczgypt1hlzgow4e docid\ c v5q9jyhmvemvsdipj2u if you're using ditto's big peer cloud deployment, for an overview of the http api for data egress, as well as the livequery webhook for real time bidirectional change data capture (cdc) with a third party data product, see the platform manual > docid\ h cbspstnhl5veceerb0m introduction 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 docid\ mmtismykr3hxzmys1bi2w 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 fundamental concepts 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 > docid\ byukq4ekkuevjbx feuog 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 invoked by way of either the find or find by id method the local query specifies your operation to execute as a single operation on its local datastore 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 established through the observe local method you use the observe query to define your observe criteria once your observe conditions are met, ditto automatically triggers an observe callback function that executes the subsequent actions based on your observe query in your app 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 activated using the subscribe method, which sets up your subscription the subscription query instructs specify your query conditions 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 finding and observing 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 docid\ hvfmp8tx4cwki4h2xotuy subscribing 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 docid\ hvfmp8tx4cwki4h2xotuy updating and upserting 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 docid\ l2hfjvzuyynu5ahzxhwaj evicting and removing there are two approaches to removing data in ditto, and the decision of which to choose depends on your specific requirements and use case invoking the remove method results in irreversible data loss 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 docid\ q6vsbhczgypt1hlzgow4e establishing relationships you can model relationships between your data using docid 1cexfnswhjeqa r6yyl 8 and docid 1cexfnswhjeqa r6yyl 8 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 docid 1cexfnswhjeqa r6yyl 8 for more information, see any of the following for an overview of ditto's advanced types, see docid\ yxemkh1com3csuumqcnlf for more information about relationships, see docid\ lqgzvvhtqzybx ald5b8j