READ
This article provides an overview of essential methods for document retrieval, query formulation, and realtime monitoring.
Just like with conventional database querying, you execute query operations to fetch one or more documents that satisfy specific criteria and conditions. Additionally, you use queries to set up listeners, referred to as subscriptions, for the data you're interested in watching.
To perform a single execution query on the Ditto store, call the execute API method on the store namespace as follows:
When dealing with data that may change dynamically during runtime, instead of defining the changing values directly in the query string, encapsulate them in a top-level args object you can use to reference the values in your queries.
To pass an argument to the execute function, use the :[argument] syntax with DQL where the [argument] maps to the field in the provided args object.
For example, here color is passed as an argument to the execute function, and, within the query string, :color placeholder references the color defined in a top-level args object.
Once the previous example operation executes, the query becomes SELECT * FROM cars WHERE color = blue.
After executing a query, the result object that is returned includes both the overall content retrieved and individual items. Each item is encapsulated in independent QueryResultItem objects that you can use to access them either directly or as raw CBOR or JSON data.
Rather than retrieving the items as part of the query execution and making them available immediately after execution, each item is lazy loaded. Lazy loading involves postponing fetching and storing in memory until requested on-demand or accessed later.
Here is an example query execution to select all documents from the cars collection. The result is stored in the variable result. Then, each item is lazy loaded from the result object and stored in the items:
The result items object is a collection ofQueryResultItem. Each item's value can be independently managed to meet the needs of your scenario.
To retrieve the value, call the value property on an item:
To help manage memory usage more efficiently, content associated with an item is lazily loaded; that is, it materializes — loads into memory — only upon the initial call to value.
To load the item's value into memory, use any of the following methods as appropriate:
To access the result items as CBOR data:
The result of this method call is not cached.
To access the result items as a JSON string:
The result of this method call is not cached.
To work with an attachment, first acquire its associated attachment token, which includes details like the _id that identifies the attachment stored externally.
Once obtained, use this token to reference the attachment and perform operations like UPDATE.
Using the attachment token, access your external attachment data on demand:
A store observer is a continuous DQL query. When a change to the store impacts the results of the query, it automatically triggers a callback that you can use to perform some action in your app.
Store observers are useful when you want to monitor changes from your local Ditto store and react to them immediately. For instance, if your end user updates their profile, you can asynchronously display those changes to them in realtime.
To cancel a store observer, call cancel on the observer object.
Once canceled, the store observer will stop processing in the background and will no longer call the provided callback.
To access store observers from the local Ditto store: