Связи

Как работают отношения

Отношения связывают два объекта между собой. В Twenty отношения всегда двунаправленные — у каждого отношения есть две стороны, и каждая сторона объявляется как поле, ссылающееся на другую.

Тип отношения	Описание	Есть внешний ключ?
`MANY_TO_ONE`	Многие записи этого объекта указывают на одну запись целевого объекта	Да (`joinColumnName`)
`ONE_TO_MANY`	Одна запись этого объекта имеет много записей целевого объекта	Нет (обратная сторона)

Каждое отношение требует двух полей, которые ссылаются друг на друга:

Сторона MANY_TO_ONE — находится в объекте, который содержит внешний ключ.
Сторона ONE_TO_MANY — находится в объекте, которому принадлежит коллекция.

Оба поля используют FieldType.RELATION и ссылаются друг на друга через relationTargetFieldMetadataUniversalIdentifier.

Пример: Почтовая открытка имеет много получателей

PostCard может быть отправлен множеству записей PostCardRecipient. Каждый получатель относится ровно к одной открытке. Шаг 1: Определите сторону ONE_TO_MANY на PostCard (сторона “one”):

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,
  },
});

Шаг 2: Определите сторону MANY_TO_ONE на PostCardRecipient (сторона “many” — содержит внешний ключ):

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',
  },
});

Циклические импорты: оба поля отношений ссылаются на universalIdentifier друг друга. Чтобы избежать проблем с циклическими импортами, экспортируйте идентификаторы полей как именованные константы из каждого файла и импортируйте их в другом. Система сборки разрешает это на этапе компиляции.

Связи через промежуточный объект

Промежуточный объект связывает одну исходную запись с одной или несколькими целевыми записями. Например, PostCardRecipient может содержать связь postCard и связь recipient. В поле ONE_TO_MANY исходного объекта задайте для junctionTargetFieldUniversalIdentifier поле связи в промежуточном объекте, указывающее на цель:

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 должен идентифицировать связь MANY_TO_ONE или морфную связь в промежуточном объекте. Это сообщает Twenty, какая связанная запись является целевой, когда функция, например распределение действий временной шкалы, проходит через промежуточный объект.

Связывание со стандартными объектами

Чтобы создать отношение со встроенным объектом Twenty (Person, Company и т. д.), используйте STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS. Связь всегда объявляется для обоих объектов, и это не меняется, когда одна из сторон является стандартным объектом: манифест также должен определять обратное поле в стандартном объекте, используя universalIdentifier стандартного объекта в качестве objectUniversalIdentifier. Если обратное поле отсутствует, приложению не удается синхронизироваться с ошибкой 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,
  },
});

Свойства поля отношения

Свойство	Обязательно	Описание
`type`	Да	Должно быть `FieldType.RELATION`
`relationTargetObjectMetadataUniversalIdentifier`	Да	`universalIdentifier` целевого объекта
`relationTargetFieldMetadataUniversalIdentifier`	Да	`universalIdentifier` соответствующего поля на целевом объекте
`universalSettings.relationType`	Да	`RelationType.MANY_TO_ONE` или `RelationType.ONE_TO_MANY`
`universalSettings.onDelete`	Только для MANY_TO_ONE	Что происходит при удалении связанной записи: `CASCADE`, `SET_NULL`, `RESTRICT` или `NO_ACTION`
`universalSettings.joinColumnName`	Только для MANY_TO_ONE	Имя столбца базы данных для внешнего ключа (например, `postCardId`)
`universalSettings.junctionTargetFieldUniversalIdentifier`	Только для промежуточного объекта ONE_TO_MANY	Поле связи в промежуточном объекте, указывающее на цель распределения

Встроенные поля связей

Вы также можете объявить связь напрямую внутри defineObject. При встроенном объявлении опустите objectUniversalIdentifier — он наследуется от родительского объекта:

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
  ],
});

Разработчики

Приложения

API

Самостоятельный хостинг

Внести вклад

Библиотека интерфейса

Как работают отношения

Пример: Почтовая открытка имеет много получателей

Связи через промежуточный объект

Связывание со стандартными объектами

Свойства поля отношения

Встроенные поля связей

​Как работают отношения

​Пример: Почтовая открытка имеет много получателей

​Связи через промежуточный объект

​Связывание со стандартными объектами

​Свойства поля отношения

​Встроенные поля связей

Как работают отношения

Пример: Почтовая открытка имеет много получателей

Связи через промежуточный объект

Связывание со стандартными объектами

Свойства поля отношения

Встроенные поля связей