データベース

スキーマを通してデータベースの構造を定義します。

テーブル

テーブルはデータを保存するための入れ物です。
Excelのように行と列で構成され、行はレコード、列はカラムと呼ばれます。
以下のテーブルは4つのカラムを持ち、3つのレコードが保存されています。

id	name	description	color
1	Apple	It is said, “An apple a day keeps the doctor away.”	red
2	Orange	Born in the Assam region of India.	orange
3	Grape	It is said that there are more than 1,000 varieties of grapes in the world.	purple

テーブルを設計する際には、カラムの定義が重要です。カラムによってテーブルのデータ構造が決まります。

スキーマでは、以下のようにテーブルを定義します。columns プロパティでカラムの定義を行います。カラムを定義する際は type プロパティでデータ型を指定します。

orizm.config.ts

import { defineConfig } from "@orizm/cli/config";
 
export default defineConfig({
  tables: {
    blog: {
      columns: {
        title: {
          type: "string",
        },
        body: {
          type: "string",
        },
      },
    },
  },
});

データ型

以下のデータ型を使用できます。

string
number
boolean
json
reference
module
module-array
storage

string

テキストデータを扱う際に使用します。

以下のオプションが設定できます。

オプション	説明	型	デフォルト
required	必須項目であることを示します。	boolean	false
readonly	読み取り専用であることを示します。	boolean	false
pattern	正規表現を用いて文字列のパターンを指定します。	string	-
minLength	文字列の最小長を指定します。	number	-
maxLength	文字列の最大長を指定します。	number	-
default	デフォルト値を指定します。	string	-

{
  type: "string",
  required: true,
  readOnly: true,
  pattern: "^[a-zA-Z]+$",
  minLength: 1,
  maxLength: 255,
  default: "default value",
}

TypeScriptの型は string です。

number

数値データを扱う際に使用します。

以下のオプションが設定できます。

オプション	説明	型	デフォルト
required	必須項目であることを示します。	boolean	false
readonly	読み取り専用であることを示します。	boolean	false
default	デフォルト値を指定します。	number	-

{
  type: "number",
  required: true,
  readOnly: true,
  default: 0,
}

TypeScriptの型は number です。

boolean

真偽値を扱う際に使用します。

以下のオプションが設定できます。

オプション	説明	型	デフォルト
required	必須項目であることを示します。	boolean	false
readonly	読み取り専用であることを示します。	boolean	false
default	デフォルト値を指定します。	boolean	-

{
  type: "boolean",
  required: true,
  readOnly: true,
  default: false,
}

TypeScriptの型は boolean です。

json

JSONデータを扱う際に使用します。

以下のオプションが設定できます。

オプション	説明	型	デフォルト
required	必須項目であることを示します。	boolean	false
readonly	読み取り専用であることを示します。	boolean	false
default	デフォルト値を指定します。	object	-

{
  type: "json",
  required: true,
  readOnly: true,
  default: {},
}

TypeScriptの型は unknown です。
定形データを扱う場合は、より型安全に扱うことのできる module や module-array の利用も検討してください。

reference

他のテーブルのレコードを参照するためのデータ型です。リレーショナルデータベースにおける外部キーのように使用されます。

以下のプロパティを設定する必要があります。

オプション	説明	型
tableName	参照するテーブルの名前を指定します。	string
includeName	参照先のレコードにアクセスするためのプロパティ名を指定します。	string
onDelete	参照先のレコードが削除された際の挙動を指定します。	“cascade” \| “set null” \| “restrict”

reference型のカラムではSDKを利用してデータを取得する際に include プロパティを使用して参照先のデータを結合することができます。includeName で参照先のデータにアクセスするためのプロパティ名を指定します。これにより参照先のデータを取得する際に、より直感的な名前でアクセスできます。

例えば以下のようにカラムを定義した場合、authorId で著者IDにアクセスできます。includeName で author と指定しているため、 include している場合は author で著者のデータにアクセスできます。

/*
 * テーブル定義
 *
 * article: {
 *   columns: {
 *     authorId:{
 *       type: "reference",
 *       tableName: "author",
 *       onDelete: "set null",
 *       includeName: "author",
 *     }
 *   }
 * }
 */
 
const data = client.tables.article.get(articleId, {
  include: {
    author: true,
  },
});
 
// data.authorId で author の ID にアクセス可能
console.log(data.authorId);
// data.author で author のデータにアクセス可能
console.log(data.author);

onDelete プロパティは以下の値から選択できます。

cascade: 参照先のレコードが削除された際、自身のレコードも削除します。
set null: 参照先のレコードが削除された際、カラムの値を null に設定します。
restrict: 参照先のレコードの削除を拒否し、エラーとして処理します。

reference型のカラムには以下のオプションが設定できます。

オプション	説明	型	デフォルト
required	必須項目であることを示します。onDelete が “set null” の場合、true にはできません。	boolean	false
readonly	読み取り専用であることを示します。	boolean	false

{
  type: "reference",
  tableName: "referenceTable",
  onDelete: "cascade",
  required: true,
  readOnly: true,
  includeName: "refCol",
}

TypeScriptの型は、string | undefined になり、参照先レコードのIDが格納されます。
includeName で指定したプロパティは、参照先のテーブルの型(T)を持つ T | undefined になります。

module

テーブルモジュールをカラムに対して 1:1 の関係で紐づける際に使用します。詳細はテーブルモジュールを参照してください。

以下のプロパティを設定する必要があります。

オプション	説明	型
moduleName	モジュールの名前を指定します。	string

{
  type: "module",
  moduleName: "moduleA",
}

TypeScriptの型は、テーブルモジュールのカラム定義に従った型になります。

module-array

テーブルモジュールをカラムに対して 1:N の関係で紐づける際に使用します。詳細はテーブルモジュールを参照してください。

以下のプロパティを設定する必要があります。

オプション	説明	型
moduleName	モジュールの名前を指定します。	string

{
  type: "module-array",
  moduleName: "moduleA",
}

TypeScriptの型は、テーブルモジュールのカラム定義に従った型を持つ配列になります。

storage

ファイルを扱う際に使用します。

storage型カラムとバケットはファイルを扱う点で似ていますが異なる点があります。バケットはシンプルなファイル置き場であるのに対し、storage型カラムはファイルをレコードに紐づけて扱います。例えば、ブログ記事にサムネイル画像を設定する場合、storage型カラムを使用して画像ファイルをレコードに紐づけることができます。

レコードが削除された場合、ファイルは30日後に自動で削除されます。削除前であれば、編集履歴の管理機能を利用して復元することも可能です。

以下のオプションが設定できます。

オプション	説明	型	デフォルト
readonly	読み取り専用であることを示します。	boolean	false

{
  type: "storage",
  readOnly: true,
}

TypeScriptの型は StorageItemType です。

type StorageItemType = {
  /**
   * ストレージアイテムを一意に識別するための識別子です。
   * アップロードAPIから取得したハンドルをテーブルに書き込むことでリンクが確立され、
   * アクセス可能なURLが発行されます。このフィールドは書き込み専用です。
   */
  handle?: string | null;
  /**
   * ストレージアイテムの公開URLです。
   * 一般公開用に認証なしでアクセス可能なURLが発行されます。
   */
  _publicUrl?: string;
  /**
   * ストレージアイテムの保護されたURLです。
   * API呼び出し元に対して署名されたURLです。
   */
  _protectedUrl?: string;
  _attributes?: {
    /** ファイルサイズ */
    size: number;
    /** ファイルのMIMEタイプ */
    type: string;
    /** 画像の横幅。画像の場合のみ設定されます。 */
    width?: number;
    /** 画像の縦幅。画像の場合のみ設定されます。 */
    height?: number;
  };
};

storage型カラムにファイルを紐づけるにはCMS SDKを使用します。
詳細は storage型カラムにデータを保存を参照してください。

予約カラム

以下のカラムは自動でテーブルに追加されます。

id

レコードを一意に識別するためのIDです。

ランダムな16文字の英数字で構成されます。（例: MlKtexCT1v8CS4pR）

id には自動でインデックスが作成されます。

createdAt

レコードが作成された日時です。

ISO 8601 形式の文字列で構成されます。（例: 2025-01-01T00:00:00.000Z）

updatedAt

レコードが更新された日時です。

ISO 8601 形式の文字列で構成されます。（例: 2025-01-01T00:00:00.000Z）

group

レコードの所属するグループです。権限の設定に使用します。

任意の文字列を設定できます。デフォルトは undefined です。

インデックス

インデックスはデータの検索速度を向上させるための仕組みです。

⚠️

絞り込みや並び替えの速度が向上する反面、データの追加や更新、削除の速度は低下します。リレーショナルデータベースにおけるインデックス設計の一般的なベストプラクティスに従って、データの操作パターンを考慮して注意深く設計してください。

id カラムには自動でインデックスが作成されるため、追加の設定は不要です。

スキーマでは以下のようにテーブル定義の中で indexes プロパティを利用して設定します。

orizm.config.ts

import { defineConfig } from "@orizm/cli/config";
 
export default defineConfig({
  tables: {
    employee: {
      columns: {
        name: {
          type: "string",
        },
        department: {
          type: "string",
        },
      },
      indexes: [
        {
          columns: ["name"],
        },
        {
          columns: ["department", "name"],
        },
      ],
    },
  },
});

unique

unique プロパティを true にすることで、ユニーク制約を設定できます。

orizm.config.ts

import { defineConfig } from "@orizm/cli/config";
 
export default defineConfig({
  tables: {
    blog: {
      columns: {
        slug: {
          type: "string",
        },
        title: {
          type: "string",
        },
      },
      indexes: [{ columns: ["slug"], unique: true }],
    },
  },
});

高度な機能

テーブルでは以下のような高度な機能を設定できます。

スキーマとはテーブルモジュール