READ

This article provides an overview of essential methods for data retrieval.

Just like with conventional database querying, you execute query operations to fetch one or more documents that satisfy specific criteria and conditions.

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, 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: