> ## 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.

# 数据结构文档

> 从数据库提取原始数据的官方文档

# 从数据库提取原始数据的官方文档

本文档旨在提供对公司可用的主要数据结构的访问和描述，以便于适当的集成、管理和分析与交互和参与代理相关的信息。

除了描述每个表的结构之外，它还包括关于负责任处理可能在记录中发现的个人数据的建议和警告，并强调遵守当前隐私和信息安全法规的重要性。

我们建议在开始任何集成或分析过程之前仔细审查每个字段定义和处理个人数据的注释，以确保数据库的安全和适当使用。

<Warning>
  呈现的数据是原始的和未处理的。
</Warning>

## 通过 HTTP 和 BI 工具访问 ClickHouse 中的数据

本节解释如何连接到 Botslovers ClickHouse 数据库，无论是通过直接 HTTP 访问（例如使用 `curl`）还是通过图形工具和商业智能工具，如 DBeaver、Power BI 或 Tableau。

### 通过 HTTP 访问（使用 curl 的示例）

您可以通过直接针对 ClickHouse 数据库执行 SQL 查询来访问数据。

**基本示例：**

要从 `messages_<company>` 表中检索前 10 条记录：

```bash theme={null}
curl -u user:'password' 'https://public-clickhouse.botslovers.com/?query=SELECT%20*%20FROM%20messages_company%20LIMIT%2010'
```

将 `user` 和 `password` 替换为您的个人凭据。

<Note>
  参数 `query` 必须进行 URL 编码。
</Note>

**响应格式：**

默认情况下，响应采用 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_<company>`）

存储在对话期间交换的每条消息。

| 字段            | 类型       | 描述                                                                 |
| ------------- | -------- | ------------------------------------------------------------------ |
| `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 等。<br />**注意：** 对于图像或文档可能为 `null`。 |
| `language`    | String   | 语言代码（例如 `"zh"`、`"en"`）。<br />**注意：** 如果未检测到，可能为 `null`。            |

### `agent_activity`（表：`chat_agent_log_<company>`）

记录代理与聊天交互期间发生的事件。

| 字段                | 类型                 | 描述                                                                                                                                                   |
| ----------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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_<company>`）

跟踪代理状态随时间的变化历史，例如从"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 号码或您的公司提供的产品的其他细节。

<Warning>
  这些记录尚未匿名化或伪匿名化，以保留每个对话的完整上下文并确保分析准确性。
</Warning>

必须根据适用的法规处理这些数据，始终维护机密性、安全性和数据主体的权利。