From 826004b82f70ab402f7eebeb1c03e620601e8b7e Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Mon, 3 Feb 2025 10:59:06 +0200 Subject: [PATCH] docs: document onesided one-to-one relationship (#11270) --- .../data-models/relationships/page.mdx | 47 ++++++++++++++----- www/apps/book/generated/edit-dates.mjs | 2 +- 2 files changed, 37 insertions(+), 12 deletions(-) diff --git a/www/apps/book/app/learn/fundamentals/data-models/relationships/page.mdx b/www/apps/book/app/learn/fundamentals/data-models/relationships/page.mdx index c154bd812c..b3e4eca729 100644 --- a/www/apps/book/app/learn/fundamentals/data-models/relationships/page.mdx +++ b/www/apps/book/app/learn/fundamentals/data-models/relationships/page.mdx @@ -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. -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). -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. @@ -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. diff --git a/www/apps/book/generated/edit-dates.mjs b/www/apps/book/generated/edit-dates.mjs index fde77bd707..fccc038bb3 100644 --- a/www/apps/book/generated/edit-dates.mjs +++ b/www/apps/book/generated/edit-dates.mjs @@ -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",