Custom Column

A Custom Column is a per-workspace, per-root virtual column a user adds to a records table (e.g. a ‘Risk level’ column on companies). It holds the column definition only — name, type, position, and the AI/formula/format config — while the computed cell values live in custom_column_values. Custom columns are workspace-scoped and namespaced by records root; they are NOT Hasura columns and NOT governed DATA_VIEW_ROOTS, so they sit behind the records table as an overlay rather than as a queryable entity of their own.

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

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-columns`	🟡 Planned
Retrieve	`GET /v1/custom-columns/{id}`	🟡 Planned
Create	`POST /v1/custom-columns`	🟡 Planned
Update	`PATCH /v1/custom-columns/{id}`	🟡 Planned
Delete	`DELETE /v1/custom-columns/{id}`	🟡 Planned

Data model

Attributes

Field	Type	Required	Constraints	Allowed values	Description
custom_column_id	string, UUID, 🔒 system	✅ Yes	unique; gen_random_uuid()	—	Public identifier of the column definition. Internal pk is never exposed.
root	string	✅ Yes	max 50 chars; part of partial-unique key	A records root (companies, invoices, transactions, …)	The data-view root this column is attached to. Scopes the column to one records table.
name	string	✅ Yes	max 255 chars	—	Human-readable column header shown in the records table.
field_key	string	✅ Yes	max 100 chars; part of partial-unique key; slugified from name	—	Stable machine key for the column, slugified from name at creation. Unique per (workspace, root).
type	string (CustomColumnTypeEnum)	✅ Yes	native enum custom_column_type_enum; default ‘text’	text, number, amount, single_select, multi_select, ai	Column data type. ‘ai’ (and rules_config-bearing columns) are auto-computed; others may be manually entered.
position	number (int)	⚪ No	default 0	—	Display order of the column within the records table.
icon	string	⚪ No	max 100 chars; nullable	—	Optional icon identifier rendered in the column header.
rules_config	jsonb	⚪ No	nullable	—	AI compute rules. When set, the column is auto-computed by the enrichment pipeline (Anthropic Haiku) for every record.
formula_config	jsonb	⚪ No	nullable	—	Formula configuration for computed (non-AI) columns.
format_config	jsonb	⚪ No	nullable	—	Display/format configuration (e.g. select options, number format).
created_at	ISO 8601, 🔒 system	—	onCreate hook	—	Creation timestamp.
updated_at	ISO 8601, 🔒 system	—	onCreate + onUpdate hooks	—	Last-update timestamp.
deleted_at	ISO 8601, 🔒 system	—	nullable; soft delete	—	Soft-delete tombstone; null when active.

Relationships

Name	Type	Required	Description
workspace	to-one (workspace)	✅ Yes	Owning workspace — the per-workspace scope of the column.
values	to-many (custom_column_value)	⚪ No	Computed/entered cell values for this column, one per record (cascade-deleted with the column).

System-computed

custom_column_id generated by gen_random_uuid()
field_key slugified from name at creation (slugifyFieldKey)
Partial unique index on (workspace_pk, root, field_key) WHERE deleted_at IS NULL — managed in a raw-SQL migration, not @Index (MikroORM cannot express partial indexes)
type defaults to ‘text’; position defaults to 0
created_at via onCreate; updated_at via onCreate + onUpdate hooks
Soft-delete via deleted_at
On create: autoProvisionPresets(workspace, root) may seed preset AI columns; fire-and-forget recompute over existing records
On rules_config / formula_config / format_config change: enqueueRecompute → recompute all records for the column
AI columns (type=‘ai’ or rules_config present) compute via EnrichmentTask (CUSTOM_COLUMN) → Cloud Task → Anthropic Haiku, with anti-prompt-injection guards

Example

{
  "data": {
    "type": "custom_column",
    "id": "7c1f9a02-4d3b-4e21-9a77-2f0c11aa33bc",
    "attributes": {
      "custom_column_id": "7c1f9a02-4d3b-4e21-9a77-2f0c11aa33bc",
      "root": "companies",
      "name": "Risk level",
      "field_key": "risk_level",
      "type": "single_select",
      "position": 3,
      "icon": "shield-alert",
      "rules_config": "{\"prompt\":\"Classify the company risk as low, medium, or high based on its industry and country.\"}",
      "formula_config": null,
      "format_config": "{\"options\":[\"low\",\"medium\",\"high\"]}",
      "created_at": "2026-05-20T09:14:00.000Z",
      "updated_at": "2026-05-28T11:02:00.000Z",
      "deleted_at": null
    }
  },
  "relationships": {
    "workspace": {
      "data": {
        "type": "workspace",
        "id": "a1b2c3d4-0000-4000-8000-000000000001"
      }
    }
  }
}

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

Main objects

Supporting objects

Platform objects

Activity objects

Infrastructure objects

API operations

Data model

Attributes

Relationships

System-computed

Example

​API operations

​Data model

​Attributes

​Relationships

​System-computed

​Example

API operations

Data model

Attributes

Relationships

System-computed

Example