> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

# エンティティの作成

> Base44 エンティティはプロジェクト内でローカルに定義され、Base44 バックエンドにプッシュされます。

<Warning>
  このページは AI コーディングエージェントスキルの一部で、人間ではなくエージェント向けに書かれています。人間向けの Base44 ドキュメントは [デベロッパードキュメント](/developers) を参照してください。
</Warning>

# エンティティの作成

Base44 エンティティはプロジェクト内でローカルに定義され、Base44 バックエンドにプッシュされます。

## 重要: ファイル命名

エンティティファイルは kebab-case 命名を使用する必要があります: `{kebab-case-name}.jsonc`

| エンティティ名       | ファイル名                |
| ------------- | -------------------- |
| `Task`        | `task.jsonc`         |
| `TeamMember`  | `team-member.jsonc`  |
| `ActivityLog` | `activity-log.jsonc` |

誤: `TeamMember.jsonc`, `teamMember.jsonc`
正: `team-member.jsonc`

## 目次

* [エンティティの作成](#creating-entities)
  * [エンティティディレクトリ](#entity-directory)
  * [エンティティの作成方法](#how-to-create-an-entity)
  * [エンティティスキーマ構造](#entity-schema-structure)
  * [サポートされるフィールド型](#supported-field-types)
  * [フィールドプロパティ](#field-properties)
  * [完全な例](#complete-example)
  * [命名規則](#naming-conventions)
  * [エンティティ間のリレーション](#relationships-between-entities)
  * [行レベルセキュリティ (RLS)](#row-level-security-rls)
  * [フィールドレベルセキュリティ (FLS)](#field-level-security-fls)
  * [エンティティのプッシュ](#pushing-entities)

## エンティティディレクトリ

すべてのエンティティ定義はプロジェクトルートの `base44/entities/` フォルダーに配置する必要があります。各エンティティは独自の `.jsonc` ファイルで定義されます。

構造の例:

```
my-app/
  base44/
    entities/
      user.jsonc
      product.jsonc
      order.jsonc
```

## エンティティの作成方法

1. `base44/entities/` ディレクトリに新しい `.jsonc` ファイルを作成します
2. 以下の構造に従ってエンティティスキーマを定義します
3. CLI を使用して変更を Base44 にプッシュします

## エンティティスキーマ構造

各エンティティファイルは JSON Schema に似た構造に従います:

```jsonc theme={null}
{
  "name": "EntityName",       // PascalCase entity name
  "type": "object",           // Always "object"
  "properties": {
    // Define your fields here
  },
  "required": ["field1"]      // Array of required field names
}
```

### よくある間違い: ネストされた schema プロパティ

**誤** - プロパティを `schema` オブジェクトでラップしないでください:

```jsonc theme={null}
{
  "name": "Task",
  "description": "A task entity",
  "schema": {                    // ❌ WRONG - don't use nested "schema"
    "type": "object",
    "properties": { ... }
  }
}
```

**正** - `type` と `properties` をトップレベルに配置します:

```jsonc theme={null}
{
  "name": "Task",
  "description": "A task entity",
  "type": "object",              // ✅ CORRECT - top level
  "properties": { ... }          // ✅ CORRECT - top level
}
```

これはよくある間違いで、エンティティをプッシュするときに "Invalid schema: Schema must have a 'type' field" エラーが発生します。

## サポートされるフィールド型

### 文字列

基本的なテキストフィールド:

```jsonc theme={null}
{
  "title": {
    "type": "string",
    "description": "Task title"
  }
}
```

フォーマット付き:

```jsonc theme={null}
{
  "due_date": {
    "type": "string",
    "format": "date",
    "description": "Due date"
  }
}
```

利用可能なフォーマット: `date`, `date-time`, `time`, `email`, `uri`, `hostname`, `ipv4`, `ipv6`, `uuid`, `file`, `regex`, `richtext`

### Enum 付き文字列

特定の値に制約:

```jsonc theme={null}
{
  "status": {
    "type": "string",
    "enum": ["todo", "in_progress", "done"],
    "default": "todo",
    "description": "Current status"
  }
}
```

### 数値

```jsonc theme={null}
{
  "position": {
    "type": "number",
    "description": "Position for ordering"
  }
}
```

### 整数

整数のみ:

```jsonc theme={null}
{
  "quantity": {
    "type": "integer",
    "description": "Item quantity",
    "minimum": 0,
    "maximum": 1000
  }
}
```

### バイナリ

ファイル/BLOB データ用:

```jsonc theme={null}
{
  "attachment": {
    "type": "binary",
    "description": "File attachment"
  }
}
```

### 真偽値

```jsonc theme={null}
{
  "notify_on_change": {
    "type": "boolean",
    "default": true,
    "description": "Enable notifications"
  }
}
```

### 文字列の配列

```jsonc theme={null}
{
  "labels": {
    "type": "array",
    "items": { "type": "string" },
    "description": "Task labels/tags"
  }
}
```

### オブジェクトの配列

```jsonc theme={null}
{
  "attachments": {
    "type": "array",
    "description": "File attachments",
    "items": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "url": { "type": "string" },
        "type": { "type": "string" }
      }
    }
  }
}
```

## フィールドプロパティ

| プロパティ         | 説明                                                                                                                       |
| ------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `type`        | データ型: `string`, `number`, `integer`, `boolean`, `array`, `object`, `binary`                                              |
| `description` | フィールドの人間可読な説明                                                                                                            |
| `enum`        | 許可される値の配列 (文字列用)                                                                                                         |
| `enumNames`   | enum 値の人間可読なラベル (`enum` と同じ順序)                                                                                           |
| `default`     | 提供されない場合のデフォルト値                                                                                                          |
| `format`      | フォーマットのヒント: `date`, `date-time`, `time`, `email`, `uri`, `hostname`, `ipv4`, `ipv6`, `uuid`, `file`, `regex`, `richtext` |
| `items`       | 配列アイテムのスキーマ                                                                                                              |
| `properties`  | オブジェクト型のネストされたプロパティ                                                                                                      |
| `$ref`        | 別のスキーマ定義への参照                                                                                                             |
| `minLength`   | 最小文字列長                                                                                                                   |
| `maxLength`   | 最大文字列長                                                                                                                   |
| `pattern`     | 文字列検証用の正規表現パターン                                                                                                          |
| `minimum`     | 数値の最小値                                                                                                                   |
| `maximum`     | 数値の最大値                                                                                                                   |
| `rls`         | フィールドレベルセキュリティルール (Field Level Security セクションを参照)                                                                        |

## 完全な例

Task の完全なエンティティ定義:

```jsonc theme={null}
{
  "name": "Task",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Task title"
    },
    "description": {
      "type": "string",
      "description": "Task description"
    },
    "status": {
      "type": "string",
      "enum": ["todo", "in_progress", "done"],
      "default": "todo",
      "description": "Current status of the task"
    },
    "board_id": {
      "type": "string",
      "description": "Board this task belongs to"
    },
    "assignee_email": {
      "type": "string",
      "description": "Email of assigned user"
    },
    "priority": {
      "type": "string",
      "enum": ["low", "medium", "high"],
      "default": "medium",
      "description": "Task priority"
    },
    "due_date": {
      "type": "string",
      "format": "date",
      "description": "Due date"
    },
    "labels": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Task labels/tags"
    }
  },
  "required": ["title"]
}
```

## 命名規則

* **エンティティ名**: 英数字のみの PascalCase を使用 (例: `Task`, `TeamMember`, `ActivityLog`)
  * パターン `/^[a-zA-Z0-9]+$/` に一致する必要があります
  * 有効: `Task`, `TeamMember`, `Order123`
  * 無効: `Team_Member`, `Team-Member`, `Team Member`
* **ファイル名**: エンティティに一致する kebab-case を使用 (例: `task.jsonc`, `team-member.jsonc`, `activity-log.jsonc`)
* **フィールド名**: snake\_case を使用 (例: `board_id`, `user_email`, `due_date`)

## エンティティ間のリレーション

エンティティ間のリレーションを作成するには、ID 参照フィールドを使用します:

```jsonc theme={null}
{
  "board_id": {
    "type": "string",
    "description": "Board this task belongs to"
  },
  "team_id": {
    "type": "string",
    "description": "Associated team ID"
  }
}
```

## 行レベルセキュリティ (RLS)

行レベルセキュリティ (RLS) は、ユーザーの ID と属性に基づいてユーザーがアクセスできるレコードを制御します。RLS ルールはスキーマの `rls` フィールド内でエンティティごとに定義されます。

**重要:** RLS が定義されていない場合、すべてのレコードがすべてのユーザーからアクセス可能です。

### RLS 操作

RLS は 5 つの操作をサポートします:

| 操作       | 説明                                    |
| -------- | ------------------------------------- |
| `create` | 新しいレコードを追加できるユーザーを制御                  |
| `read`   | レコードを閲覧できるユーザーを制御                     |
| `update` | レコードを変更できるユーザーを制御                     |
| `delete` | レコードを削除できるユーザーを制御                     |
| `write`  | `create`、`update`、`delete` を組み合わせた短縮形 |

### 権限値

各操作は以下のいずれかの値を受け入れます:

1. **`true`** - すべてのユーザーを許可 (匿名/未認証を含む)
2. **`false`** - すべてのユーザーをブロック
3. **条件オブジェクト** - 条件に一致するユーザーを許可

### テンプレート変数

現在のユーザーの属性を参照するにはテンプレート変数を使用します:

| テンプレート                     | 説明                            |
| -------------------------- | ----------------------------- |
| `{{user.id}}`              | ユーザーの ID                      |
| `{{user.email}}`           | ユーザーのメールアドレス                  |
| `{{user.role}}`            | ユーザーのロール                      |
| `{{user.data.field_name}}` | ユーザーの `data` オブジェクトのカスタムフィールド |

### 組み込みエンティティ属性

すべてのエンティティレコードには、RLS ルールで使用できる以下の組み込み属性があります:

| 属性             | 説明                    |
| -------------- | --------------------- |
| `id`           | 一意のレコード識別子            |
| `created_date` | レコード作成時のタイムスタンプ       |
| `updated_date` | レコードが最後に更新されたタイムスタンプ  |
| `created_by`   | レコードを作成したユーザーのメールアドレス |

### ルールタイプ

使用できる条件タイプは 2 種類あります:

**1. Entity-to-user comparison** - レコードフィールドを現在のユーザーの値と比較:

```jsonc theme={null}
{
  "created_by": "{{user.email}}"
}
```

**2. User condition check** - `user_condition` を使用して直接ユーザープロパティをチェック:

```jsonc theme={null}
{
  "user_condition": { "role": "admin" }
}
```

**重要な注意事項:**

* `user_condition` は **単純な等価性のみ** サポート (例: `{ "role": "admin" }`)
* **エンティティフィールドのフィルタリングには `data.` プレフィックスが必要:** エンティティフィールド値でフィルタするには `{ "data.fieldname": value }` を使用
* `data.*` フィールドの比較では演算子を使用可能: `$in`, `$nin`, `$ne`, `$all`
* 条件を組み合わせるための論理演算子 `$or`, `$and`, `$nor` が利用可能

⚠️ **高度な RLS パターンと例については、[rls-examples.md](https://docs.base44.com/developers/skills/base44-cli/references/rls-examples.md) を参照してください**

### RLS の例

**所有者のみアクセス:**

```jsonc theme={null}
{
  "created_by": "{{user.email}}"
}
```

**部門ベースのアクセス:**

```jsonc theme={null}
{
  "data.department": "{{user.data.department}}"
}
```

**管理者のみアクセス:**

```jsonc theme={null}
{
  "user_condition": { "role": "admin" }
}
```

**完全な RLS 構成:**

```jsonc theme={null}
{
  "name": "Task",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Task title"
    },
    "status": {
      "type": "string",
      "enum": ["todo", "in_progress", "done"],
      "default": "todo"
    }
  },
  "required": ["title"],
  "rls": {
    "create": true,
    "read": { "created_by": "{{user.email}}" },
    "update": { "created_by": "{{user.email}}" },
    "delete": { "created_by": "{{user.email}}" }
  }
}
```

### 一般的な RLS パターン

**公開作成、管理者のみ管理 (例: 問い合わせフォーム、ウェイトリスト):**

```jsonc theme={null}
{
  "rls": {
    "create": true,
    "read": { "user_condition": { "role": "admin" } },
    "update": { "user_condition": { "role": "admin" } },
    "delete": { "user_condition": { "role": "admin" } }
  }
}
```

**所有者のみアクセス:**

```jsonc theme={null}
{
  "rls": {
    "create": true,
    "read": { "created_by": "{{user.email}}" },
    "update": { "created_by": "{{user.email}}" },
    "delete": { "created_by": "{{user.email}}" }
  }
}
```

**ログイン済みユーザーのみ:**

```jsonc theme={null}
{
  "rls": {
    "create": { "user_condition": { "id": "{{user.id}}" } },
    "read": true,
    "update": { "created_by": "{{user.email}}" },
    "delete": { "created_by": "{{user.email}}" }
  }
}
```

### 制限事項

* **user\_condition は等価性のみ:** `user_condition` は完全一致のみサポート (例: `{ "role": "admin" }`) - 演算子はサポートされません
* **user\_condition で比較演算子は使用不可:** `$gt`, `$lt`, `$regex`, `$expr`, `$where` はユーザー条件でサポートされません
* **深くネストされたテンプレートは不可:** `{{user.data.profile.department}}` のようなテンプレートは動作しない場合があります

**サポートされる演算子:**

* **論理演算子:** 複数条件を組み合わせるための `$or`, `$and`, `$nor`
* **フィールド演算子 (`data.*` フィールドのみ):** `$in`, `$nin`, `$ne`, `$all`
* **エンティティフィールドフィルタリング:** エンティティフィールド値でフィルタするには `data.` プレフィックスを使用 (例: `{ "data.status": "published" }` または `{ "data.completed": true }`)

⚠️ **包括的な RLS パターンと例については [rls-examples.md](https://docs.base44.com/developers/skills/base44-cli/references/rls-examples.md) を参照してください**

### 複雑なアクセスパターン

複数の条件を必要とする複雑なアクセスパターン (例: 「所有者 OR 管理者」) の場合、2 つの選択肢があります:

1. **Base44 ダッシュボード UI を使用** - ダッシュボードでは操作ごとに複数のルールを OR ロジックで追加できます
2. **別のエンティティを使用** - データを異なるアクセスルールを持つ複数のエンティティに分割
3. **バックエンド関数を使用** - バックエンド関数でカスタムアクセスロジックを実装

## フィールドレベルセキュリティ (FLS)

フィールドレベルセキュリティを使用すると、エンティティ内の個々のフィールドへのアクセスを制御できます。FLS ルールは、各フィールドのスキーマ内で `rls` プロパティを使用して定義されます。

### FLS 操作

FLS はエンティティレベル RLS と同じ操作をサポートします:

| 操作       | 説明                                    |
| -------- | ------------------------------------- |
| `create` | レコード作成時にこのフィールドを設定できるユーザーを制御          |
| `read`   | このフィールドを閲覧できるユーザーを制御                  |
| `update` | このフィールドを変更できるユーザーを制御                  |
| `delete` | このフィールドをクリアできるユーザーを制御                 |
| `write`  | `create`、`update`、`delete` を組み合わせた短縮形 |

### FLS の例

```jsonc theme={null}
{
  "name": "Employee",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Employee name"
    },
    "salary": {
      "type": "number",
      "description": "Employee salary",
      "rls": {
        "read": { "user_condition": { "role": "hr" } },
        "update": { "user_condition": { "role": "hr" } }
      }
    },
    "department": {
      "type": "string",
      "description": "Department name"
    }
  },
  "required": ["name"]
}
```

この例では、`hr` ロールを持つユーザーのみが `salary` フィールドを読み取り/更新できます。エンティティにアクセスできるすべてのユーザーは他のフィールドを読み取り/更新できます。

### FLS の注意事項

* フィールドレベル RLS が定義されていない場合、フィールドはエンティティレベル RLS ルールを継承します
* FLS ルールはエンティティレベル RLS と同じ条件フォーマットに従います
* salary、SSN、内部メモなどの機密フィールドには FLS を使用します

## エンティティのプッシュ

`entities push` コマンドは `base44/entities` フォルダーに存在するすべてのエンティティをプッシュします。

```bash theme={null}
npx base44 entities push
```

push コマンドの詳細は [entities-push.md](https://docs.base44.com/developers/skills/base44-cli/references/entities-push.md) を参照してください。

<Note>このページは AI を使用して翻訳されました。最も正確で最新の情報については、[英語版](/) を参照してください。 </Note>