203 lines
7.0 KiB
Plaintext
203 lines
7.0 KiB
Plaintext
import { BetaBadge } from "docs-ui"
|
|
|
|
export const metadata = {
|
|
title: `${pageNumber} Manage Relationships`,
|
|
}
|
|
|
|
# {metadata.title} <BetaBadge tooltipText="Data model relationships are in active development and may change." text="Beta" />
|
|
|
|
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](../relationships/page.mdx#one-to-one-relationship), set an email's user ID as follows:
|
|
|
|
export const belongsHighlights = [
|
|
["4", "user", "The ID of the user the email belongs to."],
|
|
["11", "user", "The ID of the user the email belongs to."]
|
|
]
|
|
|
|
```ts highlights={belongsHighlights}
|
|
// when creating an email
|
|
const email = await helloModuleService.createEmails({
|
|
// other properties...
|
|
user: "123",
|
|
})
|
|
|
|
// when updating an email
|
|
const email = await helloModuleService.updateEmails({
|
|
id: "321",
|
|
// other properties...
|
|
user: "123",
|
|
})
|
|
```
|
|
|
|
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](../relationships/page.mdx#one-to-one-relationship), set an 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."]
|
|
]
|
|
|
|
```ts highlights={hasOneHighlights}
|
|
// 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.
|
|
|
|
---
|
|
|
|
## 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](../relationships/page.mdx#one-to-many-relationship), 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."]
|
|
]
|
|
|
|
```ts highlights={manyBelongsHighlights}
|
|
// 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.
|
|
|
|
---
|
|
|
|
## 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](../relationships/page.mdx#many-to-many-relationship), 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."]
|
|
]
|
|
|
|
```ts highlights={manyHighlights}
|
|
// 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.
|
|
|
|
### 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](../relationships/page.mdx#many-to-many-relationship), you update the product's related orders as so:
|
|
|
|
```ts
|
|
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."]
|
|
]
|
|
|
|
```ts highlights={updateAssociationHighlights}
|
|
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.
|
|
|
|
---
|
|
|
|
## 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](../relationships/page.mdx#many-to-many-relationship), you retrieve a product's orders as follows:
|
|
|
|
export const retrieveHighlights = [
|
|
["4", `"orders"`, "Retrieve the records associated with the product\nthrough the `orders` relationship."]
|
|
]
|
|
|
|
```ts highlights={retrieveHighlights}
|
|
const product = await helloModuleService.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.
|