#Collections Tabel Data

Dalam pengembangan plugin NocoBase, Collection (Tabel Data) adalah salah satu konsep paling inti. Anda dapat menambah atau memodifikasi struktur tabel data dalam plugin dengan mendefinisikan atau memperluas Collection. Berbeda dengan tabel data yang dibuat melalui antarmuka "Manajemen Data Source", Collection yang didefinisikan dengan kode biasanya merupakan tabel metadata level sistem, tidak akan muncul di daftar manajemen data source.

#Mendefinisikan Tabel Data

Sesuai dengan struktur direktori konvensi, file Collection harus diletakkan di direktori ./src/server/collections. Membuat tabel baru menggunakan defineCollection(), memperluas tabel yang ada menggunakan extendCollection().

import { defineCollection } from '@nocobase/database';

export default defineCollection({
  name: 'articles',
  title: 'Contoh Artikel',
  fields: [
    { type: 'string', name: 'title', interface: 'input', uiSchema: { title: 'Judul', required: true } },
    { type: 'text', name: 'content', interface: 'textarea', uiSchema: { title: 'Konten' } },
    {
      type: 'belongsTo',
      name: 'author',
      target: 'users',
      foreignKey: 'authorId',
      interface: 'recordPicker',
      uiSchema: { title: 'Penulis' },
    },
  ],
});

Pada contoh di atas:

• name: Nama tabel (akan otomatis menghasilkan tabel dengan nama yang sama di database).
• title: Nama tampilan tabel di antarmuka.
• fields: Kumpulan field, setiap field berisi property type, name, dan lainnya.

Saat perlu menambahkan field atau memodifikasi konfigurasi untuk Collection plugin lain, dapat menggunakan extendCollection():

import { extendCollection } from '@nocobase/database';

export default extendCollection({
  name: 'articles',
  fields: [
    {
      type: 'boolean',
      name: 'isPublished',
      defaultValue: false,
    },
  ],
});

Setelah plugin diaktifkan, sistem akan secara otomatis menambahkan field isPublished ke tabel articles yang sudah ada.

#Cheatsheet Tipe Field

Pada fields defineCollection, type menentukan tipe kolom field di database. Berikut adalah semua tipe field bawaan:

#Teks

#Angka

#Boolean

#Tanggal Waktu

#Data Terstruktur

#Generasi ID

#Tipe Khusus

#Tipe Asosiasi

Field asosiasi tidak membuat kolom database, tetapi membangun relasi antar tabel di layer ORM:

Contoh penggunaan field asosiasi:

export default defineCollection({
  name: 'articles',
  fields: [
    { type: 'string', name: 'title' },
    // Many-to-one: Artikel milik satu penulis
    {
      type: 'belongsTo',
      name: 'author',
      target: 'users',
      foreignKey: 'authorId',
    },
    // One-to-many: Artikel memiliki banyak komentar
    {
      type: 'hasMany',
      name: 'comments',
      target: 'comments',
      foreignKey: 'articleId',
    },
    // Many-to-many: Artikel memiliki banyak tag
    {
      type: 'belongsToMany',
      name: 'tags',
      target: 'tags',
      through: 'articlesTags',  // Nama tabel perantara
    },
  ],
});

#Parameter Umum

Semua field kolom mendukung parameter berikut:

#Sinkronisasi Struktur Database

Saat plugin pertama kali diaktifkan, sistem akan secara otomatis menyinkronkan konfigurasi Collection dengan struktur database. Jika plugin sudah terinstal dan sedang berjalan, setelah menambah atau memodifikasi Collection perlu menjalankan command upgrade secara manual:

yarn nocobase upgrade

Jika terjadi exception atau data kotor selama proses sinkronisasi, dapat membangun ulang struktur tabel dengan menginstal ulang aplikasi:

yarn nocobase install -f

Jika upgrade plugin perlu melakukan migrasi pada data yang ada — seperti rename field, split tabel, mengisi nilai default, dll. — harus ditangani melalui Migration Skrip Upgrade, bukan dengan mengubah database secara manual.

#Membuat Collection Muncul di Daftar Tabel Data UI

Tabel yang didefinisikan melalui defineCollection adalah tabel internal server, secara default tidak akan muncul di daftar "Manajemen Data Source", juga tidak akan muncul di daftar pemilihan tabel data saat "Menambahkan Block".

Cara yang Direkomendasikan: Tambahkan tabel data yang sesuai di "Manajemen Data Source" di antarmuka NocoBase, setelah konfigurasi field dan tipe interface, tabel akan otomatis muncul di daftar pemilihan tabel data Block.

Jika memang perlu didaftarkan dalam kode plugin (seperti skenario demo dalam plugin contoh), dapat mendaftarkan secara manual melalui addCollection dalam plugin client. Perhatikan harus didaftarkan melalui mode eventBus, tidak boleh dipanggil langsung di load() — ensureLoaded() akan membersihkan dan mengatur ulang semua collection setelah load(). Untuk contoh lengkap lihat Membuat Plugin Manajemen Data Front-Back End.

#Resource yang Dihasilkan Otomatis

Setelah mendefinisikan Collection, NocoBase akan otomatis menghasilkan resource REST API yang sesuai untuknya, API CRUD yang siap pakai (list, get, create, update, destroy) tidak perlu ditulis tambahan. Jika operasi CRUD bawaan tidak cukup — misalnya Anda memerlukan API "import batch" atau "ringkasan statistik" — dapat mendaftarkan action kustom melalui resourceManager. Lihat ResourceManager Manajemen Resource.

#Tautan Terkait

• Database — CRUD, Repository, transaksi, dan event database
• DataSourceManager Manajemen Data Source — Mengelola beberapa data source dan collection-nya
• Migration Migrasi Data — Skrip migrasi data saat upgrade plugin
• Plugin — Siklus hidup class plugin, member method, dan objek app
• ResourceManager Manajemen Resource — REST API kustom dan handler operasi
• Membuat Plugin Manajemen Data Front-Back End — Contoh lengkap defineCollection + addCollection
• Struktur Direktori Proyek — Penjelasan konvensi direktori src/server/collections