> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/ja/build/database/create-database.md).

# データベースの作成と設定

MaiAgent でデータベースを作成・設定する方法を紹介します。ファイルのアップロードによるテーブル作成、外部データベースへの接続、カラム説明の設定を説明します。

MaiAgent の**データベース管理**機能では、Agent が使用するデータベース接続をプラットフォーム上で一元管理できます。Text to SQL と組み合わせることで、Agent は自然言語を使ってデータベース内のデータを直接検索できます。

{% hint style="info" %}
Text to SQL の概要は、[Text to SQL 機能](/maiagent-user-guide/ja/build/database/text2sql.md)を参照してください。
{% endhint %}

MaiAgent は、次の 2 種類のデータベースをサポートしています。

* **MaiAgent データベース**：Excel / CSV / JSON ファイルをアップロードすると、システムが自動でテーブルを作成します。独自のデータベースを持たないユーザーに適しています
* **外部データベース**：既存の PostgreSQL、MySQL、SQL Server（MSSQL）、Oracle、SynxDB データベースに接続します

## ネットワークの事前準備（外部データベース） <a href="#network-prerequisites" id="network-prerequisites"></a>

外部データベースに接続する前に、所属組織の IT 担当者またはデータベース管理者と、次の項目を確認してください。MaiAgent データベースのみを使用する場合（スプレッドシートのアップロード）は、これらの設定は不要です。

* [ ] **MaiAgent からの接続を許可します**：接続は MaiAgent からデータベースに向けて開始されます（「<mark style="color:blue;">接続テスト</mark>」を押したとき、および Agent がクエリを実行するたび）。データベースから MaiAgent への接続は不要です。
* [ ] **接続ポートを開放します**：デフォルトは PostgreSQL 5432、MySQL 3306、SQL Server 1433、Oracle 1521、SynxDB 5432（デプロイ設定によります）です。ポート番号を変更した場合は、「<mark style="color:blue;">接続文字列</mark>」の `ホストアドレス:ポート` に指定した番号を使用します。
* [ ] **MaiAgent クラウドサービス**：データベースにファイアウォールやセキュリティグループがある場合は、MaiAgent の外向き IP アドレスを許可リストに追加し（MaiAgent の担当窓口にお問い合わせください）、上記のポートのみを開放します。
* [ ] **オンプレミス／プライベートクラウドへのデプロイ**：MaiAgent ホストとデータベースホストの間で、ネットワークセグメントとポートが相互に通信できることを確認します。データベースをインターネットに公開する必要はありません。
* [ ] **読み取り専用アカウントを使用します**：MaiAgent 専用の読み取り専用アカウントを作成し、Agent が必要とするテーブルのみへの権限を付与します。個人情報などの機密カラムを含むテーブルでは、必要なカラムだけのビュー（View）を作成して権限を付与することもできます。「<mark style="color:blue;">指定テーブル</mark>」は Agent が参照する範囲を絞る設定であり、実際に読み取れるデータは、このアカウントの権限で決まります。

プラットフォームが書き込み構文をブロックする仕組み、各データベースの読み取り専用保護の程度、ネットワーク要件の詳細は、技術者向けマニュアルの [Text to SQL：読み取り専用保護](https://docs.maiagent.ai/tech/advanced-genai-tech/text-to-sql#read-only)と[ネットワーク要件](https://docs.maiagent.ai/tech/advanced-genai-tech/text-to-sql#network)を参照してください。

## データベースの作成 <a href="#create-database" id="create-database"></a>

### 1. データベース管理ページを開きます <a href="#enter-database-management-page" id="enter-database-management-page"></a>

左側のナビゲーションから「<mark style="color:blue;">AI 機能</mark>」セクションに移動し、「<mark style="color:blue;">データベース</mark>」をクリックします。ページには <mark style="color:blue;">MaiAgent データベース</mark> と <mark style="color:blue;">外部データベース</mark> の 2 つのタブがあります。

右上の「<mark style="color:blue;">データベースを追加</mark>」ボタンをクリックして作成を開始します。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-1679e98bd1aac4aaa4518e438af0f88ac67c34e7%2Fdatabase-list-page.png?alt=media" alt="データベース管理ページ"><figcaption><p>MaiAgent データベースの一覧を表示するデータベース管理ページです</p></figcaption></figure>

{% hint style="info" %}
ボタンがグレー表示でクリックできない場合は、ロールにデータベース作成権限が付与されていません。組織管理者に権限の設定を依頼してください。
{% endhint %}

### 2. データベースの種類を選択します <a href="#select-database-type" id="select-database-type"></a>

作成するデータベースの種類を選び、対応するカードをクリックしてから「<mark style="color:blue;">次へ</mark>」を押します。

* **MaiAgent データベース**：スプレッドシートファイルのアップロードに適しており、接続文字列は不要です
* **PostgreSQL / MySQL / SQL Server / Oracle / SynxDB**：企業の既存の外部データベースに接続します

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-7bfa7cfc7a933807d14941d090f30a8442c0e3af%2Fdatabase-create-select-type.png?alt=media" alt="データベースの種類を選択"><figcaption><p>ステップ 1：データベースの種類を選択します</p></figcaption></figure>

### 3. 基本情報を入力します <a href="#fill-in-basic-info" id="fill-in-basic-info"></a>

#### MaiAgent データベース <a href="#maiagent-database-info" id="maiagent-database-info"></a>

| 項目      | 必須  | 説明                  |
| ------- | --- | ------------------- |
| データベース名 | はい  | 例：「2024 年度売上データ」    |
| 説明      | いいえ | データベースの用途や内容の補足説明です |

{% hint style="info" %}
MaiAgent データベースでは接続文字列の入力は不要です。データの保存はシステムが自動で処理します。作成後にスプレッドシートファイルをアップロードしてください。
{% endhint %}

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-87d0a0885bc2b8454421703e90225a019c1e2b57%2Fdatabase-create-info-maiagent.png?alt=media" alt="MaiAgent データベースの設定"><figcaption><p>ステップ 2：MaiAgent データベースの設定画面です</p></figcaption></figure>

#### 外部データベース <a href="#external-database-info" id="external-database-info"></a>

| 項目      | 必須  | 説明                               |
| ------- | --- | -------------------------------- |
| データベース名 | はい  | 例：「企業 ERP データベース」                |
| 説明      | いいえ | データベースの用途や内容の補足説明です              |
| 接続文字列   | はい  | データベースの接続 URL です                 |
| 指定テーブル  | いいえ | Agent が検索できるテーブルを制限します。カンマで区切ります |

接続文字列の形式は次のとおりです（選択した種類の形式は、項目の下にも表示されます）。

```
PostgreSQL:   postgresql://使用者名稱:密碼@主機位址:連接埠/資料庫名稱
MySQL:        mysql+pymysql://使用者名稱:密碼@主機位址:連接埠/資料庫名稱
SQL Server:   mssql+pyodbc://使用者名稱:密碼@主機位址:連接埠/資料庫名稱?driver=ODBC+Driver+18+for+SQL+Server&TrustServerCertificate=yes&Encrypt=no
Oracle:       oracle+oracledb://使用者名稱:密碼@主機位址:連接埠/?service_name=服務名稱
SynxDB:       postgresql://使用者名稱:密碼@主機位址:連接埠/資料庫名稱
```

{% hint style="danger" %}
接続文字列の形式が正しく、必要な接続情報を含んでいることを必ず確認してください。先頭部分は上記の形式と一致している必要があります。一致しない場合は「接続文字列の形式が正しくありません」と表示され、次のステップに進めません。また、データベースが MaiAgent からの接続を許可していることも確認してください。[ネットワークの事前準備](#network-prerequisites)を参照してください。
{% endhint %}

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-6158a998800e16ec360cd66dc1d0203786acdcf4%2Fdatabase-create-info-external.png?alt=media" alt="外部データベースの設定"><figcaption><p>ステップ 2：外部データベース（PostgreSQL）の設定画面です</p></figcaption></figure>

接続文字列の入力後は、「<mark style="color:blue;">接続テスト</mark>」ボタンで接続が正常か検証することを推奨します（テストを省略して直接保存することもできます）。

* **接続成功**：MaiAgent がデータベースに正常にアクセスできます
* **接続失敗**：接続文字列の形式、アカウントとパスワード、ファイアウォール、許可リスト、ポートが[ネットワークの事前準備](#network-prerequisites)に従って設定されているか確認してください

データベースに多数のテーブルがある場合は、「<mark style="color:blue;">指定テーブル</mark>」に公開するテーブル名（例：`customers, orders, products`）を入力すると、クエリの効率と安全性を高められます。空欄の場合はすべてのテーブルを検索します。

### 4. ロール権限を設定します <a href="#configure-group-permission" id="configure-group-permission"></a>

最後に、このデータベースにアクセスできるロールを設定します。「<mark style="color:blue;">権限範囲のクイック選択</mark>」で、いずれかを選択します。

* <mark style="color:blue;">すべてのロール</mark>：組織内のすべてのロールのメンバーに、このデータベースの利用を許可します
* <mark style="color:blue;">デフォルトロールを除外</mark>：デフォルトロールを除外し、カスタムロールのみ利用を許可します
* <mark style="color:blue;">ロールを個別選択</mark>：特定のロールを手動で選び、権限を付与するロールを「<mark style="color:blue;">選択可能なロール</mark>」から「<mark style="color:blue;">選択済みのロール</mark>」へ移動します

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-370933d45e5081799639a1b310f3f3ae875936a2%2Fdatabase-create-role-permission.png?alt=media" alt="ロール権限の設定"><figcaption><p>ステップ 3：権限範囲のクイック選択です</p></figcaption></figure>

{% hint style="info" %}
今すぐロール権限を設定する必要がない場合は、このステップを省略し、後でデータベース設定ページの「<mark style="color:blue;">ロール権限</mark>」タブで調整できます。
{% endhint %}

### 5. 作成を完了します <a href="#complete-creation" id="complete-creation"></a>

すべての設定を確認したら、「<mark style="color:blue;">データベースを作成</mark>」（MaiAgent データベース）または「<mark style="color:blue;">保存</mark>」（外部データベース）をクリックします。作成に成功すると、データベース設定ページが開き、続けて操作できます。

{% hint style="warning" %}
新しく作成したデータベースは、デフォルトで**無効**です。「<mark style="color:blue;">基本情報</mark>」タブで「<mark style="color:blue;">データベースを有効化</mark>」をオンにして保存するか、データベース一覧の「<mark style="color:blue;">有効</mark>」スイッチを切り替えると、Agent が Text to SQL のクエリでこのデータベースを使用できるようになります。
{% endhint %}

{% hint style="info" %}
作成後は、データベースを **Agent に関連付ける**ことを忘れないでください。関連付けると、Agent がこのデータベースを検索できます。[Agent とグループ権限の関連付け](/maiagent-user-guide/ja/build/database/link-chatbots-groups.md)を参照してください。
{% endhint %}

## ファイルをアップロードしてテーブルを作成します（MaiAgent データベース） <a href="#upload-file-to-create-table" id="upload-file-to-create-table"></a>

MaiAgent データベースの作成後、設定ページで「<mark style="color:blue;">テーブル管理</mark>」タブに切り替え、「<mark style="color:blue;">テーブルファイルをアップロード</mark>」ボタンをクリックします。ファイルを選択するかアップロード領域にドラッグし、「<mark style="color:blue;">アップロード</mark>」をクリックします。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-20335fe758b8e0f9dbd3fd5f1bb89d70b698624a%2Fdatabase-config-table-management.png?alt=media" alt="テーブル管理タブ"><figcaption><p>テーブル管理タブでは、テーブルを元のファイルごとにグループ化して表示します</p></figcaption></figure>

### サポートするファイル形式 <a href="#supported-file-formats" id="supported-file-formats"></a>

| 形式    | 拡張子              | 説明                         |
| ----- | ---------------- | -------------------------- |
| Excel | `.xlsx`、`.xls`   | 各シート（Sheet）から個別のテーブルを作成します |
| CSV   | `.csv`           | カンマ区切りの値を含むファイルです          |
| JSON  | `.json`、`.jsonl` | JSON 形式のデータファイルです          |

アップロード後、システムがバックグラウンドでファイル構造を自動解析し、テーブルを作成します。テーブルは元のファイルごとに表示され、処理状態を確認できます。

| 状態   | 説明                                        |
| ---- | ----------------------------------------- |
| 処理待ち | ファイルはアップロード済みで、処理を待っています                  |
| 処理中  | システムがファイルを解析し、テーブルを作成しています                |
| 成功   | テーブルの作成が完了し、Agent が検索できます                 |
| 失敗   | 作成中にエラーが発生しました。エラーアイコンにマウスを合わせると原因を確認できます |
| 削除中  | バックグラウンドでテーブルを削除しています                     |
| 削除失敗 | 削除が完了していません。もう一度削除できます                    |

元のファイル名の下に「<mark style="color:blue;">ナレッジベースから</mark>」と表示されるテーブルは、ここでアップロードされたものではありません。ナレッジベースに構造化ファイルをアップロードした際に[データベースへ切り替え](/maiagent-user-guide/ja/build/knowledge-base/km.md#table-row-limit)、同期されたものです。同じファイルがナレッジベースとデータベースにそれぞれ存在し、一方を削除しても他方には影響しません。

### テーブル名と再アップロード <a href="#table-naming-and-reupload" id="table-naming-and-reupload"></a>

* テーブル名はシステムが `table_<檔名>_<10 碼雜湊>` の形式で生成します。ファイル名はアップロードしたファイルから拡張子を除き、中国語・英語の文字、数字、アンダースコアのみを残したもので、最大 45 文字です。ハッシュは今回のアップロードのファイル ID とシート名から計算します。例えば `2024 銷售.xlsx` の「Q1」シートをアップロードすると、`table_2024銷售_` に 10 文字のハッシュを付けた名前になります。Agent はクエリ時にこの名前を参照するため、どのファイルのどのシートかを[テーブル説明](#edit-column-description)に記載することを推奨します。
* Excel の各シートから個別のテーブルを作成します。作成に成功したテーブルは、データベースの <mark style="color:blue;">指定テーブル</mark> に自動で追加されます。
* **同じ名前のファイルを再アップロードしても上書きされません**：アップロードごとに新しいファイル ID が割り当てられ、ハッシュも異なるため、別のテーブル群が作成されます。既存のテーブルとカラム説明はそのまま残り、Agent は両方のテーブル群を参照します。データを更新する場合は、<mark style="color:blue;">テーブル管理</mark> で古いテーブル（または元のファイル全体）を削除してから、新しいファイルをアップロードしてください。削除後はカラム説明が残らないため、事前に控えてください。
* ナレッジベースから同期されたテーブル（<mark style="color:blue;">ナレッジベースから</mark> と表示されます）も同じ命名規則を使用します。削除時も、一方の操作は他方に影響しません。

### ファイル形式の注意事項 <a href="#file-format-notes" id="file-format-notes"></a>

* [x] 最初の行（Row）は**カラム名**にしてください
* [x] 各カラムの**データ型**は統一してください（例：価格カラムはすべて数値にします）
* [x] **セルの結合**は避けてください
* [x] **カラム名の重複**は避けてください
* [x] Excel ファイルの各シート（Sheet）には、**一つの表**のみを含めてください

{% hint style="warning" %}
テーブル作成に失敗する主な原因は、ファイル形式の誤りや破損、カラム名の特殊文字、カラム名の重複、同一カラム内のデータ型の不一致です。
{% endhint %}

## カラム説明の編集 <a href="#edit-column-description" id="edit-column-description"></a>

カラム説明は、Text to SQL のクエリ精度を高めるための**重要な設定**です。Agent はカラム説明を参照してデータの意味を理解し、より正確な SQL クエリを生成します。

例えば、テーブルに `status` というカラムがあっても、Agent はその意味を理解できない場合があります。「注文の状態です。値は pending（処理待ち）、completed（完了）、cancelled（キャンセル）のいずれかです」という説明を追加すると、Agent はカラムの意味を正しく理解できます。

### 編集方法 <a href="#how-to-edit" id="how-to-edit"></a>

**MaiAgent データベース**：「<mark style="color:blue;">テーブル管理</mark>」タブで、テーブルの操作欄にある「<mark style="color:blue;">編集</mark>」アイコンをクリックし、「<mark style="color:blue;">テーブル情報を編集</mark>」ウィンドウを開きます。「<mark style="color:blue;">テーブル説明</mark>」と各カラムの「<mark style="color:blue;">カラム説明</mark>」を入力し、「<mark style="color:blue;">保存</mark>」をクリックします。ウィンドウには入力の進捗も表示されます（例：「3 / 10 カラムを設定済み」）。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-55bbc387eb441d873faf95addb67a70ecba7ce0c%2Fdatabase-edit-table-info.png?alt=media" alt="テーブル情報の編集ウィンドウ"><figcaption><p>テーブル情報の編集：テーブル説明とカラム説明を入力します</p></figcaption></figure>

**外部データベース**：「<mark style="color:blue;">基本情報</mark>」タブの下部にある「<mark style="color:blue;">テーブル構造の説明</mark>」セクションで、「<mark style="color:blue;">テーブルを追加</mark>」をクリックします。「<mark style="color:blue;">テーブル名</mark>」と「<mark style="color:blue;">カラムと用途の説明</mark>」を入力し、「<mark style="color:blue;">保存</mark>」をクリックします。

### 記載のヒント <a href="#writing-suggestions" id="writing-suggestions"></a>

{% hint style="info" %}
適切なカラム説明は、AI のクエリ精度を大きく向上させます。
{% endhint %}

| カラム名       | 不十分な説明 | よりよい説明                                                            |
| ---------- | ------ | ----------------------------------------------------------------- |
| `amt`      | 金額     | 注文の合計金額（日本円）です。税金と送料を含みます                                         |
| `cust_lvl` | 等級     | 顧客ランクです。A は年間購入額が 100 万を超える VIP 顧客、B は年間購入額が 10 万〜100 万、C はそれ以外です |
| `reg`      | 地域     | 顧客が所在する地域です。値は北部、中部、南部、東部、離島のいずれかです                               |

## 既存のデータベースの管理 <a href="#manage-existing-databases" id="manage-existing-databases"></a>

### データベースの編集 <a href="#edit-database" id="edit-database"></a>

データベース一覧の操作欄で「<mark style="color:blue;">編集</mark>」アイコンをクリックすると、設定ページが開きます。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-4730481d7efc94106f51933b1d9399496e2a39b8%2Fdatabase-config-basic-info.png?alt=media" alt="データベース設定ページ"><figcaption><p>データベース設定ページ：基本情報タブです</p></figcaption></figure>

設定ページには次のタブがあります。

| タブ                                                 | 説明                                                        | 対象の種類       |
| -------------------------------------------------- | --------------------------------------------------------- | ----------- |
| 基本情報                                               | 名前、説明、有効状態を編集します。外部データベースでは、接続文字列、指定テーブル、テーブル構造の説明も変更できます | すべて         |
| テーブル管理                                             | ファイルのアップロード、テーブルとカラム説明の管理を行います                            | MaiAgent のみ |
| <mark style="color:blue;">関連付けられた AI アシスタント</mark> | このデータベースを使用できる Agent を指定します                               | すべて         |
| ロール権限                                              | ロールのアクセス権限を設定します                                          | すべて         |

{% hint style="info" %}
セキュリティ上の理由から、外部データベースの接続文字列ではパスワードがマスク表示されます。変更する場合は「<mark style="color:blue;">変更</mark>」をクリックし、新しい接続文字列全体を入力してください。
{% endhint %}

### 有効化／無効化 <a href="#enable-disable" id="enable-disable"></a>

データベース一覧の「有効」スイッチで、状態をすばやく切り替えられます。無効にすると、Agent は一時的にこのデータベースを検索できなくなりますが、設定とデータは保持されます。

### データベースの削除 <a href="#delete-database" id="delete-database"></a>

データベース一覧の操作欄で <mark style="color:blue;">削除</mark> をクリックすると、「<mark style="color:blue;">データベースを削除</mark>」確認ウィンドウが開き、「『データベース名』を削除してもよろしいですか？」と表示されます。MaiAgent データベースの場合は、「<mark style="color:blue;">削除前の注意事項</mark>」も表示されます。このデータベースのテーブルはナレッジベースのファイルから同期されている場合があるため、完全に削除したい場合は、ナレッジベースにも併せて削除するファイルがないか確認することを推奨します。削除後は、このデータベースとすべてのテーブルデータを復元できません。外部データベースでは、「削除後、このデータベースの接続設定は復元できません」と表示されます。<mark style="color:blue;">削除を確定</mark> を押すと実行されます。

{% hint style="danger" %}
データベースの削除は元に戻せません。

* **MaiAgent データベース**：アップロードしたファイルから作成されたすべてのテーブルも削除されます。ナレッジベースから同期されたテーブルについては、ナレッジベース側のファイルは残ります
* **外部データベース**：MaiAgent 内の接続設定のみを削除し、元のデータベース内のデータには影響しません
  {% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/ja/build/database/create-database.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.