Обзор

Что покрывает слой данных

Уровень данных приложения Twenty — это данные, которые ваше приложение добавляет в рабочее пространство: новые типы записей, которые оно объявляет, столбцы, которые оно добавляет к существующим объектам, и то, как эти записи связываются друг с другом.

┌──────────────────────────────────────────────────┐
│ 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    │
└──────────────────────────────────────────────────┘

В этом разделе

Объекты

defineObject — объявляют новые типы записей своими собственными полями.

Расширение объектов

defineField — добавляйте поля к объектам стандартного или другого приложения.

Связи

Двусторонние связи MANY_TO_ONE / ONE_TO_MANY между объектами.

Типы действий на временной шкале

Определяйте автоматические события аудита и явные события приложения для временных шкал записей.

Сущности вкратце

Сущность	Назначение	Определяется с помощью
Объект	Новый пользовательский тип записей (например, PostCard, Invoice) с собственными полями	`defineObject()`
Поле	Столбец в объекте. Отдельные поля могут расширять объекты, которые вы не создавали (например, добавьте `loyaltyTier` к объекту Company)	`defineField()`
Связь	Двусторонняя связь между двумя объектами — обе стороны объявлены как поля	`defineField()` с `FieldType.RELATION`
Индекс	Индекс базы данных для ускорения повторяющегося запроса к одному из ваших объектов	`defineIndex()`
Тип действия на временной шкале	Автоматическое событие аудита или явное событие домена, отображаемое на временных шкалах записей	`defineTimelineActivityType()`
Путь к связанной записи	Цепочка из не более чем трех связей, по которым доступ к записи распространяется на связанные с ней записи	`defineRelatedRecordPath()`

CLI обнаруживает их с помощью анализа AST во время сборки, поэтому организация файлов остается на ваше усмотрение — по соглашению используются src/objects/, src/fields/, src/indexes/, src/timeline-activity-types/ и src/related-record-paths/. Стабильные UUID universalIdentifier связывают все воедино между развертываниями.

Индексы (необязательно)

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

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

Уникальные индексы

defineIndex принимает isUnique: true как для уникальности по одному столбцу, так и по нескольким столбцам. Это рекомендуемый примитив — defineField({ isUnique: true }) устарел и будет удален в одном из будущих релизов.

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

Другие ограничения

Частичные предложения WHERE остаются под контролем администратора — приложения не могут объявлять их.
Для каждого объекта допускается не более 10 пользовательских индексов (индексы самого фреймворка не учитываются).

Упорядочьте массив fields в том порядке, в котором Postgres должен его использовать — сначала самый левый столбец, как в телефонной книге. Индексы не бесплатны: при каждой записи в таблицу они обновляются. Добавляйте индекс только тогда, когда у вас есть запрос, которому он действительно нужен.

Пути к связанным записям (необязательно)

Пути связанных записей находятся в предварительной версии: они синхронизируются с вашим приложением, но разрешения записей пока их не используют. После включения им требуется тариф Organization или выше, как и для безопасности на уровне строк.

Путь связанной записи начинается на объекте и проходит не более чем по трём полям связей, каждое из которых находится на объекте, достигнутом предыдущим полем. Разрешения записей используют эти пути для расширения доступа от записи к связанным с ней записям.

Неотъемлемый путь (isInherent: true) применяется всегда, когда начальная запись доступна для чтения, независимо от того, как был предоставлен этот доступ. Используйте его для записей, принадлежащих родительской записи, например для вложений карточки публикации.
Обычный путь применяется только тогда, когда доступ к начальной записи предоставляется непосредственно ролью, поэтому рабочие пространства выбирают, на какие из них полагаться.

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

Добавьте secondFieldMetadataUniversalIdentifier и thirdFieldMetadataUniversalIdentifier для более длинных путей. Каждый переход должен быть активной связью на достигнутом к этому моменту объекте, путь не может посещать один и тот же объект дважды, и два пути не могут использовать одни и те же переходы.

Ищете Application Config или Roles & Permissions? Они описывают само приложение, а не данные, которые оно добавляет, — их можно найти в разделе Config. Ищете Connections (Linear, GitHub, Slack OAuth)? Они существуют для вызова из логических функций и находятся в разделе Logic.

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

Приложения

API

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

Внести вклад

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

Что покрывает слой данных

В этом разделе

Сущности вкратце

Индексы (необязательно)

Уникальные индексы

Другие ограничения

Пути к связанным записям (необязательно)

​Что покрывает слой данных

​В этом разделе

​Сущности вкратце

​Индексы (необязательно)

​Уникальные индексы

​Другие ограничения

​Пути к связанным записям (необязательно)

Что покрывает слой данных

В этом разделе

Сущности вкратце

Индексы (необязательно)

Уникальные индексы

Другие ограничения

Пути к связанным записям (необязательно)