Resumen

Qué cubre la capa de datos

La capa de datos de una aplicación de Twenty es el conjunto de datos que tu aplicación agrega a un espacio de trabajo — los nuevos tipos de registros que declara, las columnas que agrega a los objetos existentes y cómo esos registros se conectan entre sí.

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

En esta sección

Objects

defineObject — declarar nuevos tipos de registro con sus propios campos.

Extender Objetos

defineField - añadir campos a objetos estándar u otras aplicaciones.

Relaciones

Conexiones bidireccionales MANY_TO_ONE / ONE_TO_MANY entre objetos.

Tipos de actividad de línea de tiempo

Definir eventos de auditoría automática y eventos explícitos de la aplicación para grabar cronología.

Reglas de validación

defineValidationRule — declara las condiciones que un registro debe cumplir antes de poder guardarse.

Entidades de un vistazo

Entidad	Propósito	Definido con
Objeto	Un nuevo tipo de registro personalizado (por ejemplo, PostCard, Invoice) con sus propios campos	`defineObject()`
Campo	Una columna en un objeto. Los campos independientes pueden ampliar objetos que no creaste (por ejemplo, agregar `loyaltyTier` a Company)	`defineField()`
Relación	Un vínculo bidireccional entre dos objetos: ambos lados se declaran como campos	`defineField()` con `FieldType.RELATION`
Índice	Un índice de base de datos para acelerar una consulta recurrente sobre uno de tus objetos	`defineIndex()`
Tipo de actividad de la cronología	Un evento de auditoría automático o un evento de dominio explícito mostrado en las líneas de tiempo de los registros	`defineTimelineActivityType()`
Ruta de registros relacionados	Una cadena de hasta tres relaciones a través de las cuales el acceso a un registro se extiende a sus registros relacionados	`defineRelatedRecordPath()`
Regla de validación	Una condición que un registro debe cumplir antes de poder guardarse	`defineValidationRule()`

La CLI detecta estos mediante análisis AST en tiempo de compilación, por lo que la organización de los archivos depende de ti; la convención es src/objects/, src/validation-rules/, src/fields/, src/indexes/, src/timeline-activity-types/ y src/related-record-paths/. Los UUID universalIdentifier estables vinculan todo a través de los despliegues.

Índices (opcional)

Las aplicaciones pueden incluir índices junto con sus objetos para mantener rápidas las consultas recurrentes. El caso más habitual es una columna de estado o de clave externa que lees con frecuencia.

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

Índices únicos

defineIndex acepta isUnique: true tanto para unicidad de una sola columna como de varias columnas. Este es el elemento primitivo recomendado — defineField({ isUnique: true }) está obsoleto y se eliminará en una versión futura.

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

Otras restricciones

Las cláusulas WHERE parciales permanecen bajo el control del administrador: las aplicaciones no pueden declararlas.
Cada objeto está limitado a 10 índices personalizados (los índices propios del framework no cuentan).

Ordena el arreglo fields de la forma en que Postgres debería usarlo: la columna más a la izquierda primero, como en una guía telefónica. Los índices no son gratuitos: cada escritura en la tabla los actualiza. Añade uno solo cuando tengas una consulta que lo necesite.

Rutas de registros relacionados (opcional)

Las rutas de registros relacionados están en vista previa: se sincronizan con tu aplicación, pero los permisos de registros aún no las usan. Una vez aplicadas, requieren el plan Organization o superior, como la seguridad a nivel de fila.

Una ruta de registros relacionados comienza en un objeto y sigue hasta tres campos de relación, cada uno en el objeto al que llegó el anterior. Los permisos de registros usan estas rutas para ampliar el acceso de un registro a sus registros relacionados.

Una ruta inherente (isInherent: true) se aplica siempre que se pueda leer el registro inicial, independientemente de cómo se haya concedido ese acceso. Úsala para los registros que pertenecen a su elemento principal, como los archivos adjuntos de una tarjeta de publicación.
Una ruta regular se aplica solo cuando el acceso al registro inicial proviene directamente de un rol, por lo que los espacios de trabajo eligen en cuáles basarse.

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

Agrega secondFieldMetadataUniversalIdentifier y thirdFieldMetadataUniversalIdentifier para rutas más largas. Cada salto debe ser una relación activa en el objeto al que se ha llegado hasta el momento, una ruta no puede visitar el mismo objeto dos veces y dos rutas no pueden usar los mismos saltos.

¿Buscas Application Config o Roles & Permissions? Esos describen la propia aplicación en lugar de los datos que agrega; se encuentran en Config. ¿Buscas Connections (Linear, GitHub, Slack OAuth)? Estas existen para ser llamadas desde las funciones lógicas y se encuentran en Logic.

Desarrolladores

Aplicaciones

API

Autoalojamiento

Contribuir

Biblioteca de IU

Qué cubre la capa de datos

En esta sección

Entidades de un vistazo

Índices (opcional)

Índices únicos

Otras restricciones

Rutas de registros relacionados (opcional)

​Qué cubre la capa de datos

​En esta sección

​Entidades de un vistazo

​Índices (opcional)

​Índices únicos

​Otras restricciones

​Rutas de registros relacionados (opcional)

Qué cubre la capa de datos

En esta sección

Entidades de un vistazo

Índices (opcional)

Índices únicos

Otras restricciones

Rutas de registros relacionados (opcional)