DataView

DataView represents a named, global (non-workspace-scoped) saved view configuration used by the backoffice records table engine. It stores a display name, a record root (the entity type being queried, e.g. "companies" or "invoices"), and a two-dimensional JSONB field list defining which columns to show. DataViews are created and updated exclusively through the internal backoffice endpoint (POST /v1/backoffice/records/save) and are accessible only to email-whitelisted admin users. There are no workspace relationships — the entity is a global template layer sitting above the per-workspace WorkspaceView entity, which carries workspace tenancy and user-editable saved filters.

Naming	Value
Object	DataView
Resource type (JSON:API `type`)	`data_view`
Collection / records root	— _{(not a records root)}
REST base	`/v1/data-views`
Entity class	`DataView`

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

Data model

Attributes

Field	Type	Required	Constraints	Allowed values	Description
id	string (UUID) — 🔒 system	✅ Yes	unique; default gen_random_uuid()	—	Public stable identifier for the view. Generated by PostgreSQL on insert. Immutable after creation.
name	string	✅ Yes	varchar(255); unique across all data_views (global)	—	Human-readable display name for the view. Must be globally unique. Used as the upsert key in the save controller: if a row with this name already exists it is updated in place; otherwise a new row is created.
root	string	✅ Yes	varchar(50); value must match a valid DataViewRoot constant (e.g. 'companies', 'invoices', 'people', 'transactions', 'documents')	—	The entity root this view is configured for. Determines which Hasura table is queried and which field metadata applies. Corresponds to values in DATA_VIEW_ROOTS (packages/shared).
fields	string[][] (JSONB)	✅ Yes	JSONB not null; outer array is the ordered column list; each inner array is a field path tuple (typically a single element but allows grouped sub-paths)	—	Ordered column configuration for the view. Each element of the outer array represents one displayed column; the inner array holds the field path(s) that compose it. Composite fields (e.g. ['composite_logo_name']) reference composite recipes defined in composites.yml.
created_at	datetime — 🔒 system	✅ Yes	timestamptz not null; set by MikroORM onCreate hook	—	UTC timestamp of row creation. Populated automatically by the MikroORM @Property onCreate hook; never set by callers.
updated_at	datetime — 🔒 system	⚪ No	timestamptz nullable; set by MikroORM onCreate + onUpdate hooks	—	UTC timestamp of the most recent update. Populated automatically by MikroORM on every flush. Null only if the row has never been updated after initial creation (unlikely given the upsert save path).

System-computed

id — generated by gen_random_uuid() database default on INSERT; immutable
created_at — set by MikroORM @Property({ onCreate: () => new Date() }); never supplied by callers
updated_at — set by MikroORM @Property({ onCreate: () => new Date(), onUpdate: () => new Date() }); refreshed on every entity flush
No deleted_at — DataView is explicitly listed in apps/api/CLAUDE.md as an append-only / no-soft-delete entity (alongside ChatConversation and SessionEvent)
Upsert-by-name — handleSaveView performs a findOne({ name }) before create: if a view with that name exists, root and fields are overwritten in place; otherwise a new row is created. This means name is effectively the idempotency key for the backoffice save endpoint.

Example

{
  "data": {
    "type": "data_view",
    "id": "a3f1c2d4-0e8b-4a2f-9c7d-1b5e6f3a0c4d",
    "attributes": {
      "name": "Companies — Default 34-column",
      "root": "companies",
      "fields": [
        ["composite_logo_name"],
        ["name"],
        ["domain"],
        ["business_type"],
        ["composite_people_list"],
        ["composite_locations_list"]
      ],
      "created_at": "2025-10-02T12:31:07.000Z",
      "updated_at": "2026-01-15T09:14:22.000Z"
    }
  }
}

_{Source: /Users/maximechampoux/platform/apps/api/src/database/entities/DataView.ts · domain: workspace · tier: Infrastructure}