4.4.4. Add Columns to a Link

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

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 HelloModule from "../modules/hello"2import ProductModule from "@medusajs/medusa/product"3import { defineLink } from "@medusajs/framework/utils"4
5export default defineLink(6  ProductModule.linkable.product,7  HelloModule.linkable.myCustom,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 myCustom 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 the remote 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 remoteLink.create({2  [Modules.PRODUCT]: {3    product_id: "123",4  },5  HELLO_MODULE: {6    my_custom_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 productHelloLink from "../links/product-hello"2
3// ...4
5const { data } = await query.graph({6  entity: productHelloLink.entryPoint,7  fields: ["metadata", "product.*", "my_custom.*"],8  filters: {9    product_id: "prod_123",10  },11})

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

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

Update Custom Column's Value#

The remote 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 remoteLink.create({2  [Modules.PRODUCT]: {3    product_id: "123",4  },5  HELLO_MODULE: {6    my_custom_id: "321",7  },8  data: {9    metadata: {10      test: false,11    },12  },13})