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, as well as 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, below 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, meaning 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:

To access the result items as a JSON-string:

A store observer is a DQL query that runs continuously and triggers a callback when a change to the store impacts the results of the query.

Store observers are useful when you want to monitor changes from your local Ditto store and react to them immediately. For instance, when your end user updates their profile, asynchronously display changes in realtime.

Using the registerObserver method, set up an observer within the store namespace enclosed with a query that specifies the collection to watch for changes, as well as your logic to handle the incoming changes.

To associate arguments with your query add them as optional paramater.

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: