MAP

an alternative approach to using a json object as a register to represent and organize data in a hierarchical structure within a document is to use a map the map type uses the add wins approach to resolving concurrency conflicts so instead of choosing a single definitive value to merge and distribute across peers like the last write wins strategy utilized by the register and attachment data types, choose them all — even if the data is already contained within the map object comparing a json object the map data type in dql forms a tree like, parent child relationship within a document's dataset this is similar to a json object, which functions as a single unit however, a map allows nesting of various dql data types register , map , and attachment as values for its keys each key value pair within a map can be modified independently without affecting other pairs utilization of an add wins merge strategy for conflict resolution when conflicting changes occur during sync, all conflicting changes are retained rather than converging on only one this ensures that no data is lost map data structure the response structure of a map is a json like object; however, each field in a map has a corresponding data type this means that each field within a map has an independent merge definition the same as fields on the top level document the map type is useful when creating a list of non conflicting items and updating items over time within a document the following snippet demonstrates a ditto document with an embedded map my map ditto document { " id" "123" "my map" { "sub field" "value", } } declaring a map the register is the default data type in ditto; therefore, there is no need for explicit declaration — it's implicitly assumed however, to use a map (and attachment ) data type, you must explicitly declare it within your dql statement using t ype definition syntax a type definition is a description informing ditto that the given set of key value pairs embedded in the document as a nested structure is distinct from the default register type this definition specifies how ditto should handle the dataset within that nested structure to declare a data type a map , you use the collection identifier prefix, followed by the collection name enclosed in parentheses alongside a type definition all done inline as follows dql collection your collection name (my map 1 map, my map 2 map, ) for more information and how to instructions, see ditto query language > docid\ xmnfy9mgvsnxp3q7kiiud merge strategy with map the map type has an add wins merge behavior this means that the adding or updating of a field always wins over the removal ( tombstone ) of the same field when performing a merge across two peers conflicts with multiple field entries if multiple fields are added across small peer devices, the result will be a map with all added fields this is because each field within a map is associated with a distinct data type; that is, each can be represented as a register , map , or an attachment that means, unlike a json blob object, which acts as a register functioning as a single unit, the merge strategy for each field within a map object depends on each of their data type representation in the following example, user 1 inserts item1 and user 2 inserts item2 to an items map dql # user 1 adds item1 update collection my collection (items map) set items > (item1 = 'red') where id = '123' dql # user 2 adds item2 update collection my collection (items map) set items > (item2 = 'blue') where id = '123' the resulting document contains an items map with both item1 and item2 ditto document { " id" "123" "items" { "item1" "red", "item2" "blue", } } comparing map with register types the nested json object functions as a register and closely resembles a nested map structure within a document however, their merge strategies and supported types for nested values are significantly different understanding these distinctions is crucial when selecting the appropriate data type for expressing your data structure example scenario for example, consider a document with a properties field of the register data type storing information about a car in an embedded json object you want to change only the color field for a car identified by document id 123 to blue since a register acts as a single object, to update just the color , you'd need to update the entire object by providing the entire set of nested key value pairs, including the modified color , as follows let newproperties = \[ "color" "blue", "sunroof" true, "door count" 4 ] await ditto store execute( "update cars set properties = \ newproperties where id = '123'", \["newproperties" newproperties]);var result = ditto store execute( "insert into cars documents (\ newcar)", mapof("newproperties" to mapof("color" to "blue", "sunroof" to true, "door count" to 4)))const newproperties = { color 'blue', sunroof true, door count 4 } await ditto store execute( "update cars set properties = \ newproperties where id = '123'", {newproperties});map\<string, string> newproperties = new hashmap<>(); newcar put("color", "blue"); newcar put("sunroof", true); newcar put("door count", 4); dittoqueryresult result = (dittoqueryresult) ditto store execute( "update cars set properties = \ newproperties where id = '123'", collections singletonmap("newproperties", newproperties), 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 args = new dictionary\<string, object>(); args add("newproperties", new { color="blue", sunroof=true, doorcount=4}); await ditto store executeasync( "update cars set properties = \ newproperties where id = '123'", args);struct properties { std string color; bool sunroof; int door count; }; // std map\<std string, properties> args; args\["newproperties"] = {"blue", true, 4}; ditto get store() execute( "update cars set properties = \ newproperties where id = '123'", args);struct properties { color string, sunroof bool, door count i32 } struct args { newproperties properties, } // let args = args { newproperties properties { color "blue" to string(), sunroof true, door count 4 } }; await ditto store() execute( "update cars set properties = \ newproperties where id = '123'", args);final newproperties = { "color" "blue", "sunroof" true, "door count" 4, }; await ditto store execute( "update cars set properties = \ newproperties where id = '123'", arguments {"newproperties" newproperties}, ); however, if the properties field is of the map data type instead, to update the color without altering the other nested key value pairs in the set, assign the properties color field to blue as follows dql update collection cars (properties map) set properties > (color = blue) where id = '123' conflicts with tombstone and modify if a tombstone (deletion flag) and a modification ( insert ) operation occur across two peers simultaneously, the resulting state depends on the causal order of these changes causal order refers to the logical sequence in which events occur, considering the cause and effect relationship between them modifications to the value of fields within a map do not count as modifications to the map itself following is a truth table showing "if a map is deleted" based on "if the peers are connected" and "when the tombstone operation occurs relative to the modification " peer status tombstone first tombstone last connected false true disconnected false false warnings and cautions syncing large documents can significantly impact sync performance consider using an attachment instead of a regular document when handling a deeply embedded or large document object when internet connection is limited or using only bluetooth low energy (le) to sync across connected peers, syncing documents containing large amounts of data is slow for instance, when using only bluetooth le to sync a document of a typical size, the rate of replication is 20 kb per second maximum given this, a document of 250 kb or larger may require 10 seconds or more to sync for the first time between small peer devices a slow replication rate results in a loading spinner displayed to your end users until the sync process fully completes this is due to the callback being unable to render the returned data; the end to end sync process requires that documents be broken down into smaller parts before being synced across the mesh, and then, until the client receives all of the smaller parts and reconstructs them, the document is not returned instead of using a single document to encode large datasets, use a series of smaller documents if a document exceeds 250 kb, a stdout warning prints any docu ments exceeding 5 mb do not sync to other peers