docs: document many-to-many with extra columns (#10586)

2024-12-12 17:32:49 +02:00
parent 7f669b8c5f
commit bbed7af027
3 changed files with 111 additions and 2 deletions
@@ -100,6 +100,12 @@ In the example above, you pass the `store_id` property when creating or updating

 ## Manage Many-to-Many Relationship

+<Note>
+
+If your many-to-many relation is represented with a [pivotEntity](../relationships/page.mdx#many-to-many-with-custom-columns), refer to [this section](#manage-many-to-many-relationship-with-pivotentity) instead.
+
+</Note>
+
 ### 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.
@@ -176,6 +182,58 @@ This keeps existing associations between the product and orders, and adds a new

 ---

+## Manage Many-to-Many Relationship with pivotEntity
+
+<Note>
+
+If your many-to-many relation is represented without a [pivotEntity](../relationships/page.mdx#many-to-many-with-custom-columns), refer to [this section](#manage-many-to-many-relationship) 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](../../modules/service-factory/page.mdx) that your module's service extends.
+
+For example, assuming you have the [Order, Product, and OrderProduct models from the previous chapter](../relationships/page.mdx#many-to-many-with-custom-columns), add `OrderProduct` to `MedusaService`'s object parameter:
+
+```ts highlights={["4"]}
+class HelloModuleService 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:
+
+```ts
+// create order-product association
+const orderProduct = await helloModuleService.createOrderProducts({
+  order_id: "123",
+  product_id: "123",
+  metadata: {
+    test: true
+  }
+})
+
+// update order-product association
+const orderProduct = await helloModuleService.updateOrderProducts({
+  id: "123",
+  metadata: {
+    test: false
+  }
+})
+
+// delete order-product association
+await 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](#manage-one-to-many-relationship) using `order_id` and `product_id`.
+
+Refer to the [service factory reference](!resources!/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.