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, as well as to set up listeners, referred to as subscriptions , for the data you're interested in watching /#single execution queries /#store observer queries single execution queries to perform a single execution query on the ditto store, call the execute api method on the store namespace as follows let result = await ditto store execute(query "select from cars")val result = ditto store execute("select from cars")const result = await ditto store execute("select from cars");dittoqueryresult result = (dittoqueryresult) ditto store execute( "select from cars", new continuation<>() { @nonnull @override public coroutinecontext getcontext() { return emptycoroutinecontext instance; } @override public void resumewith(@nonnull object o) { if (o instanceof result failure) { // handle failure } } } );var result = await ditto store executeasync("select from cars");auto result = ditto get store() execute("select from cars") get();let result = ditto store() execute("select from cars", none); using args to query dynamic values 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 let result = await ditto store execute( query "select from cars where color = \ color", arguments \[ "color" "blue" ])val result = ditto store execute( "select from cars where color = \ color", mapof("color" to "blue"))const result = await ditto store execute( "select from cars where color = \ color", { color "blue" });dittoqueryresult result = (dittoqueryresult) ditto store execute( "select from cars where color = \ color", collections singletonmap("color", "blue"), new continuation<>() { @nonnull @override public coroutinecontext getcontext() { return emptycoroutinecontext instance; } @override public void resumewith(@nonnull object o) { if (o instanceof result failure) { // handle failure } } } );const result = await ditto store executeasync( "select from cars where color = \ color", new dictionary\<string, object> { "color", "blue" });auto result = ditto get store() execute( "select from cars where color = \ color", {{"color", "blue"}}) get();struct args { color string, } // let args = args { color "blue" to string(), }; let result = ditto store() execute( "select from cars where color = \ color", some(args into())); 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 managing query results 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 let result = await ditto store execute(query "select from cars") let items = result itemsval result = ditto store execute("select from cars") const items = result itemsconst result = await ditto store execute("select from cars") const items = result itemsdittoqueryresult result = (dittoqueryresult) ditto store execute( "select from cars", new continuation<>() { @nonnull @override public coroutinecontext getcontext() { return emptycoroutinecontext instance; } @override public void resumewith(@nonnull object o) { if (o instanceof result failure) { // handle failure } } } ); dittoqueryresultitems items = result items;var result = await ditto store executeasync("select from cars"); var items = result items;auto result = ditto get store() execute("select from cars") get(); auto items = result items();let result = ditto store() execute("select from cars", none); let items = result items(); working with a queryresultitem the result items object is a collection of queryresultitem each item's value can be independently managed to meet the needs of your scenario value to retrieve the value, call the value property on an item let result = await ditto store execute(query "select from cars") let item = result items\[0] let itemvalue = item value let itemvaluecolor = item value\["color"]val result = ditto store execute("select from cars") val item = result items first() val itemvalue = item value val itemvaluecolor = item value\["color"]const result = await ditto store execute(`select from cars`) const item = result items\[0] const itemvalue = item value const itemvaluecolor = item value\["color"]dittoqueryresult result = (dittoqueryresult) ditto store execute( "select from cars", new continuation<>() { @nonnull @override public coroutinecontext getcontext() { return emptycoroutinecontext instance; } @override public void resumewith(@nonnull object o) { if (o instanceof result failure) { // handle failure } } } ); dittoqueryresultitem item = result items\[0] map\<string, object> itemvalue = item value string itemvaluecolor = item value\["color"] tostring()var result = await ditto store executeasync("select from cars"); var item = result items\[0]; var itemvalue = item value; var itemvaluecolor = item value\["color"] as string;// use json or cbor valuelet result = ditto store() execute("select from cars", none); let item = result items(0); let itemvalue = item materialize(); materializing the value 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 // returns `true` if value is currently held materialized in memory, otherwise returns `false` item ismaterialized // loads the item's value into memory item materialize() // release item's value from memory item dematerialize()// returns `true` if value is currently held materialized in memory, otherwise returns `false` item ismaterialized // loads the item's value into memory item materialize() // release item's value from memory item dematerialize()// returns `true` if value is currently held materialized in memory, otherwise returns `false` item ismaterialized // loads the item's value into memory item materialize() // release item's value from memory item dematerialize()// returns `true` if value is currently held materialized in memory, otherwise returns `false` item ismaterialized // loads the item's value into memory item materialize() // release item's value from memory item dematerialize()// returns `true` if value is currently held materialized in memory, otherwise returns `false` item ismaterialized; // loads the item's value into memory item materialize(); // release item's value from memory item dematerialize();// not supported// loads the item's value into memory item materialize(); raw cbor value to access the result items as cbor data the result of this method call is not cached let result = await ditto store execute(query "select from cars") let cborserializeditem = result items\[0] cbordata()val result = ditto store execute("select from cars") val cboritem = result items first() cbordata()const result = await ditto store execute(`select from cars`) const cboritem = result items\[0] cbordata()dittoqueryresult result = (dittoqueryresult) ditto store execute( "select from cars", new continuation<>() { @nonnull @override public coroutinecontext getcontext() { return emptycoroutinecontext instance; } @override public void resumewith(@nonnull object o) { if (o instanceof result failure) { // handle failure } } } ); byte\[] cboritem = result items\[0] cbordata()var result = await ditto store executeasync("select from cars"); var cboritem = result items\[0] cbordata();auto result = ditto get store() execute("select from cars") get(); auto cboritem = result get item(0) cbor();let result = ditto store() execute("select from cars", none); let cboritem = result items(0) cbor(); raw json value to access the result items as a json string the result of this method call is not cached let result = await ditto store execute(query "select from cars") let jsonserializeditem string = result items\[0] jsonstring() let jsonasdata data = data(jsonserializeditem utf8)val result = ditto store execute("select from cars") val jsonitem = result items first() jsonstring()const result = await ditto store execute(`select from cars`) const jsonitem = result items\[0] jsonstring()dittoqueryresult result = (dittoqueryresult) ditto store execute( "select from cars", collections singletonmap("color", "blue"), new continuation<>() { @nonnull @override public coroutinecontext getcontext() { return emptycoroutinecontext instance; } @override public void resumewith(@nonnull object o) { if (o instanceof result failure) { // handle failure } } } ); string cboritem = result items\[0] jsondata()var result = await ditto store executeasync("select from cars"); var jsonitem = result items\[0] jsonstring();auto result = ditto get store() execute("select from cars") get(); auto jsonitem = result get item(0) json();let result = ditto store() execute("select from cars", none); let jsonitem = result items(0) json(); store observer queries 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 setting up store observers 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 let observer = ditto store registerobserver( query "select from cars"){ result in / handle change / };val observer = ditto store registerobserver("select from cars") { result > / handle change / };const changehandler = (result) => { // handle change } const observer = ditto store registerobserver( "select from cars", changehandler);dittostoreobserver observer = ditto store registerobserver( "select from cars", result > { // handle change } );// without arguments var result = await ditto store registerobserver( "select from cars", (result) => { // handle change }); // with arguments var result = ditto store registerobserver( "select from cars", (result) => { // handle change }); auto observer = ditto get store() register observer( "select from cars", \[&]\(queryresult result) { / handle change / });let observer = ditto store() register observer( "select from cars", none, move |result queryresult| { // handle change }) associating arguments to associate arguments with your query let observer = ditto store registerobserver( query "select from cars where color = \ color", argumets \[ "color" "blue" ]){ result in / handle change / };ditto store registerobserver( "select from cars where color = \ color", mapof("color" to "blue")) { result > / handle change / };const changehandler = (result) => { // handle change } const observer = ditto store registerobserver( "select from cars where color = \ color", changehandler, { color 'blue' });dittostoreobserver observer = ditto store registerobserver( "select from cars where color = \ color", collections singletonmap("color", "blue"), result > { // handle change } );// without arguments var result = await ditto store registerobserver( "select from cars", (result) => { // handle change }); // with arguments var result = ditto store registerobserver( "select from cars where color = \ color", new dictionary\<string, object> { "color", "blue" }, (result) => { // handle change }); auto observer = ditto get store() register observer( "select from cars", {{"color", "blue"}}), \[&]\(queryresult result) { / handle change / });struct args { color string, } // let args = args { color "blue" to string(), } let observer = ditto store() register observer( "select from cars where color = \ color", args, move |result queryresult| { // handle change }) canceling a store observer 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 observer cancel()observer cancel()observer cancel()observer cancel();observer cancel()observer cancel();observer cancel() accessing store observers to access store observers from the local ditto store ditto store observersditto store observersditto store observersditto store observers;ditto store observersditto get store() observers()ditto store() observers()