Skip to content

The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.

3.8 KB
Raw Blame
---
title: "Attribute data models"
sidebarTitle: "Data models"
description: "Every field on ProductAttribute and ProductAttributeValue, with defaults, nullability, indexes, and relations."
---

The Product Attribute module owns 2 data models: `ProductAttribute` and `ProductAttributeValue`. Both are defined in `packages/core/src/modules/product-attribute/models` and resolved through `MercurModules.PRODUCT_ATTRIBUTE` (`"product_attribute"`). Like every Medusa data model, each also gets `created_at`, `updated_at`, and `deleted_at` timestamps.

## ProductAttribute

A typed attribute in the shared catalog, either global or scoped to one product. Id prefix `pattr`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | Primary key, prefixed `pattr` |
| `handle` | `string \| null` | Unique among non-deleted attributes when set. Derived from `name` on create for global attributes |
| `name` | `string` | Display name. Searchable. For an axis, also the title of its `ProductOption` |
| `description` | `string \| null` | Free-form description |
| `type` | `AttributeType` | One of `single_select`, `multi_select`, `unit`, `toggle`, `text`. Can’t change after create |
| `is_required` | `boolean` | Default `false`. The remove workflows refuse to detach a required attribute |
| `is_filterable` | `boolean` | Default `false`. Marks the attribute as a storefront facet |
| `is_variant_axis` | `boolean` | Default `false`. With `multi_select`, backs the attribute with a `ProductOption` |
| `rank` | `number` | Default `0`. Sort order |
| `is_active` | `boolean` | Default `true` |
| `created_by` | `string \| null` | Id of whoever created the attribute. The built-in routes leave it unset |
| `product_id` | `string \| null` | `null` for a global attribute, the product’s id for an inline one |
| `product_option_id` | `string \| null` | Id of the mirror `ProductOption` for an axis attribute |
| `metadata` | `Record<string, unknown> \| null` | Custom key-value data |

Relations and constraints:

- **`values`**: has many `ProductAttributeValue`, deleted with the attribute
- **`IDX_product_attribute_handle_unique`**: unique `handle` where `deleted_at IS NULL AND handle IS NOT NULL`
- **`IDX_product_attribute_type`**: index on `type`
- **`IDX_product_attribute_product_id`**: index on `product_id` where it’s not null

## ProductAttributeValue

One selectable value of an attribute, or the stored value of a `text`, `unit`, or `toggle` attribute on a product. Id prefix `pattrval`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | Primary key, prefixed `pattrval` |
| `attribute_id` | `string` | Id of the parent `ProductAttribute` |
| `handle` | `string \| null` | Unique per attribute when set. Derived from `name` on create for values of global select attributes |
| `name` | `string` | The value label, or the stored content for `text` and `unit` |
| `rank` | `number` | Default `0`. Sort order within the attribute |
| `is_active` | `boolean` | Default `true` |
| `product_option_value_id` | `string \| null` | Id of the mirror `ProductOptionValue` for an axis value |
| `metadata` | `Record<string, unknown> \| null` | Custom key-value data |

Relations and constraints:

- **`attribute`**: belongs to `ProductAttribute` through `attribute_id`
- **`IDX_product_attribute_value_handle_unique`**: unique `(attribute_id, handle)` where `deleted_at IS NULL AND handle IS NOT NULL`

## AttributeType enum

`AttributeType` is exported from `@mercurjs/types`:

| Member | Value |
| --- | --- |
| `SINGLE_SELECT` | `"single_select"` |
| `MULTI_SELECT` | `"multi_select"` |
| `UNIT` | `"unit"` |
| `TOGGLE` | `"toggle"` |
| `TEXT` | `"text"` |

<Note>
  Neither model stores which products hold a value. That lives in the `product_attribute_value_link` pivot table, described in [Links](/platform/attribute/reference/links).
</Note>