docs: document onesided one-to-one relationship (#11270)
This commit is contained in:
Shahed Nasser
GitHub
@@ -32,7 +32,7 @@ A one-to-one relationship indicates that one record of a data model belongs to o
|
||||
|
||||
To define a one-to-one relationship, create relationship properties in the data models using the following methods:
|
||||
|
||||
1. `hasOne`: indicates that the model has one records of the specified model.
|
||||
1. `hasOne`: indicates that the model has one record of the specified model.
|
||||
2. `belongsTo`: indicates that the model belongs to one record of the specified model.
|
||||
|
||||
For example:
|
||||
@@ -61,13 +61,38 @@ const Email = model.define("email", {
|
||||
|
||||
In the example above, a user has one email, and an email belongs to one user.
|
||||
|
||||
The `hasOne` and `belongsTo` methods accept a function as a first parameter. The function returns the associated data model.
|
||||
The `hasOne` and `belongsTo` methods accept a function as the first parameter. The function returns the associated data model.
|
||||
|
||||
The `belongsTo` method also requires passing as a second parameter an object with the property `mappedBy`. Its value is the name of the relationship property in the other data model.
|
||||
|
||||
### Optional Relationship
|
||||
|
||||
To make the relationship optional on the `hasOne` or `belongsTo` side, use the `nullable` method on either properties as explained in [this chapter](../configure-properties/page.mdx#nullable-property).
|
||||
To make the relationship optional on the `hasOne` or `belongsTo` side, use the `nullable` method on either property as explained in [this chapter](../configure-properties/page.mdx#nullable-property).
|
||||
|
||||
### One-sided One-to-One Relationship
|
||||
|
||||
If the one-to-one relationship is only defined on one side, pass `undefined` to the `mappedBy` property in the `belongsTo` method.
|
||||
|
||||
For example:
|
||||
|
||||
export const oneToOneUndefinedHighlights = [
|
||||
["10", "undefined", "Pass `undefined` since the relationship is only defined on the `Email` data model."]
|
||||
]
|
||||
|
||||
```ts highlights={oneToOneUndefinedHighlights}
|
||||
import { model } from "@medusajs/framework/utils"
|
||||
|
||||
const User = model.define("user", {
|
||||
id: model.id().primaryKey(),
|
||||
})
|
||||
|
||||
const Email = model.define("email", {
|
||||
id: model.id().primaryKey(),
|
||||
user: model.belongsTo(() => User, {
|
||||
mappedBy: undefined,
|
||||
}),
|
||||
})
|
||||
```
|
||||
|
||||
### One-to-One Relationship in the Database
|
||||
|
||||
@@ -86,13 +111,13 @@ A one-to-many relationship indicates that one record of a data model has many re
|
||||
|
||||
To define a one-to-many relationship, create relationship properties in the data models using the following methods:
|
||||
|
||||
1. `hasMany`: indicates that the model has more than one records of the specified model.
|
||||
1. `hasMany`: indicates that the model has more than one record of the specified model.
|
||||
2. `belongsTo`: indicates that the model belongs to one record of the specified model.
|
||||
|
||||
For example:
|
||||
|
||||
export const oneToManyHighlights = [
|
||||
["5", "hasMany", "A store has many products"],
|
||||
["5", "hasMany", "A store has many products."],
|
||||
["10", "belongsTo", "A product has one store."],
|
||||
["11", `"products"`, "The relationship's name in the `Store` data model."]
|
||||
]
|
||||
@@ -132,7 +157,7 @@ When you generate the migrations of data models that have a one-to-many relation
|
||||
|
||||
## Many-to-Many Relationship
|
||||
|
||||
A many-to-many relationship indicates that many records of a data model can be associated to many records of another data model.
|
||||
A many-to-many relationship indicates that many records of a data model can be associated with many records of another data model.
|
||||
|
||||
To define a many-to-many relationship, create relationship properties in the data models using the `manyToMany` method.
|
||||
|
||||
@@ -169,19 +194,19 @@ The `manyToMany` method accepts two parameters:
|
||||
1. A function that returns the associated data model.
|
||||
2. An object of optional configuration. Only one of the data models in the relation can define the `pivotTable`, `joinColumn`, and `inverseJoinColumn` configurations, and it's considered the owner data model. The object can accept the following properties:
|
||||
- `mappedBy`: The name of the relationship property in the other data model. If not set, the property's name is inferred from the associated data model's name.
|
||||
- `pivotTable`: The name of the pivot table created in the database for the many-to-many relation. If not set, the pivot table is inferred by combining the names of the data models' tables in alphabetical order, seperating them by `_`, and pluralizing the last name. For example, `order_products`.
|
||||
- `pivotTable`: The name of the pivot table created in the database for the many-to-many relation. If not set, the pivot table is inferred by combining the names of the data models' tables in alphabetical order, separating them by `_`, and pluralizing the last name. For example, `order_products`.
|
||||
- `joinColumn`: The name of the column in the pivot table that points to the owner model's primary key.
|
||||
- `inverseJoinColumn`: The name of the column in the pivot table that points to the owned model's primary key.
|
||||
|
||||
<Note>
|
||||
|
||||
The `pivotTable`, `joinColumn`, and `inverseJoinColumn` property are only available after [Medusa v2.0.7](https://github.com/medusajs/medusa/releases/tag/v2.0.7).
|
||||
The `pivotTable`, `joinColumn`, and `inverseJoinColumn` properties are only available after [Medusa v2.0.7](https://github.com/medusajs/medusa/releases/tag/v2.0.7).
|
||||
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
|
||||
Following [Medusa v2.1.0](https://github.com/medusajs/medusa/releases/tag/v2.1.0), if `pivotTable`, `joinColumn`, and `inverseJoinColumn` aren't specified on either models, the owner is decided based on alphabetical order. So, in the example above, the `Order` data model would be the owner.
|
||||
Following [Medusa v2.1.0](https://github.com/medusajs/medusa/releases/tag/v2.1.0), if `pivotTable`, `joinColumn`, and `inverseJoinColumn` aren't specified on either model, the owner is decided based on alphabetical order. So, in the example above, the `Order` data model would be the owner.
|
||||
|
||||
</Note>
|
||||
|
||||
@@ -189,7 +214,7 @@ In this example, an order is associated with many products, and a product is ass
|
||||
|
||||
### Many-to-Many Relationship in the Database
|
||||
|
||||
When you generate the migrations of data models that have a many-to-many relationship, the migration adds a new pivot table. Its name is either the name you specify in the `pivotTable` configuration, or the inferred name combining the names of the data models' tables in alphabetical order, seperating them by `_`, and pluralizing the last name. For example, `order_products`.
|
||||
When you generate the migrations of data models that have a many-to-many relationship, the migration adds a new pivot table. Its name is either the name you specify in the `pivotTable` configuration or the inferred name combining the names of the data models' tables in alphabetical order, separating them by `_`, and pluralizing the last name. For example, `order_products`.
|
||||
|
||||
The pivot table has a column with the name `{data_model}_id` for each of the data model's tables. It also has foreign keys on each of these columns to their respective tables.
|
||||
|
||||
@@ -257,7 +282,7 @@ The `OrderProduct` model defines, aside from the ID, the following properties:
|
||||
|
||||
The relationship property methods accept as a second parameter an object of options. The `mappedBy` property defines the name of the relationship in the other data model.
|
||||
|
||||
This is useful if the relationship property’s name is different than that of the associated data model.
|
||||
This is useful if the relationship property’s name is different from that of the associated data model.
|
||||
|
||||
As seen in previous examples, the `mappedBy` option is required for the `belongsTo` method.
|
||||
|
||||
|
||||
@@ -41,7 +41,7 @@ export const generatedEditDates = {
|
||||
"app/learn/fundamentals/data-models/manage-relationships/page.mdx": "2024-12-12T14:23:26.254Z",
|
||||
"app/learn/fundamentals/modules/remote-query/page.mdx": "2024-07-21T21:20:24+02:00",
|
||||
"app/learn/fundamentals/modules/options/page.mdx": "2025-01-16T09:21:38.244Z",
|
||||
"app/learn/fundamentals/data-models/relationships/page.mdx": "2024-12-12T14:08:50.686Z",
|
||||
"app/learn/fundamentals/data-models/relationships/page.mdx": "2025-02-03T08:01:18.094Z",
|
||||
"app/learn/fundamentals/workflows/compensation-function/page.mdx": "2024-12-06T14:34:50.384Z",
|
||||
"app/learn/fundamentals/modules/service-factory/page.mdx": "2024-10-21T13:30:21.371Z",
|
||||
"app/learn/fundamentals/data-models/primary-key/page.mdx": "2024-10-21T13:30:21.368Z",
|
||||
|
||||
Reference in New Issue
Block a user