3.5.2. Data Model Properties

In this chapter, you'll learn about the different property types you can use in a data model and how to configure a data model's properties.

Data Model's Default Properties#

By default, Medusa creates the following properties for every data model:

• created_at: A dateTime property that stores when a record of the data model was created.
• updated_at: A dateTime property that stores when a record of the data model was updated.
• deleted_at: A dateTime property that stores when a record of the data model was deleted. When you soft-delete a record, Medusa sets the deleted_at property to the current date.

Property Types#

This section covers the different property types you can define in a data model's schema using the model methods.

id#

The id method defines an automatically generated string ID property. The generated ID is a unique string that has a mix of letters and numbers.

For example:

Code
1import { model } from "@medusajs/framework/utils"2
3const Post = model.define("post", {4  id: model.id(),5  // ...6})7
8export default Post

text#

The text method defines a string property.

For example:

Code
1import { model } from "@medusajs/framework/utils"2
3const Post = model.define("post", {4  name: model.text(),5  // ...6})7
8export default Post

Limit Text Length

To limit the allowed length of a text property, use the checks method.

For example, to limit the name property to a maximum of 50 characters:

Code
1import { model } from "@medusajs/framework/utils"2
3const Post = model.define("post", {4  name: model.text(),5  // ...6})7.checks([8  {9    name: "limit_name_length",10    expression: (columns) => `LENGTH(${columns.name}) <= 50`,11  },12])13
14export default Post

This will add a database check constraint that ensures the name property of a record does not exceed 50 characters. If a record with a longer name is attempted to be inserted, an error will be thrown.

number#

The number method defines a number property.

For example:

Code
1import { model } from "@medusajs/framework/utils"2
3const Post = model.define("post", {4  age: model.number(),5  // ...6})7
8export default Post

float#

The float method defines a number property that allows for values with decimal places.

For example:

Code
1import { model } from "@medusajs/framework/utils"2
3const Post = model.define("post", {4  rating: model.float(),5  // ...6})7
8export default Post

bigNumber#

The bigNumber method defines a number property that expects large numbers, such as prices.

For example:

Code
1import { model } from "@medusajs/framework/utils"2
3const Post = model.define("post", {4  price: model.bigNumber(),5  // ...6})7
8export default Post

boolean#

The boolean method defines a boolean property.

For example:

Code
1import { model } from "@medusajs/framework/utils"2
3const Post = model.define("post", {4  hasAccount: model.boolean(),5  // ...6})7
8export default Post

enum#

The enum method defines a property whose value can only be one of the specified values.

For example:

Code
1import { model } from "@medusajs/framework/utils"2
3const Post = model.define("post", {4  color: model.enum(["black", "white"]),5  // ...6})7
8export default Post

The enum method accepts an array of possible string values.

dateTime#

The dateTime method defines a timestamp property.

For example:

Code
1import { model } from "@medusajs/framework/utils"2
3const Post = model.define("post", {4  date_of_birth: model.dateTime(),5  // ...6})7
8export default Post

json#

The json method defines a property whose value is stored as a stringified JSON object in the database.

For example:

Code
1import { model } from "@medusajs/framework/utils"2
3const Post = model.define("post", {4  metadata: model.json(),5  // ...6})7
8export default Post

Learn more in the JSON Properties chapter.

array#

The array method defines an array of strings property.

For example:

Code
1import { model } from "@medusajs/framework/utils"2
3const Post = model.define("post", {4  names: model.array(),5  // ...6})7
8export default Post

Properties Reference#

Refer to the Data Model Language (DML) reference for a full reference of the properties.

Set Primary Key Property#

To set any id, text, or number property as a primary key, use the primaryKey method.

For example:

Code
1import { model } from "@medusajs/framework/utils"2
3const Post = model.define("post", {4  id: model.id().primaryKey(),5  // ...6})7
8export default Post

In the example above, the id property is defined as the data model's primary key.

Property Default Value#

Use the default method on a property's definition to specify the default value of a property.

For example:

Code
1import { model } from "@medusajs/framework/utils"2
3const Post = model.define("post", {4  color: model5    .enum(["black", "white"])6    .default("black"),7  age: model8    .number()9    .default(0),10  // ...11})12
13export default Post

In this example, you set the default value of the color enum property to black, and that of the age number property to 0.

Make Property Optional#

Use the nullable method to indicate that a property’s value can be null. This is useful when you want a property to be optional.

For example:

Code
1import { model } from "@medusajs/framework/utils"2
3const Post = model.define("post", {4  price: model.bigNumber().nullable(),5  // ...6})7
8export default Post

In the example above, the price property is configured to allow null values, making it optional.

Unique Property#

The unique method indicates that a property’s value must be unique in the database through a unique index.

For example:

Code
1import { model } from "@medusajs/framework/utils"2
3const User = model.define("user", {4  email: model.text().unique(),5  // ...6})7
8export default User

In this example, multiple users can’t have the same email.

Define Database Index on Property#

Use the index method on a property's definition to define a database index.

For example:

Code
1import { model } from "@medusajs/framework/utils"2
3const Post = model.define("post", {4  id: model.id().primaryKey(),5  name: model.text().index(6    "IDX_MY_CUSTOM_NAME"7  ),8})9
10export default Post

The index method optionally accepts the name of the index as a parameter.

In this example, you define an index on the name property.

Define a Searchable Property#

Methods generated by the service factory that accept filters, such as list{ModelName}s, accept a q property as part of the filters.

When the q filter is passed, the data model's searchable properties are queried to find matching records.

Use the searchable method on a text property to indicate that it's searchable.

For example:

Code
1import { model } from "@medusajs/framework/utils"2
3const Post = model.define("post", {4  title: model.text().searchable(),5  // ...6})7
8export default Post

In this example, the title property is searchable.

Search Example#

If you pass a q filter to the listPosts method:

Code
1const posts = await blogModuleService.listPosts({2  q: "New Products",3})

This retrieves records that include New Products in their title property.

Make Property Translatable#

Use the translatable method on a text property to indicate that the property can have different values per locale. This only works if the Translation Module is configured in your application.

When a property is marked as translatable, merchants can manage translations for these fields through the Medusa Admin.

For example:

Code
1import { model } from "@medusajs/framework/utils"2
3const Post = model.define("post", {4  title: model.text().translatable(),5  description: model.text().translatable(),6  // ...7})8
9export default Post

In this example, the title and description properties are translatable. So, admin users can translate the values of these properties into different locales.

Learn more in the Translate Custom Data Models guide.