> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovi.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# データ構造ドキュメント
> データベースから生データを抽出する公式ドキュメント
# データベースから生データを抽出する公式ドキュメント
このドキュメントは、企業が利用可能な主要なデータ構造へのアクセスと説明を提供することを目的としており、適切な統合、管理、分析を容易にし、記録で見つかる可能性のある個人データの責任ある取り扱いに関する推奨事項と警告を含みます。
各テーブルの構造を説明するだけでなく、現在のプライバシーと情報セキュリティ規制の遵守の重要性を強調し、データベースの安全で適切な使用を確保するために、各フィールド定義と個人データの取り扱いに関する注意事項を慎重に確認することを推奨します。
提示されたデータは生であり、未処理です。
## ClickHouse から HTTP と BI ツール経由でデータにアクセスする
このセクションでは、Botslovers ClickHouse データベースへの接続方法を説明します。直接 HTTP アクセス（例: `curl` を使用）またはグラフィカルツールとビジネスインテリジェンスツール（DBeaver、Power BI、Tableau など）経由です。
### HTTP 経由でのアクセス（curl を使用した例）
ClickHouse データベースに対して直接 SQL クエリを実行してデータにアクセスできます。
**基本例：**
`messages_` テーブルから最初の 10 件のレコードを取得：
```bash theme={null}
curl -u user:'password' 'https://public-clickhouse.botslovers.com/?query=SELECT%20*%20FROM%20messages_company%20LIMIT%2010'
```
`user` と `password` を個人の資格情報に置き換えてください。
パラメータ `query` は URL エンコードする必要があります。
**レスポンス形式：**
デフォルトでは、レスポンスは TabSeparated 形式です。クエリの最後に `FORMAT` を追加することで他の形式をリクエストできます：
**JSON 例：**
```bash theme={null}
curl -u user:'password' "https://public-clickhouse.botslovers.com/?query=SELECT%20*%20FROM%20messages_company%20LIMIT%2010%20FORMAT%20JSON"
```
**CSV 例：**
```bash theme={null}
curl -u user:'password' "https://public-clickhouse.botslovers.com/?query=SELECT%20*%20FROM%20messages_company%20LIMIT%2010%20FORMAT%20CSV"
```
### BI ツールまたはデータベースクライアントからのアクセス（DBeaver、Power BI、Tableau など）
ClickHouse は JDBC および ODBC コネクタをサポートしており、グラフィカルツールを使用してデータを探索および分析できます。
#### DBeaver からのアクセス
* DBeaver を開き、新しい接続を作成します。
* データベースタイプとして ClickHouse を選択します。
* 接続タイプとして HTTP を選択します。
* 以下のフィールドを入力します：
* Host: `public-clickhouse.botslovers.com`
* ポート: `443`
* ユーザー: あなたのユーザー名
* パスワード: あなたのパスワード
* SSL: 有効（ボックスがチェックされていることを確認）
* 接続をテストして保存します。
#### BI ツールからのアクセス（Power BI、Tableau など）
**Power BI**
* 公式 ClickHouse ODBC ドライバーをダウンロードしてインストールします。
* 以下のポイントを指す ODBC DSN を構成します：
* Host: `public-clickhouse.botslovers.com`
* ポート: `443`（構成によっては `8443`、管理者に確認）
* SSL モード: 有効
* ユーザー名/パスワード: あなたの資格情報
* Power BI で新しい ODBC データソースを作成し、構成された DSN を選択します。
**Tableau**
* Power BI の場合と同じように ClickHouse ODBC ドライバーを使用できます。
* または、ネイティブ ClickHouse コネクタを使用します。
## セキュリティとベストプラクティス
* あなたの資格情報は個人的なもので、共有しないでください。
* 使用制限やデータ構造に関する質問がある場合は、管理者に相談してください。
* 潜在的なサービスパフォーマンス問題を防ぐために、大量のデータを抽出するクエリを避けることを推奨します。
## テーブル
### `messages`
各会話で生成された個々のメッセージが保存される中央リポジトリとして機能します。このドキュメントは、そのフィールド、目的、機密データを安全に管理するための具体的な推奨事項を詳述します。
### `agent_activity`
参加するエージェント（人間または自動化）の関連情報を集中させるテーブル。これにより、各エージェントのイベントとメトリクスを関連付け、個々のアクティビティ分析、主要指標計算（例: 応答時間、セッションクロージャ、エージェント可用性）、転送が発生する場合でも会話全体でのアクションのトレーサビリティを容易にします。
## テーブル記述
### `messages`（テーブル: `messages_`）
会話中に交換された各メッセージを保存します。
| フィールド | タイプ | 説明 |
| ------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `sender_id` | String | 各メッセージを特定のエンティティにリンクする一意の送信者識別子。 |
| `sender_type` | String | メッセージの起源: `"user"`、`"bot"`、`"system"`、または `"human"`。 |
| `id` | String | 重複検出を保証する各メッセージの一意のキー。 |
| `created_at` | DateTime | メッセージが生成されたときの UTC タイムスタンプ。 |
| `channel` | String | メッセージが送信されたチャネル: `"whatsapp"` または `"web"`（ウィジェット）。 |
| `session` | String | 複数のメッセージをグループ化する会話識別子。 |
| `direction` | String | メッセージの方向: `"inbound"` または `"outbound"`。 |
| `type` | String | コミュニカティブタイプ: `"inbound"`（受信）または `"outbound"`（送信）。 |
| `text` | String | メッセージの完全なフリーテキストコンテンツ。テキスト、絵文字、メール、ID などを含む場合があります。
**注意:** 画像またはドキュメントの場合は `null` になる可能性があります。 |
| `language` | String | 言語コード（例: `"ja"`、`"en"`）。
**注意:** 検出されない場合は `null` になる可能性があります。 |
### `agent_activity`（テーブル: `chat_agent_log_`）
エージェントがチャットと対話する際に発生するイベントを記録します。
| フィールド | タイプ | 説明 |
| ----------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | String | 一意のイベント識別子。 |
| `chat_id` | String | 関連するチャットの識別子。 |
| `agent_id` | String | イベントに関与する一意のエージェント識別子。 |
| `joined_at` | DateTime | エージェントがチャットに参加した UTC タイムスタンプ。 |
| `left_at` | Nullable(DateTime) | エージェントがチャットを離れた UTC タイムスタンプ、またはまだアクティブな場合は `null`。 |
| `event` | String | イベントのタイプ。可能な値: `bot_assigned`、`agent_timeout`、`user_timeout`、`agent_joined`、`chat_escalated`、`manual_close`、`resolved`、`assigned_to_human`、`transferred`。 |
| `response_rating` | Nullable(Int16) | 存在する場合、インタラクションに与えられた評価。 |
| `created_at` | DateTime | レコード作成タイムスタンプ。 |
| `updated_at` | DateTime | レコードの最終更新タイムスタンプ。 |
| `deleted_at` | Nullable(DateTime) | 該当する場合の論理削除タイムスタンプ。 |
### `agent_status_logs`（テーブル: `agent_status_logs_`）
エージェントのステータス変更の履歴を時間の経過とともに追跡します。例えば、"online" から "break" への移行。
| フィールド | タイプ | 説明 |
| ------------------- | --------------- | --------------------------------------------------------------------------------- |
| `id` | String | 一意のステータス変更識別子。 |
| `agent_id` | String | 一意のエージェント識別子。 |
| `old_status` | String | エージェントの以前のステータス: `training`、`offline`、`break`、`ending_shift`、`inactive`、`online`。 |
| `new_status` | String | エージェントの新しいステータス: `training`、`offline`、`break`、`ending_shift`、`inactive`、`online`。 |
| `status_changed_at` | DateTime | ステータスが変更された UTC タイムスタンプ。 |
| `duration_seconds` | Nullable(Int64) | 以前のステータスの秒単位の期間、該当しない場合は `null`。 |
| `created_at` | DateTime | レコード作成タイムスタンプ。 |
## 個人データの取り扱い
`messages_` テーブル、特に `text` 列は、顧客のインタラクションの完全な内容を保持し、会社の提供する製品やサービスに関する名前、電子メールアドレス、ID 番号などの個人データを潜在的に含みます。
これらの記録は、会話の完全な文脈を維持し、分析の正確性を確保するために匿名化または擬似匿名化されていません。
適用される規制に従ってこれらのデータを処理し、常に機密性、安全性、およびデータ主体の権利を維持することが**必須**です。