Help

Get Started
Product
Build
Tools
Reference
User Guide
Cloud

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#

Note: This property is only available after Medusa v2.1.2.

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

Tip: Use this property type when it's less important to have high precision for numbers with large decimal places. Alternatively, for higher precision, use the bigNumber property.

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.

Tip: Use this property type when it's important to have high precision for numbers with large decimal places. Alternatively, for less percision, use the float property.

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.

Was this chapter helpful?