Relations

Relations connect two objects together. In Twenty, relations are always bidirectional — every relation has two sides, and each side is declared as a field that references the other.

Relation type	Description	Has foreign key?
`MANY_TO_ONE`	Many records of this object point to one record of the target	Yes (`joinColumnName`)
`ONE_TO_MANY`	One record of this object has many records of the target	No (the inverse side)

How relations work

Every relation requires two fields that reference each other:

The MANY_TO_ONE side — lives on the object that holds the foreign key.
The ONE_TO_MANY side — lives on the object that owns the collection.

Both fields use FieldType.RELATION and cross-reference each other via relationTargetFieldMetadataUniversalIdentifier.

Example: Post Card has many Recipients

A PostCard can be sent to many PostCardRecipient records. Each recipient belongs to exactly one post card. Step 1: Define the ONE_TO_MANY side on PostCard (the “one” side):

src/fields/post-card-recipients-on-post-card.field.ts

import { defineField, FieldType, RelationType } from 'twenty-sdk/define';
import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';

// Export so the other side can reference it
export const POST_CARD_RECIPIENTS_FIELD_ID = 'a1111111-1111-1111-1111-111111111111';
// Import from the other side
import { POST_CARD_FIELD_ID } from './post-card-on-post-card-recipient.field';

export default defineField({
  universalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
  objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
  type: FieldType.RELATION,
  name: 'postCardRecipients',
  label: 'Post Card Recipients',
  icon: 'IconUsers',
  relationTargetObjectMetadataUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
  relationTargetFieldMetadataUniversalIdentifier: POST_CARD_FIELD_ID,
  universalSettings: {
    relationType: RelationType.ONE_TO_MANY,
  },
});

Step 2: Define the MANY_TO_ONE side on PostCardRecipient (the “many” side — holds the foreign key):

src/fields/post-card-on-post-card-recipient.field.ts

import { defineField, FieldType, RelationType, OnDeleteAction } from 'twenty-sdk/define';
import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';

// Export so the other side can reference it
export const POST_CARD_FIELD_ID = 'b2222222-2222-2222-2222-222222222222';
// Import from the other side
import { POST_CARD_RECIPIENTS_FIELD_ID } from './post-card-recipients-on-post-card.field';

export default defineField({
  universalIdentifier: POST_CARD_FIELD_ID,
  objectUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
  type: FieldType.RELATION,
  name: 'postCard',
  label: 'Post Card',
  icon: 'IconMail',
  relationTargetObjectMetadataUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
  relationTargetFieldMetadataUniversalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
  universalSettings: {
    relationType: RelationType.MANY_TO_ONE,
    onDelete: OnDeleteAction.CASCADE,
    joinColumnName: 'postCardId',
  },
});

Circular imports: both relation fields reference each other’s universalIdentifier. To avoid circular import issues, export your field IDs as named constants from each file and import them in the other. The build system resolves these at compile time.

Junction relations

A junction object connects one source record to one or more target records. For example, PostCardRecipient can hold both a postCard relation and a recipient relation. On the source object’s ONE_TO_MANY field, set junctionTargetFieldUniversalIdentifier to the relation field on the junction object that points to the target:

export default defineField({
  universalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
  objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
  type: FieldType.RELATION,
  name: 'postCardRecipients',
  label: 'Post Card Recipients',
  relationTargetObjectMetadataUniversalIdentifier:
    POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
  relationTargetFieldMetadataUniversalIdentifier: POST_CARD_FIELD_ID,
  universalSettings: {
    relationType: RelationType.ONE_TO_MANY,
    junctionTargetFieldUniversalIdentifier: RECIPIENT_FIELD_ID,
  },
});

RECIPIENT_FIELD_ID must identify a MANY_TO_ONE or morph relation on the junction object. It tells Twenty which related record is the target when a feature such as timeline activity fan-out traverses the junction.

Relating to standard objects

To create a relation with a built-in Twenty object (Person, Company, etc.), use STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS. A relation is always declared on both objects, and this does not change when one side is a standard object: the manifest must also define the reverse field on the standard object, with the standard object’s universalIdentifier as objectUniversalIdentifier. If the reverse field is missing, the app fails to sync with Relation field target metadata not found.

src/fields/person-on-self-hosting-user.field.ts

import {
  defineField,
  FieldType,
  RelationType,
  OnDeleteAction,
  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
} from 'twenty-sdk/define';
import { SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER } from '../objects/self-hosting-user.object';

export const PERSON_FIELD_ID = 'c3333333-3333-3333-3333-333333333333';
export const SELF_HOSTING_USER_REVERSE_FIELD_ID = 'd4444444-4444-4444-4444-444444444444';

export default defineField({
  universalIdentifier: PERSON_FIELD_ID,
  objectUniversalIdentifier: SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER,
  type: FieldType.RELATION,
  name: 'person',
  label: 'Person',
  description: 'Person matching with the self hosting user',
  isNullable: true,
  relationTargetObjectMetadataUniversalIdentifier:
    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.universalIdentifier,
  relationTargetFieldMetadataUniversalIdentifier: SELF_HOSTING_USER_REVERSE_FIELD_ID,
  universalSettings: {
    relationType: RelationType.MANY_TO_ONE,
    onDelete: OnDeleteAction.SET_NULL,
    joinColumnName: 'personId',
  },
});

src/fields/self-hosting-users-on-person.field.ts

import {
  defineField,
  FieldType,
  RelationType,
  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
} from 'twenty-sdk/define';
import { SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER } from '../objects/self-hosting-user.object';
import {
  PERSON_FIELD_ID,
  SELF_HOSTING_USER_REVERSE_FIELD_ID,
} from './person-on-self-hosting-user.field';

export default defineField({
  universalIdentifier: SELF_HOSTING_USER_REVERSE_FIELD_ID,
  objectUniversalIdentifier:
    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.universalIdentifier,
  type: FieldType.RELATION,
  name: 'selfHostingUsers',
  label: 'Self hosting users',
  relationTargetObjectMetadataUniversalIdentifier:
    SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER,
  relationTargetFieldMetadataUniversalIdentifier: PERSON_FIELD_ID,
  universalSettings: {
    relationType: RelationType.ONE_TO_MANY,
  },
});

Relation field properties

Property	Required	Description
`type`	Yes	Must be `FieldType.RELATION`
`relationTargetObjectMetadataUniversalIdentifier`	Yes	The `universalIdentifier` of the target object
`relationTargetFieldMetadataUniversalIdentifier`	Yes	The `universalIdentifier` of the matching field on the target object
`universalSettings.relationType`	Yes	`RelationType.MANY_TO_ONE` or `RelationType.ONE_TO_MANY`
`universalSettings.onDelete`	MANY_TO_ONE only	What happens when the referenced record is deleted: `CASCADE`, `SET_NULL`, `RESTRICT`, or `NO_ACTION`
`universalSettings.joinColumnName`	MANY_TO_ONE only	Database column name for the foreign key (e.g., `postCardId`)
`universalSettings.junctionTargetFieldUniversalIdentifier`	Junction ONE_TO_MANY only	Relation field on the junction object that points to the fan-out target

Inline relation fields

You can also declare a relation directly inside defineObject. When inline, omit objectUniversalIdentifier — it’s inherited from the parent object:

export default defineObject({
  universalIdentifier: '...',
  nameSingular: 'postCardRecipient',
  // ...
  fields: [
    {
      universalIdentifier: POST_CARD_FIELD_ID,
      type: FieldType.RELATION,
      name: 'postCard',
      label: 'Post Card',
      relationTargetObjectMetadataUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
      relationTargetFieldMetadataUniversalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
      universalSettings: {
        relationType: RelationType.MANY_TO_ONE,
        onDelete: OnDeleteAction.CASCADE,
        joinColumnName: 'postCardId',
      },
    },
    // … other fields
  ],
});

Overview

Apps

API

Self-Host

Contribute

UI Library

How relations work

Example: Post Card has many Recipients

Junction relations

Relating to standard objects

Relation field properties

Inline relation fields

​How relations work

​Example: Post Card has many Recipients

​Junction relations

​Relating to standard objects

​Relation field properties

​Inline relation fields

How relations work

Example: Post Card has many Recipients

Junction relations

Relating to standard objects

Relation field properties

Inline relation fields