#Collections データテーブル

NocoBase のプラグイン開発において、Collection（データテーブル） は最も核となる概念の一つです。Collection を定義または拡張することで、プラグイン内でデータテーブル構造を追加・変更できます。「データソース管理」画面で作成するデータテーブルとは異なり、コードで定義された Collection は通常、システムレベルのメタデータテーブルであり、データソース管理のリストには表示されません。

#データテーブルの定義

規約に基づいたディレクトリ構造に従い、Collection ファイルは ./src/server/collections ディレクトリに配置します。新しいテーブルを作成するには defineCollection() を、既存のテーブルを拡張するには extendCollection() を使用します。

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

export default defineCollection({
  name: 'articles',
  title: 'サンプル記事',
  fields: [
    { type: 'string', name: 'title', interface: 'input', uiSchema: { title: 'タイトル', required: true } },
    { type: 'text', name: 'content', interface: 'textarea', uiSchema: { title: '本文' } },
    {
      type: 'belongsTo',
      name: 'author',
      target: 'users',
      foreignKey: 'authorId',
      interface: 'recordPicker',
      uiSchema: { title: '著者' },
    },
  ],
});

上記の例では、

• name：テーブル名（データベースに同名のテーブルが自動生成されます）。
• title：このテーブルの画面上での表示名称です。
• fields：フィールドの集合で、各フィールドには type、name などの属性が含まれます。

他のプラグインの Collection にフィールドを追加したり、設定を変更したりする必要がある場合は、extendCollection() を使用できます。

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

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

プラグインを有効化すると、システムは既存の articles テーブルに isPublished フィールドを自動的に追加します。

#フィールドタイプ早見表

defineCollection の fields において、type はフィールドのデータベース上のカラム型を決定します。以下は組み込みのフィールドタイプの一覧です。

#テキスト

#数値

#ブール値

#日付時刻

#構造化データ

#ID 生成

#特殊型

#リレーション型

リレーションフィールドはデータベースカラムを作成せず、ORM レイヤーでテーブル間の関係を構築します。

リレーションフィールドの使用例：

export default defineCollection({
  name: 'articles',
  fields: [
    { type: 'string', name: 'title' },
    // 多対一：記事は一人の著者に属する
    {
      type: 'belongsTo',
      name: 'author',
      target: 'users',
      foreignKey: 'authorId',
    },
    // 一対多：記事には複数のコメントがある
    {
      type: 'hasMany',
      name: 'comments',
      target: 'comments',
      foreignKey: 'articleId',
    },
    // 多対多：記事には複数のタグがある
    {
      type: 'belongsToMany',
      name: 'tags',
      target: 'tags',
      through: 'articlesTags',  // 中間テーブル名
    },
  ],
});

#共通パラメータ

すべてのカラムフィールドは以下のパラメータをサポートしています。

#データベース構造の同期

プラグインが初めて有効化される際、システムは Collection の設定とデータベース構造を自動的に同期します。プラグインがすでにインストールされて実行中の場合、Collection を追加または変更した後は、手動でアップグレードコマンドを実行する必要があります。

yarn nocobase upgrade

同期中に異常やダーティデータが発生した場合は、アプリケーションを再インストールすることでテーブル構造を再構築できます。

yarn nocobase install -f

プラグインのアップグレード時に既存データの移行が必要な場合――フィールド名の変更、テーブルの分割、デフォルト値の埋め戻しなど――は、データベースを手動で変更するのではなく、Migration アップグレードスクリプト で対応してください。

#Collection を UI のデータテーブルリストに表示する

defineCollection で定義されたテーブルはサーバー側の内部テーブルであり、デフォルトでは「データソース管理」のリストにも、「ブロックを追加」する際のデータテーブル選択リストにも表示されません。

推奨方法：NocoBase の画面上の「データソース管理」からデータテーブルを追加し、フィールドとインターフェースタイプを設定すれば、ブロックのデータテーブル選択リストに自動的に表示されるようになります。

プラグインのコードで登録する必要がある場合（例えばサンプルプラグインのデモシナリオなど）は、クライアントプラグインで addCollection を使って手動で登録できます。ただし、eventBus パターンで登録する必要があり、load() 内で直接呼び出すことはできません。ensureLoaded() は load() の後にすべての collection をクリアして再設定するためです。完全な例は フロントエンドとバックエンドが連動するデータ管理プラグインを作る を参照してください。

#リソース（Resource）の自動生成

Collection を定義すると、NocoBase は対応する REST API リソースを自動的に生成します。CRUD インターフェース（list、get、create、update、destroy）はすぐに使える状態で、追加のコードは不要です。組み込みの CRUD 操作では足りない場合――例えば「一括インポート」や「集計」インターフェースが必要な場合――は、resourceManager でカスタム action を登録できます。詳細は ResourceManager リソース管理 を参照してください。

#関連リンク

• Database データベース — CRUD、Repository、トランザクションとデータベースイベント
• DataSourceManager データソース管理 — 複数データソースとその Collection の管理
• Migration データマイグレーション — プラグインアップグレード時のデータ移行スクリプト
• Plugin プラグイン — プラグインクラスのライフサイクル、メンバーメソッドと app オブジェクト
• ResourceManager リソース管理 — カスタム REST API と操作ハンドラー
• フロントエンドとバックエンドが連動するデータ管理プラグインを作る — defineCollection + addCollection の完全な例
• プロジェクトディレクトリ構造 — src/server/collections ディレクトリの規約説明