نظرة عامة

طبقة البيانات في تطبيق 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()`

يكتشف SDK هذه العناصر عبر تحليل AST أثناء وقت البناء، لذا تنظيم الملفات يعود إليك — القاعدة المتّبعة هي src/objects/ و src/fields/ و src/indexes/. معرّفات 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 استخدامها — العمود في أقصى اليسار أولًا، مثل دليل الهاتف. الفهارس ليست مجانية: كل عملية كتابة في الجدول تقوم بتحديثها. أضِف واحدًا فقط عندما يكون لديك استعلام يحتاج إليه.

هل تبحث عن Application Config أو Roles & Permissions؟ هذه تصف التطبيق نفسه بدلًا من البيانات التي يضيفها — وتوجد ضمن Config. هل تبحث عن Connections (Linear, GitHub, Slack OAuth)؟ هذه وُجِدت ليتم استدعاؤها من دوال المنطق وتوجد ضمن Logic.

التطبيقات

واجهة برمجة التطبيقات

الاستضافة الذاتية

المساهمة

نظرة عامة

في هذا القسم

كائنات

توسيع الكائنات

العلاقات

الكيانات بنظرة سريعة

الفهارس (اختياري)

الفهارس الفريدة

قيود أخرى

​في هذا القسم

كائنات

توسيع الكائنات

العلاقات

​الكيانات بنظرة سريعة

​الفهارس (اختياري)

​الفهارس الفريدة

​قيود أخرى

في هذا القسم

الكيانات بنظرة سريعة

الفهارس (اختياري)

الفهارس الفريدة

قيود أخرى