Panoramica

Cosa copre il livello dati

Il data layer di un’app Twenty è l’insieme dei dati che la tua app aggiunge a uno spazio di lavoro — i nuovi tipi di record che dichiara, le colonne che aggiunge agli oggetti esistenti e come questi record si collegano tra loro.

┌──────────────────────────────────────────────────┐
│ 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 questa sezione

Objects

defineObject — dichiara nuovi tipi di record con i propri campi.

Estendere gli oggetti

defineField — aggiungi campi agli oggetti standard o di altre applicazioni.

Relations

Bidirezionale MANY_TO_ONE / connessioni ONE_TO_MANY tra oggetti.

Tipi di attività Timeline

Definire gli eventi di audit automatico e gli eventi espliciti delle app per registrare le cronologie.

Regole di convalida

defineValidationRule — dichiara le condizioni che un record deve soddisfare prima di poter essere salvato.

Entità in sintesi

Entità	Scopo	Definito con
Oggetto	Un nuovo tipo di record personalizzato (ad es. PostCard, Invoice) con i propri campi	`defineObject()`
Campo	Una colonna su un oggetto. I campi autonomi possono estendere oggetti che non hai creato tu (ad es. aggiungere `loyaltyTier` a Company)	`defineField()`
Relazione	Un collegamento bidirezionale tra due oggetti — entrambi i lati sono dichiarati come campi	`defineField()` con `FieldType.RELATION`
Indice	Un indice di database per velocizzare una query ricorrente su uno dei tuoi oggetti	`defineIndex()`
Tipo di attività della timeline	Un evento di audit automatico o un evento di dominio esplicito visualizzato nelle timeline dei record	`defineTimelineActivityType()`
Percorso del record correlato	Una catena di un massimo di tre relazioni attraverso la quale l’accesso a un record si estende ai record correlati	`defineRelatedRecordPath()`
Regola di convalida	Una condizione che un record deve soddisfare prima di poter essere salvato	`defineValidationRule()`

La CLI rileva questi elementi tramite analisi AST in fase di build, quindi l’organizzazione dei file spetta a te — la convenzione è src/objects/, src/validation-rules/, src/fields/, src/indexes/, src/timeline-activity-types/ e src/related-record-paths/. Gli UUID universalIdentifier stabili collegano tutto tra le varie distribuzioni.

Indici (facoltativi)

Le app possono distribuire indici insieme ai loro oggetti per mantenere veloci le query ricorrenti. Il caso più comune è una colonna di stato o di chiave esterna che leggi spesso.

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

Indici univoci

defineIndex accetta isUnique: true sia per l’univocità a singola colonna sia per quella multi-colonna. Questa è la primitiva consigliata — defineField({ isUnique: true }) è deprecata e verrà rimossa in una futura release.

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

Altri vincoli

Le clausole WHERE parziali restano sotto il controllo dell’amministratore — le app non possono dichiararle.
Ogni oggetto è limitato a 10 indici personalizzati (gli indici propri del framework non contano).

Ordina l’array fields nel modo in cui Postgres dovrebbe usarlo — la colonna più a sinistra per prima, come in un elenco telefonico. Gli indici non sono gratuiti: ogni scrittura sulla tabella li aggiorna. Aggiungine uno solo quando hai una query che ne ha bisogno.

Percorsi dei record correlati (opzionale)

I percorsi di record correlati sono in anteprima: si sincronizzano con la tua app, ma le autorizzazioni dei record non li utilizzano ancora. Una volta applicati, richiedono il piano Organization o superiore, come la sicurezza a livello di riga.

Un percorso di record correlato inizia su un oggetto e segue fino a tre campi di relazione, ciascuno sull’oggetto raggiunto dal precedente. Le autorizzazioni dei record utilizzano questi percorsi per estendere l’accesso da un record ai relativi record correlati.

Un percorso intrinseco (isInherent: true) si applica ogni volta che il record iniziale è leggibile, indipendentemente da come sia stato concesso l’accesso. Usalo per i record che appartengono al relativo elemento padre, come gli allegati di una scheda di post.
Un percorso normale si applica solo quando l’accesso al record iniziale deriva direttamente da un ruolo, quindi gli spazi di lavoro scelgono su quali fare affidamento.

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

Aggiungi secondFieldMetadataUniversalIdentifier e thirdFieldMetadataUniversalIdentifier per percorsi più lunghi. Ogni passaggio deve essere una relazione attiva sull’oggetto raggiunto fino a quel momento, un percorso non può visitare lo stesso oggetto due volte e due percorsi non possono utilizzare gli stessi passaggi.

Cerchi Application Config o Roles & Permissions? Quelli descrivono l’app in sé piuttosto che i dati che aggiunge — si trovano sotto Config. Cerchi Connections (Linear, GitHub, Slack OAuth)? Quelle esistono per essere chiamate dalle funzioni di logica e si trovano sotto Logic.

Sviluppatori

App

API

Auto-ospitazione

Contribuire

Libreria UI

Cosa copre il livello dati

In questa sezione

Entità in sintesi

Indici (facoltativi)

Indici univoci

Altri vincoli

Percorsi dei record correlati (opzionale)

​Cosa copre il livello dati

​In questa sezione

​Entità in sintesi

​Indici (facoltativi)

​Indici univoci

​Altri vincoli

​Percorsi dei record correlati (opzionale)

Cosa copre il livello dati

In questa sezione

Entità in sintesi

Indici (facoltativi)

Indici univoci

Altri vincoli

Percorsi dei record correlati (opzionale)