# EMQXエージェントをEMQX Tablesに接続する

EMQX Tablesコネクターを使用すると、エージェントがSQLを通じて時系列データをクエリおよび書き込みできます。このコネクターを利用して、テレメトリ履歴の分析、保存データによるエージェントの意思決定の強化、計算結果のEMQX Tablesへの書き戻しを行えます。

## よくあるユースケース

- アラート送信の判断前に最新のテレメトリをクエリする。
- 最新の計測値を過去の基準値と比較する。
- 異常スコアやメンテナンス結果をテーブルに書き込む。
- EMQX Tablesに保存されたデバイスデータからレポートを作成する。

チャットプロンプトの例：

```text
factory-tablesコネクターを使って、MQTTイベント内のデバイスIDの直近20件の温度データをクエリしてください。平均値を計算し、最終応答に含めてください。
```

## 前提条件

コネクターを追加する前に以下を準備してください：

- EMQX Tablesサービスのアドレス
- 認証が有効な場合はユーザー名とパスワード
- データベース名
- ワークフローで必要なテーブル名とスキーマ
- 最小限のSQL権限を持つデータベースアカウント

## EMQX Tablesコネクターの追加手順

1. 左側のナビゲーションメニューで**Connectors**をクリックします。
2. **Available**タブで**EMQX Tables**を見つけ、**Add**をクリックします。
3. コネクターの各項目を設定します。
4. **Confirm**をクリックします。
5. **Added**タブでコネクターがリストに表示されていることを確認します。

| 項目 | 必須 | 説明 |
|---|---|---|
| **Type** | はい | 選択されたコネクタータイプ、`EMQX Tables`。 |
| **Name** | はい | 表示名（例：`factory-tables`）。 |
| **Address** | はい | `host:port`形式のTablesサービスアドレス。デフォルトポートは`4000`。ポート省略時はEMQXエージェントが`4000`を使用します。 |
| **Username** | いいえ | EMQX Tables認証に使用するユーザー名。 |
| **Password** | いいえ | EMQX Tables認証に使用するパスワード。 |
| **Database Name** | いいえ | 接続するデータベース名。デフォルトは`public`。 |
| **Enable TLS/SSL** | いいえ | 接続にTLSを有効にします。デフォルトは無効。 |

<!-- TODO: 最終的なフィールド順が現在のドキュメントと異なる場合は、agents_add_emqx_tables_connector.pngという名前のサニタイズ済みスクリーンショットを追加してください。 -->

## EMQX Tablesコネクターの編集手順

1. **Added**タブでEMQX Tablesコネクターの編集アイコンをクリックします。
2. コネクターがデプロイ済みエージェントで使用されていない場合、**Edit Connector**パネルで以下の項目を更新できます：
   - **Name**
   - **Address**
   - **Username**
   - **Password**
   - **Database Name**
   - **Enable TLS/SSL**
3. コネクターがデプロイ済みエージェントで使用されている場合は、**Name**のみ更新可能です。
4. **Confirm**をクリックします。

**Type**項目は読み取り専用で変更できません。

::: warning 重要なお知らせ
デプロイ済みエージェントで使用されているコネクターのデータベース名やその他接続設定は、項目が有効になっていても変更しないでください。
:::

## 対応ツール

このコネクターは`tables.sql`ツールを提供します。このツールはSQL文を受け付け、パラメータ、結果の上限、タイムアウトを指定できます。

チャット内でスキーマやサンプル行の確認、SQL検証に使用し、エージェントのデプロイ前に動作確認が可能です。生成されたエージェントは実行時に同じコネクターを使用します。

::: warning 重要なお知らせ
SQL文は接続アカウントに書き込み権限がある場合、データの変更や削除を行う可能性があります。読み取り専用のワークフローには読み取り専用アカウントを使用し、SQLの書き込み操作はデプロイ前に必ず確認してください。
:::

<!-- TODO: ユーザーが確認できる最大行数制限、タイムアウト範囲、およびコンソールで読み取り専用または操作許可リストの制御が可能かどうかを確認してください。 -->

## 権限とセキュリティ

- データベースアカウントには必要なデータベース、スキーマ、テーブルへのアクセス権のみを付与してください。
- エージェントがデータのクエリのみを行う場合は読み取り専用アカウントを使用してください。
- チャットプロンプトやエージェントの指示にユーザー名やパスワードを含めないでください。
- 信頼できないネットワーク経由でEMQX Tablesにアクセスする場合はTLSを使用してください。

## 制限事項

- 無効なSQL、存在しないテーブル、権限不足によりツール呼び出しが失敗します。
- 大量の結果セットはエージェントの処理制限を超える可能性があります。ワークフローで必要な列と行のみをクエリしてください。
- コネクターは設定されたEMQX Tablesアカウントの権限を使用します。

## トラブルシューティング

| 症状 | 対処法 |
|---|---|
| コネクターがEMQX Tablesに接続できない。 | アドレス、ポート、TLS設定、ネットワークアクセスを確認してください。 |
| 認証に失敗する。 | ユーザー名、パスワード、データベースアカウントの状態を確認してください。 |
| クエリが失敗する。 | SQL構文、データベース名、テーブル名、アカウント権限を確認してください。 |
| 結果が切り捨てられるか大きすぎる。 | フィルターを追加するか、列数を減らすか、クエリの上限を下げてください。 |

## 関連リンク

- [Connectors](../connectors.md)
- [Start a Chat](../chats.md)
- [Manage Agents](../agents.md)