Relationships

there are several methods for linking related data items and organizing them for easy lookup field referencing another document by id embedded json object that acts as a register type or an embedded map overview the following table provides a complete overview of the different relationships you can form in ditto, as well as a brief description, list of possible approaches you can take, and links to related content relationship description approaches one to many associates a parent element with children elements to establish a hierarchy embed a json object ( register ) embed a map reference a field to a document reference a document to a collection many to many associates multiple entities in one collection with multiple entities in another collection embed a json object ( register ) embed a map create references between documents in different collections many to one associates two or more collections, where one collection refers to the primary key of another collection to create a meaningful relationship between the datasets embed a json object ( register ) embed a map create references between documents in different collections avoid using arrays in ditto due to potential merge conflicts when offline peers reconnect to the mesh and attempt to sync their updates, especially when multiple peers make concurrent updates to the same item within the array foreign key relationships to create a foreign key relationship , store the primary key to one document within another document a foreign key relationship establishes a link between two or more datasets for example, the following snippet demonstrates a foreign key relationship between documents in the cars and people collections, in which the reference to susanid serves as the foreign key establishing a relationship between cars and people pseudocode const results = await ditto store write(async (transaction) => { // create a person named susan in the "people" collection const cars = transaction scoped('cars') const people = transaction scoped('people') // create a car document in the "cars" collection const susanid = await people upsert({ name 'susan', }) await cars upsert({ make 'hyundai', color 'red', owner susanid, // set the owner field to susan's id }) // evict the susan document from the "people" collection await people findbyid(susanid) evict() }) key value relationships a key value relationship establishes a parent child hierarchy between embedded data elements in this hierarchy, the key functions as the parent, and its encapsulated values, represented as a set of key value pairs, serve as children when managing data that requires unique identifiers and relationships, instead of using an array to encode your data, use a map with unique string keys and object values instead if you need to represent a highly complex dataset in a document, you can embed a map data type within a document avoid using arrays in ditto due to potential merge conflicts when offline peers reconnect to the mesh and attempt to sync their updates, especially when multiple peers make concurrent updates to the same item within the array deeply hierarchical structures embedding a map is one way to structure and organize related data within a single document to create a complex structure with multiple levels of hierarchy as in, you can embed a map within a map , within another map , and so on for an example demonstrating both the deeply embedded and flat models, see docid\ vk4cuqumawqfv0heyatit for example, the following snippet shows three levels of embedded maps details , engine , interior , and features { " id" { "vin" "123abc", "make" "toyota", "model" "corolla", "year" 2022, }, "details" { "engine" { "type" "gasoline", "displacement" "1 8l" }, "interior" { "seats" 5, "color" "black" }, "features" { "safety" { "airbags" 6, "antilockbrakes" true }, "technology" { "infotainment" "touchscreen", "navigation" true } } } } each level contains its key value pairs and, if used, children level map you can represent key values using a register , attachment , or another map benefits of embedding maps embedding a map is beneficial in scenarios where you need to manage a collection of items and continuously modify that collection over time; that is you want to link multiple data items with a single unique string identifier, but you anticipate that these data items are subject to concurrent edits over time as an example, the following snippet demonstrates a basic point of sale (pos) system where you need to keep track of the customer orders collection and, since multiple users can add and remove orders within the collection, you embed a map to represent the ordered items, where each key denotes an item id and the linked value indicates the quantity ordered pseudocode const order = { customername 'john doe', orderdate '2023 08 15', items { 'item123' 2, // item id quantity ordered 'item456' 5, 'item789' 1 } }; // inserting the order into the ditto collection await ditto store execute(` update into orders documents (\ order)`, { order });