www/apps/book/app/learn/fundamentals/data-models/manage-relationships/page.mdx
export const metadata = {
title: ${pageNumber} Manage Relationships,
}
In this chapter, you'll learn how to manage relationships between data models when creating, updating, or retrieving records using the module's main service.
<Note>This chapter applies to data model relationships within the same module. To manage linked data models across modules, check out Links and Query.
</Note>When you create a record of a data model that belongs to another through a one-to-one relation, pass the ID of the other data model's record in the {relation}_id property, where {relation} is the name of the relation property.
For example, assuming you have the User and Email data models from the previous chapter, set an email's user ID as follows:
export const belongsHighlights = [ ["4", "user_id", "The ID of the user the email belongs to."], ["11", "user_id", "The ID of the user the email belongs to."] ]
// when creating an email
const email = await helloModuleService.createEmails({
// other properties...
user_id: "123",
})
// when updating an email
const email = await helloModuleService.updateEmails({
id: "321",
// other properties...
user_id: "123",
})
In the example above, you pass the user_id property when creating or updating an email to specify the user it belongs to.
When you create a record of a data model that has one of another, pass the ID of the other data model's record in the relation property.
For example, assuming you have the User and Email data models from the previous chapter, set a user's email ID as follows:
export const hasOneHighlights = [ ["4", "email", "The ID of the email that the user has."], ["11", "email", "The ID of the email that the user has."] ]
// when creating a user
const user = await helloModuleService.createUsers({
// other properties...
email: "123",
})
// when updating a user
const user = await helloModuleService.updateUsers({
id: "321",
// other properties...
email: "123",
})
In the example above, you pass the email property when creating or updating a user to specify the email it has.
In a one-to-many relationship, you can only manage the associations from the belongsTo side.
When you create a record of the data model on the belongsTo side, pass the ID of the other data model's record in the {relation}_id property, where {relation} is the name of the relation property.
For example, assuming you have the Product and Store data models from the previous chapter, set a product's store ID as follows:
export const manyBelongsHighlights = [ ["4", "store_id", "The ID of the store the product belongs to."], ["11", "store_id", "The ID of the store the product belongs to."] ]
// when creating a product
const product = await helloModuleService.createProducts({
// other properties...
store_id: "123",
})
// when updating a product
const product = await helloModuleService.updateProducts({
id: "321",
// other properties...
store_id: "123",
})
In the example above, you pass the store_id property when creating or updating a product to specify the store it belongs to.
If your many-to-many relation is represented with a pivotEntity, refer to this section instead.
</Note>When you create a record of a data model that has a many-to-many relationship to another data model, pass an array of IDs of the other data model's records in the relation property.
For example, assuming you have the Order and Product data models from the previous chapter, set the association between products and orders as follows:
export const manyHighlights = [ ["4", "orders", "The IDs of the orders associated with the product."], ["11", "products", "The IDs of the products associated with the order."] ]
// when creating a product
const product = await helloModuleService.createProducts({
// other properties...
orders: ["123", "321"],
})
// when creating an order
const order = await helloModuleService.createOrders({
id: "321",
// other properties...
products: ["123", "321"],
})
In the example above, you pass the orders property when you create a product, and you pass the products property when you create an order.
When you use the update methods generated by the service factory, you also pass an array of IDs as the relation property's value to add new associated records.
However, this removes any existing associations to records whose IDs aren't included in the array.
For example, assuming you have the Order and Product data models from the previous chapter, you update the product's related orders as so:
const product = await helloModuleService.updateProducts({
id: "123",
// other properties...
orders: ["321"],
})
If the product was associated with an order, and you don't include that order's ID in the orders array, the association between the product and order is removed.
So, to add a new association without removing existing ones, retrieve the product first to pass its associated orders when updating the product:
export const updateAssociationHighlights = [ ["1", "retrieveProduct", "Retrieve the product with its orders."], ["12", "", "Pass the IDs of the orders previously associated with the product."], ["13", "", "Associate the product with a new order."] ]
const product = await helloModuleService.retrieveProduct(
"123",
{
relations: ["orders"],
}
)
const updatedProduct = await helloModuleService.updateProducts({
id: product.id,
// other properties...
orders: [
...product.orders.map((order) => order.id),
"321",
],
})
This keeps existing associations between the product and orders, and adds a new one.
If your many-to-many relation is represented without a pivotEntity, refer to this section instead.
</Note>If you have a many-to-many relation with a pivotEntity specified, make sure to pass the data model representing the pivot table to MedusaService that your module's service extends.
For example, assuming you have the Order, Product, and OrderProduct models from the previous chapter, add OrderProduct to MedusaService's object parameter:
class BlogModuleService extends MedusaService({
Order,
Product,
OrderProduct,
}) {}
This will generate Create, Read, Update and Delete (CRUD) methods for the OrderProduct data model, which you can use to create relations between orders and products and manage the extra columns in the pivot table.
For example:
// create order-product association
const orderProduct = await blogModuleService.createOrderProducts({
order_id: "123",
product_id: "123",
metadata: {
test: true,
},
})
// update order-product association
const orderProduct = await blogModuleService.updateOrderProducts({
id: "123",
metadata: {
test: false,
},
})
// delete order-product association
await blogModuleService.deleteOrderProducts("123")
Since the OrderProduct data model belongs to the Order and Product data models, you can set its order and product as explained in the one-to-many relationship section using order_id and product_id.
Refer to the service factory reference for a full list of generated methods and their usages.
The list, listAndCount, and retrieve methods of a module's main service accept as a second parameter an object of options.
To retrieve the records associated with a data model's records through a relationship, pass in the second parameter object a relations property whose value is an array of relationship names.
For example, assuming you have the Order and Product data models from the previous chapter, you retrieve a product's orders as follows:
export const retrieveHighlights = [
["4", "orders", "Retrieve the records associated with the product\nthrough the orders relationship."]
]
const product = await blogModuleService.retrieveProducts(
"123",
{
relations: ["orders"],
}
)
In the example above, the retrieved product has an orders property, whose value is an array of orders associated with the product.