---
title: Relationships
slug: v4-5/document-model/complex-structures/relationships
docTags: 
createdAt: 2023-10-05T13:25:28.790Z
---

There are several methods for linking related data items and organizing them for easy lookup:

- Field referencing another document by `_id`. (See [Foreign-Key Relationships](./#foreign-key-relationships)) 
- Embedded JSON object that acts as a `REGISTER` type or an embedded `MAP`. (See [Key-Value Relationships](./#key-value-relationships))

:::hint{type="info"}
For an example demonstrating both the deeply embedded and flat models, see [Complex Structures](docId\:GrJc1h2C70DADHHtpDhyS).
:::

# 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                       |

# Foreign-Key Relationships

To create a *foreign-key relationship*, store the primary key to one document in 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`:

:::CodeblockTabs
pseudocode

```javascript
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.