Custom Column Value

A Custom Column Value is one computed-or-entered cell: the value of a Custom Column for a single record. It is joined to its target record by the record's public UUID (record_id) rather than a typed foreign key, which is what lets the same custom-column mechanism work across every records root. AI-computed values are written by the enrichment worker as structured JSON.

Naming	Value
Object	Custom Column Value
Resource type (JSON:API `type`)	`custom_column_value`
Collection / records root	— _{(not a records root)}
REST base	`/v1/custom-column-values`
Entity class	`CustomColumnValue`

Internal object. Not currently exposed on the public REST API. The operations below describe the intended contract.

API operations

Operation	Method & path	Status
List	`GET /v1/custom-column-values`	🟡 Planned
Retrieve	`GET /v1/custom-column-values/{id}`	🟡 Planned
Create	`POST /v1/custom-column-values`	🟡 Planned
Update	`PATCH /v1/custom-column-values/{id}`	🟡 Planned
Delete	`DELETE /v1/custom-column-values/{id}`	🟡 Planned

Data model

Attributes

Field	Type	Required	Constraints	Allowed values	Description
value_id	string, UUID, 🔒 system	✅ Yes	unique; gen_random_uuid()	—	Public identifier of the value row.
record_id	string (UUID)	✅ Yes	max 255 chars; indexed with custom_column	—	Public UUID of the target record (e.g. a company_id). NOT a typed FK — a root-agnostic join key, so one mechanism serves all roots.
root	string	✅ Yes	max 50 chars; denormalized	A records root	The records root of the target record (denormalized from the column for fast filtering).
value	jsonb	⚪ No	nullable	—	The cell value. AI stores structured output: { value: "high" } for text/select, { value: 42, currency: "EUR" } for amount.
created_at	ISO 8601, 🔒 system	—	onCreate hook	—	Creation timestamp.
updated_at	ISO 8601, 🔒 system	—	onCreate + onUpdate hooks; nullable	—	Last-update timestamp (recompute overwrites it).

Relationships

Name	Type	Required	Description
custom_column	to-one (custom_column)	✅ Yes	The column definition this value belongs to. deleteRule: cascade — deleting the column deletes its values.

System-computed

value_id generated by gen_random_uuid()
created_at via onCreate; updated_at via onCreate + onUpdate hooks
NO deleted_at — values are not soft-deleted; they cascade-delete with their custom_column (deleteRule: cascade)
Indexed on (custom_column, record_id)
record_id is the target record's PUBLIC UUID (root-agnostic join key) — no FK to the underlying entity table
value shape is written by the enrichment worker: { value } or { value, currency } for amount columns

Example

{
  "data": {
    "type": "custom_column_value",
    "id": "e4d5c6b7-1111-4111-8111-aaaabbbbcccc",
    "attributes": {
      "value_id": "e4d5c6b7-1111-4111-8111-aaaabbbbcccc",
      "root": "companies",
      "record_id": "3fa1c2d4-87ae-4b10-a9f3-ec5d1234abcd",
      "value": {
        "value": "high"
      },
      "created_at": "2026-05-20T09:15:30.000Z",
      "updated_at": "2026-05-28T11:03:00.000Z"
    }
  },
  "relationships": {
    "custom_column": {
      "data": {
        "type": "custom_column",
        "id": "7c1f9a02-4d3b-4e21-9a77-2f0c11aa33bc"
      }
    }
  }
}

_{Source: apps/api/src/database/entities/CustomColumnValue.ts · domain: records / data-views · tier: Infrastructure}