---
pkg: "@nocobase/plugin-collection-sql"
---

# SQL コレクション

## 概要

SQL コレクションは、SQL クエリを使ってデータを取得する強力な方法を提供します。SQL クエリでデータフィールドを抽出し、関連するフィールドのメタデータを設定することで、ユーザーはこれらのフィールドを通常のテーブルと同じように利用できます。この機能は、複雑な結合クエリや統計分析などのシナリオで特に便利です。

## 利用ガイド

### 新規作成

<img src="https://static-docs.nocobase.com/202405191452918.png"/>

1. SQL 入力ボックスに SQL クエリを入力し、「実行 (Execute)」をクリックします。システムは、SQL で使用されているテーブルとフィールドを解析し、ソーステーブルから関連するフィールドのメタデータを自動的に抽出します。

<img src="https://docs.nocobase.com/202405191453556.png"/>

2. システムによるソーステーブルとフィールドの分析が正しくない場合は、手動で適切なテーブルとフィールドを選択し、正しいメタデータが使用されるように調整できます。まずソーステーブルを選択し、次に下のフィールドソースセクションで対応するフィールドを選択してください。

<img src="https://docs.nocobase.com/202405191453579.png"/>

3. 直接的なソースがないフィールドの場合、システムはデータ型に基づいてフィールドタイプを推測します。この推測が正しくない場合は、手動で適切なフィールドタイプを選択できます。

<img src="https://docs.nocobase.com/202405191454703.png"/>

4. 各フィールドを設定しながら、プレビューエリアでその表示をプレビューし、設定の即時的な影響を確認できます。

<img src="https://docs.nocobase.com/202405191455439.png"/>

5. 設定が完了し、すべてが正しいことを確認したら、SQL 入力ボックスの下にある「確認 (Confirm)」ボタンをクリックして、最終的な送信を完了します。

<img src="https://docs.nocobase.com/202405191455302.png"/>

### 編集

1. SQL クエリを変更する必要がある場合は、「変更 (Edit)」ボタンをクリックして、SQL ステートメントを直接変更し、必要に応じてフィールドを再設定します。

2. フィールドのメタデータを調整するには、「フィールド設定 (Configure fields)」オプションを使用します。これにより、通常のテーブルと同じようにフィールド設定を更新できます。

### 同期

SQL クエリは変更されていないが、基になるデータベースのテーブル構造が変更された場合、「フィールド設定 (Configure fields)」-「データベースから同期 (Sync from Database)」を選択することで、フィールドを同期および再設定できます。

<img src="https://docs.nocobase.com/202405191456216.png"/>

### SQL コレクションと接続されたデータベースビューの比較

| テンプレートタイプ | 最適なシナリオ                                                                               | 実装方法   | CRUD 操作のサポート |
| :--- | :--- | :--- | :--- |
| SQL            | シンプルなモデル、軽量なユースケース<br />データベース操作が不便な場合<br />ビューのメンテナンスを避けたい場合<br />UI による操作を完全に希望する場合 | SQL サブクエリ | サポートなし     |
| データベースビューに接続 | 複雑なモデル<br />データベースとの対話が必要な場合<br />データの変更が必要な場合<br />より堅牢で安定したデータベースサポートが必要な場合 | データベースビュー | 部分的にサポート   |

:::warning
SQL コレクションを使用する際は、NocoBase 内で管理可能なデータテーブルを選択してください。同じデータベース内であっても、NocoBase に接続されていない他のテーブルを使用すると、SQL クエリの解析が不正確になる可能性があります。このような要件がある場合は、ビューを作成して接続することを検討してください。
:::