Overview

What the data layer covers

A Twenty app’s data layer is the data your app adds to a workspace — the new record types it declares, the columns it adds to existing objects, and how those records connect to each other.

┌──────────────────────────────────────────────────┐
│ Object — a record type, e.g. PostCard            │
│    ├─ Field     (name, type, label)              │
│    ├─ Field                                      │
│    └─ Relation  (link to another object)         │
└──────────────────────────────────────────────────┘
            │
            ├── lives in your app, OR
            │
            ▼
┌──────────────────────────────────────────────────┐
│ Standard / other apps' objects                   │
│    └─ Field added by your app via defineField    │
└──────────────────────────────────────────────────┘

In this section

Objects

defineObject — declare new record types with their own fields.

Extending Objects

defineField — add fields to standard or other apps’ objects.

Relations

Bidirectional MANY_TO_ONE / ONE_TO_MANY connections between objects.

Timeline Activity Types

Define automatic audit events and explicit app events for record timelines.

Validation Rules

defineValidationRule — declare the conditions a record must meet before it can be saved.

Entities at a glance

Entity	Purpose	Defined with
Object	A new custom record type (e.g. PostCard, Invoice) with its own fields	`defineObject()`
Field	A column on an object. Standalone fields can extend objects you didn’t create (e.g. add `loyaltyTier` to Company)	`defineField()`
Relation	A bidirectional link between two objects — both sides declared as fields	`defineField()` with `FieldType.RELATION`
Index	A database index to speed up a recurring query on one of your objects	`defineIndex()`
Timeline activity type	An automatic audit event or explicit domain event shown in record timelines	`defineTimelineActivityType()`
Related record path	A chain of up to three relations along which access to a record extends to its related records	`defineRelatedRecordPath()`
Validation rule	A condition a record must meet before it can be saved	`defineValidationRule()`

The CLI detects these via AST analysis at build time, so file organization is up to you — the convention is src/objects/, src/validation-rules/, src/fields/, src/indexes/, src/timeline-activity-types/, and src/related-record-paths/. Stable universalIdentifier UUIDs tie everything together across deploys.

Indexes (optional)

Apps can ship indexes alongside their objects to keep recurring queries fast. The most common case is a status or foreign-key column that you read frequently.

src/indexes/post-card-status.index.ts

import { defineIndex } from 'twenty-sdk/define';

import {
  POST_CARD_UNIVERSAL_IDENTIFIER,
  STATUS_FIELD_UNIVERSAL_IDENTIFIER,
} from '../objects/post-card.object';

export default defineIndex({
  universalIdentifier: 'b6e9d2a1-5a4c-46ca-9d52-42c8f02d1ff0',
  objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
  fields: [
    {
      universalIdentifier: 'b6e9d2a1-5a4c-46ca-9d52-42c8f02d1ff1',
      fieldUniversalIdentifier: STATUS_FIELD_UNIVERSAL_IDENTIFIER,
    },
  ],
});

Unique indexes

defineIndex accepts isUnique: true for both single- and multi-column uniqueness. This is the recommended primitive — defineField({ isUnique: true }) is deprecated and will be removed in a future release.

defineIndex({
  universalIdentifier: '…',
  objectUniversalIdentifier: PERSON_UNIVERSAL_IDENTIFIER,
  isUnique: true,
  fields: [{ universalIdentifier: '…', fieldUniversalIdentifier: EMAIL_FIELD_UNIVERSAL_IDENTIFIER }],
});

Other constraints

Partial WHERE clauses stay under admin control — apps can’t declare them.
Each object is capped at 10 custom indexes (the framework’s own indexes don’t count).

Order the fields array the way Postgres should use it — leftmost column first, like a phone book. Indexes are not free: every write to the table updates them. Add one only when you have a query that needs it.

Related record paths are in preview: they sync with your app, but record permissions don’t use them yet. Once enforced, they require the Organization plan or above, like row-level security.

A related record path starts on an object and follows up to three relation fields, each on the object the previous one reached. Record permissions use these paths to extend access from a record to its related records.

An inherent path (isInherent: true) applies whenever the starting record is readable, however that access was granted. Use it for records that belong to their parent, such as a post card’s attachments.
A regular path applies only when access to the starting record comes directly from a role, so workspaces choose which ones to rely on.

src/related-record-paths/post-card-attachments.related-record-path.ts

import { defineRelatedRecordPath } from 'twenty-sdk/define';

import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
import { ATTACHMENTS_ON_POST_CARD_UNIVERSAL_IDENTIFIER } from '../fields/attachments-on-post-card.field';

export default defineRelatedRecordPath({
  universalIdentifier: 'c1b8f0d2-7e4a-4b6c-9a1d-3f5e2b7c8d90',
  objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
  firstFieldMetadataUniversalIdentifier:
    ATTACHMENTS_ON_POST_CARD_UNIVERSAL_IDENTIFIER,
  isInherent: true,
});

Add secondFieldMetadataUniversalIdentifier and thirdFieldMetadataUniversalIdentifier for longer paths. Each hop must be an active relation on the object reached so far, a path can’t visit the same object twice, and two paths can’t use the same hops.

Looking for Application Config or Roles & Permissions? Those describe the app itself rather than the data it adds — they live under Config. Looking for Connections (Linear, GitHub, Slack OAuth)? Those exist to be called from logic functions and live under Logic.

Developers

Apps

API

Self-Host

Contribute

UI Library

What the data layer covers

In this section

Entities at a glance

Indexes (optional)

Unique indexes

Other constraints

​What the data layer covers

​In this section

​Entities at a glance

​Indexes (optional)

​Unique indexes

​Other constraints

​Related record paths (optional)

What the data layer covers

In this section

Entities at a glance

Indexes (optional)

Unique indexes

Other constraints

Related record paths (optional)