This article provides an overview of essential methods for reading documents within Ditto.
execute
API method on the store
namespace as follows:
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.
SELECT * FROM cars WHERE color = blue
.
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
:
items
object is a collection ofQueryResultItem
. Each item’s value can be independently managed to meet the needs of your scenario.
value
property on an item:
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:
DittoDiffer
class that
allows you to opt-in to diffing only when necessary, thereby avoiding
unnecessary performance and memory costs.
However, diffing is computationally expensive. It requires storing the previous query
results in memory, leading to increased RAM usage, which can be particularly
problematic for applications handling large datasets or frequent updates.
Instead of computing diffs synchronously with every store observer update, it is
recommended to debounce diffing, processing changes out-of-band at a cadence
that best suits your use case.
A DittoDiffer
is given query result items and compares them to the previous set of items it has received:
diff()
method returns a DittoDiff
containing:
insertions
: Indexes of new items in the new arraydeletions
: Indexes of items that were removed from the old arrayupdates
: Indexes of items in the new array that were present in the old array and whose value has changedmoves
: Pairs of indexes showing items that changed positionUITableView
, UICollectionView
:
updated
unless those changes result in a different value from the initial state to the final state.
event
parameters, you can migrate to the newer store observer pattern with the DittoDiffer
class. The differ provides equivalent functionality but requires manual management of previous results.
For a complete migration guide, see Replacing Live Query Events with Store Observers.