3.4.7. 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.

Manage One-to-One Relationship#

BelongsTo Side of One-to-One#

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 property.

For example, assuming you have the User and Email data models from the previous chapter, set an email's user ID as follows:

Code
1// when creating an email2const email = await helloModuleService.createEmails({3  // other properties...4  user: "123",5})6
7// when updating an email8const email = await helloModuleService.updateEmails({9  id: "321",10  // other properties...11  user: "123",12})

In the example above, you pass the user property when creating or updating an email to specify the user it belongs to.

HasOne Side#

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:

Code
1// when creating a user2const user = await helloModuleService.createUsers({3  // other properties...4  email: "123",5})6
7// when updating a user8const user = await helloModuleService.updateUsers({9  id: "321",10  // other properties...11  email: "123",12})

In the example above, you pass the email property when creating or updating a user to specify the email it has.

Manage One-to-Many Relationship#

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:

Code
1// when creating a product2const product = await helloModuleService.createProducts({3  // other properties...4  store_id: "123",5})6
7// when updating a product8const product = await helloModuleService.updateProducts({9  id: "321",10  // other properties...11  store_id: "123",12})

In the example above, you pass the store_id property when creating or updating a product to specify the store it belongs to.

Manage Many-to-Many Relationship#

Create Associations#

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:

Code
1// when creating a product2const product = await helloModuleService.createProducts({3  // other properties...4  orders: ["123", "321"],5})6
7// when creating an order8const order = await helloModuleService.createOrders({9  id: "321",10  // other properties...11  products: ["123", "321"],12})

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.

Update Associations#

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:

Code
1const product = await helloModuleService.updateProducts({2  id: "123",3  // other properties...4  orders: ["321"],5})

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:

Code
1const product = await helloModuleService.retrieveProduct(2  "123",3  {4    relations: ["orders"],5  }6)7
8const updatedProduct = await helloModuleService.updateProducts({9  id: product.id,10  // other properties...11  orders: [12    ...product.orders.map((order) => order.id),13    "321",14  ],15})

This keeps existing associations between the product and orders, and adds a new one.

Manage Many-to-Many Relationship with pivotEntity#

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:

Code
1class HelloModuleService extends MedusaService({2  Order,3  Product,4  OrderProduct5}) {}

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:

Code
1// create order-product association2const orderProduct = await helloModuleService.createOrderProducts({3  order_id: "123",4  product_id: "123",5  metadata: {6    test: true7  }8})9
10// update order-product association11const orderProduct = await helloModuleService.updateOrderProducts({12  id: "123",13  metadata: {14    test: false15  }16})17
18// delete order-product association19await helloModuleService.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.

Retrieve Records of Relation#

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:

Code
1const product = await helloModuleService.retrieveProducts(2  "123",3  {4    relations: ["orders"],5  }6)

In the example above, the retrieved product has an orders property, whose value is an array of orders associated with the product.