3.3.4. Add Columns to a Link Table

In this chapter, you'll learn how to add custom columns to a link definition's table and manage them.

Link Table's Default Columns#

When you define a link between two data models, Medusa creates a link table in the database to store the IDs of the linked records. You can learn more about the created table in the Module Links chapter.

In various cases, you might need to store additional data in the link table. For example, if you define a link between a product and a post, you might want to store the publish date of the product's post in the link table.

In those cases, you can add a custom column to a link's table in the link definition. You can later set that column whenever you create or update a link between the linked records.

How to Add Custom Columns to a Link's Table?#

The defineLink function used to define a link accepts a third parameter, which is an object of options.

To add custom columns to a link's table, pass in the third parameter of defineLink a database property:

Code
1import BlogModule from "../modules/blog"2import ProductModule from "@medusajs/medusa/product"3import { defineLink } from "@medusajs/framework/utils"4
5export default defineLink(6  ProductModule.linkable.product,7  BlogModule.linkable.blog,8  {9    database: {10      extraColumns: {11        metadata: {12          type: "json",13        },14      },15    },16  }17)

This adds to the table created for the link between product and blog a metadata column of type json.

Database Options#

The database property defines configuration for the table created in the database.

Its extraColumns property defines custom columns to create in the link's table.

extraColumns's value is an object whose keys are the names of the columns, and values are the column's configurations as an object.

Column Configurations#

The column's configurations object accepts the following properties:

• type: The column's type. Possible values are:
  • string
  • text
  • integer
  • boolean
  • date
  • time
  • datetime
  • enum
  • json
  • array
  • enumArray
  • float
  • double
  • decimal
  • bigint
  • mediumint
  • smallint
  • tinyint
  • blob
  • uuid
  • uint8array
• defaultValue: The column's default value.
• nullable: Whether the column can have null values.

Set Custom Column when Creating Link#

The object you pass to Link's create method accepts a data property. Its value is an object whose keys are custom column names, and values are the value of the custom column for this link.

For example:

Code
1await link.create({2  [Modules.PRODUCT]: {3    product_id: "123",4  },5  [BLOG_MODULE]: {6    post_id: "321",7  },8  data: {9    metadata: {10      test: true,11    },12  },13})

Retrieve Custom Column with Link#

To retrieve linked records with their custom columns, use Query. A module link's definition, exported by a file under src/links, has a special entryPoint property. Use this property when specifying the entity property in Query's graph method.

For example:

Code
1import productPostLink from "../links/product-post"2
3// ...4
5const { data } = await query.graph({6  entity: productPostLink.entryPoint,7  fields: ["metadata", "product.*", "post.*"],8  filters: {9    product_id: "prod_123",10  },11})

This retrieves the product of id prod_123 and its linked post records.

In the fields array you pass metadata, which is the custom column to retrieve of the link.

Update Custom Column's Value#

Link's create method updates a link's data if the link between the specified records already exists.

So, to update the value of a custom column in a created link, use the create method again passing it a new value for the custom column.

For example:

Code
1await link.create({2  [Modules.PRODUCT]: {3    product_id: "123",4  },5  [BLOG_MODULE]: {6    post_id: "321",7  },8  data: {9    metadata: {10      test: false,11    },12  },13})