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 similar to a json object, the map data type in dql forms a tree like parent child relationship within a document's dataset however, unlike a json object which is limited to scalar subtypes, functions as a single value, and enforces a last write wins merge strategy, a map allows nesting of various dql data types register , map , and attachment independent modification of each key value pair utilization of an add wins merge strategy for conflict resolution with the add wins approach, all conflicting changes are retained rather than converging on only one 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 you want to create a list of non conflicting items and update 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", } } add wins merge strategy 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 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 type definition syntax a type definition is a description that informs ditto that the given set of key value pairs embedded in the document as a nested structure is of the non register type and has specific characteristics in how it handles data to declare a data type a map , you use the collection identifier prefix, followed by the collection name enclosed in parentheses, along with 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 docid\ e3uqqeqvzvotjls2xfdfl > docid\ gsusic4zsrjq 0h07ckn creating a map in a document there are two ways to create a map structure in an insert operation — create a new document and nest it with this set of fields (see /#inserting to create a map ) in an update operation — if the map does not already exist, create it (see /#updating to create a map ) when you need to represent a highly complex data structure in a map , consider embedding another map embedding a map within a map establishes an additional hierarchy there are the decision to use deeply embedded maps in a single document or opt for a flat model instead depends on your specific requirements, relationships between data, and tolerance for certain tradeoffs the flat model is a simple, non‑embedded structure in which you spread your data across multiple separate documents inserting to create a map when inserting a new document in ditto, you can define a field as a map and include the structure of key value pairs nested within it — a two in one approach for example let arguments \[string any] = \[ "newcar" \[ " id" "123", "properties" \[ "color" "blue", "mileage" 3000 ] } ]; await ditto store execute( query "insert into collection cars (properties map) documents (\ newcar)", arguments arguments);val arguments = mapof( "newcar" to mapof( " id" to "123", "properties" to mapof( "color" to "blue", "mileage" to 3000 ) ) ) ) ditto store execute(""" insert into collection cars (properties map) documents (\ newcar) """, arguments)const newcar = { id "123", properties { color 'blue', mileage 3000 } } await ditto store execute(` insert into collection cars (properties map) documents (\ newcar)`, { newcar });map\<string, object> properties = new hashmap<>(); properties put("color", "blue"); properties put("mileage", 3000); map\<string, object> newcar = new hashmap<>(); newcar put(" id", "123"); newcar put("properties", properties); dittoqueryresult result = (dittoqueryresult) ditto store execute( "insert into collection cars (properties map) documents (\ newcar)", collections singletonmap("newcar", newcar), 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 submap = new { color = "blue", mileage = 3000 }; var insertargs = new dictionary\<string, object>(); insertargs add("newcar", new { id = newid, properties = submap }) var result = await ditto store executeasync( "insert into collection cars (properties map) documents (\ newcar)", insertargs);struct properties { std string color; int mileage; }; struct car { std string id; properties properties; }; // std map\<std string, car> args; args\["newcar"] = {"123", {"blue", 3000}}; ditto get store() execute( "insert into collection your collection name (properties map)" \+ " documents (\ newcar)", args) get();struct args { newcar car, } struct properties { color string, mileage i32 } struct car { id string, properties properties } // let args = args { newcar car { id "123" to string(), properties properties { color "blue" to string(), mileage 3000 } }, }; await ditto store() execute( "insert into collection cars (properties map) documents (\ newcar)", args); another method to creating a map within a document is to perform an update operation in the update approach, you set the structure of key value pairs and specify the document id for storage for example, this statement creates the map structure — unless it already exists — setting a single key value pair of color is red within the properties map for the document with the id 123 in the cars collection dql update collection cars (properties map) set properties > ( color = 'red' ) where id = '123' for more information and how to instructions, see docid\ e3uqqeqvzvotjls2xfdfl > docid\ qsoasgyrr0l0dydxy77ca updating to create a map maps can be updated with specific dql arrow operator syntax > ( ) this syntax allows for multiple child fields to be edited on a single map dql update collection cars (properties map) set properties > ( color = 'red', mileage = 3001 ) where id = '123' for more information and how to instructions, see docid\ e3uqqeqvzvotjls2xfdfl > docid\ gsusic4zsrjq 0h07ckn > docid\ gsusic4zsrjq 0h07ckn embedding a map in a map if you need to represent and organize highly complex data in a hierarchical structure, consider embedding a map within another map to establish a parent child relationship within a document as follows let arguments \[string any] = \[ "newdocument" \[ " id" "123", "top map" \[ "nested map" \[ "color" "blue" ] ] } ]; await ditto store execute( query """ insert into collection your collection name (top map map(nested map map)) documents (\ newdocument) """, arguments arguments);val arguments = mapof( "newdocument" to mapof( " id" to "123", "top map" to mapof( "nested map" to mapof( "color" to "blue" ) ) ) ) ditto store execute(""" insert into collection your collection name (top map map(nested map map)) documents (\ newdocument) """, arguments)const newdocument = { id "123", top map { nested map { color "blue" } } } await ditto store execute(` insert into collection your collection name (top map map(nested map map)) documents (\ newdocument)`, { newdocument });map\<string, object> nestedmap = new hashmap<>(); nestedmap put("color", "blue"); map\<string, object> topmap = new hashmap<>(); topmap put("nestedmap", nestedmap); map\<string, object> newdocument = new hashmap<>(); newdocument put(" id", "123"); newdocument put("topmap", topmap); dittoqueryresult result = (dittoqueryresult) ditto store execute( "insert into collection your collection name (top map map(nested mapmap)) documents (\ newdocument)", collections singletonmap("newdocument", newdocument), 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 nestedmap = new { color = "blue" }; var topmap = new { nestedmap = nestedmap }; var args = new dictionary\<string, object>(); args add("newdocument", new { id = newid, topmap = topmap }) var result = await ditto store executeasync( "insert into collection your collection name (top map map(nested map map))" \+ " documents (\ newdocument)", args);struct nestedmap { std string color; }; struct topmap { nestedmap nestedmap; }; struct document { std string id; topmap topmap; }; // std map\<std string, document> args; args\["newdocument"] = {"123", topmap{nestedmap{"blue"}}}; ditto get store() execute( "insert into collection your collection name (properties map)" \+ " documents (\ newdocument)", args);struct args { newdocument document, } struct nestedmap { color string } struct topmap { nestedmap nestedmap } struct document { id string, topmap topmap } // let args = args { newdocument document { id "123" to string(), topmap topmap { nestedmap nestedmap { sobfield "blue" to string() } } }, }; await ditto store() execute(" "insert into collection your collection name (properties map)" \+ " documents (\ newdocument)", args); deleting a map the map data type can be marked as deleted using the tombstone() functional operation when a map is tombstoned, a metadata property is internally set on the field and all the data within the map is removed this is done by iterating through all the fields in the map and calling tombstone on those fields for register or attachment data types within the map this will result in their values also being deleted dql update collection cars (properties map) set properties > tombstone() where id = '123' for more information and how to instructions, see docid\ e3uqqeqvzvotjls2xfdfl > docid\ gsusic4zsrjq 0h07ckn > docid\ gsusic4zsrjq 0h07ckn 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 being added across small peer devices, the result will be a map with all added fields because each field in a map has its own data type, the merge strategy for that field will depend on the data type of that field 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", } } comparison with register the nested json object, functioning as a register , closely resembles a nested map structure within a document however, their merge strategies and supported types for nested values differ significantly understanding these distinctions is crucial when selecting the appropriate data type for expressing your data structure for example, consider a scenario in which you have 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); however, if the properties field was of the map data type instead, to update just the color without altering the other nested key value pairs in the set, you would simply set 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 and modification (or insert ) occur at the same time across two peers, the result is dependent on the casual order of changes 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 caution is advised when handling a deeply embedded document or a very large document if you have a deeply embedded or large document object, consider using an attachment instead of a regular document when internet connection is limited or when using only bluetooth to sync across connected peers, the process of syncing documents that contain large amounts of data is slow for instance, when using only bluetooth low energy (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 being 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 all of your large dataset, use a series of smaller documents note that if a document exceeds 250 kb in size, a stdout warning prints, and any documents larger than 5 mb will not sync to other peers