Panoramica

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

Oggetti

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

Estendere gli oggetti

defineField — aggiunge campi agli oggetti standard o di altre app.

Relazioni

Connessioni bidirezionali MANY_TO_ONE / ONE_TO_MANY tra oggetti.

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()`

L’SDK rileva questi elementi tramite analisi AST in fase di build, quindi l’organizzazione dei file dipende da te — la convenzione è src/objects/, src/fields/ e src/indexes/. 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.

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.

App

API

Auto-ospitazione

Contribuire

Panoramica

In questa sezione

Oggetti

Estendere gli oggetti

Relazioni

Entità in sintesi

Indici (facoltativi)

Indici univoci

Altri vincoli

​In questa sezione

Oggetti

Estendere gli oggetti

Relazioni

​Entità in sintesi

​Indici (facoltativi)

​Indici univoci

​Altri vincoli

In questa sezione

Entità in sintesi

Indici (facoltativi)

Indici univoci

Altri vincoli