Skip to main content

Entities

In this document, you'll learn what Entities are in Medusa.

What are Entities​

Entities in medusa represent tables in the database as classes. An example of this would be the OrderCopy to Clipboard entity which represents the orderCopy to Clipboard table in the database. Entities provide a uniform way of defining and interacting with data retrieved from the database.

Aside from the entities in the Medusa core package, you can also create your own entities to use in your Medusa backend. Custom entities are TypeScript or JavaScript files located in the src/modelsCopy to Clipboard directory of your Medusa backend. These entities are then transpiled to the dist/modelsCopy to Clipboard directory to be used during the backend's runtime.

Entities are TypeScript files and they are based on Typeorm’s Entities and use Typeorm decorators.

Base Entities​

All entities must extend either the BaseEntityCopy to Clipboard or SoftDeletableEntityCopy to Clipboard classes. The BaseEntityCopy to Clipboard class holds common columns including the idCopy to Clipboard, created_atCopy to Clipboard, and updated_atCopy to Clipboard columns.

The SoftDeletableEntityCopy to Clipboard class extends the BaseEntityCopy to Clipboard class and adds another column deleted_atCopy to Clipboard. If an entity can be soft deleted, meaning that a row in it can appear to the user as deleted but still be available in the database, it should extend SoftDeletableEntityCopy to Clipboard.

metadata Attribute​

Most entities in Medusa have a metadataCopy to Clipboard attribute. This attribute is an object that can be used to store custom data related to that entity. In the database, this attribute is stored as a JSON Binary (JSONB) column. On retrieval, the attribute is parsed into an object.

Some example use cases for the metadataCopy to Clipboard attribute include:

  • Store an external ID of an entity related to a third-party integartion.
  • Store product customization such as personalization options.

Add and Update Metadata​

You can add or update metadata entities either through the REST APIs or through create and update methods in the entity's respective service.

In the admin REST APIs, you'll find that in create or update requests of some entities you can also set the metadataCopy to Clipboard.

In services, there are typically createCopy to Clipboard or updateCopy to Clipboard methods that allow you to set or update the metadata.

If you want to add a property to the metadataCopy to Clipboard object or update a property in the metadataCopy to Clipboard object, you can pass the metadataCopy to Clipboard object with the properties you want to add or update in it. For example:

{
  // other data
  "metadata": {
    "is_b2b": true
  }
}
Report Incorrect CodeCopy to Clipboard

If you want to remove a property from the metadataCopy to Clipboard object, you can pass the metadataCopy to Clipboard object with the property you want to delete. The property should have an empty string value. For example:

{
  // other data
  "metadata": {
    "is_b2b": "" // this deletes the `is_b2b` property from `metadata`
  }
}
Report Incorrect CodeCopy to Clipboard

Custom Development​

Developers can create custom entities in the Medusa backend, a plugin, or in a Commerce Module, then ensure it reflects in the database using a migration.