> ## 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 Этот раздел объясняет, как подключиться к базе данных ClickHouse Botslovers, либо через прямой доступ HTTP (например, используя `curl`), либо через графические инструменты и инструменты бизнес-аналитики, такие как DBeaver, Power BI или Tableau. ### Доступ через HTTP (пример с использованием curl) Вы можете получить доступ к данным, выполняя SQL-запросы непосредственно к базе данных ClickHouse через ее HTTP-интерфейс. **Базовый пример:** Для извлечения первых 10 записей из таблицы `messages_<компания>`: ```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** * Скачайте и установите официальный драйвер ODBC ClickHouse. * Настройте DSN ODBC, указывающий на: * Host: `public-clickhouse.botslovers.com` * Порт: `443` (или `8443` в зависимости от конфигурации, проверьте у администратора) * Режим SSL: включен * Имя пользователя/Пароль: ваши учетные данные * В Power BI создайте новый источник данных ODBC и выберите настроенный DSN. **Tableau** * Вы можете использовать драйвер ODBC ClickHouse как в Power BI. * В качестве альтернативы используйте собственный коннектор 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 | Полное содержимое текста сообщения. Может включать текст, эмодзи, email, ID и т.д.
**Примечание:** Может быть `null` для изображений или документов. | | `language` | String | Код языка (например, `"ru"`, `"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 или другие детали о продуктах или услугах, предлагаемых вашей компанией. Эти записи не были анонимизированы или псевдонимизированы для сохранения полного контекста каждого разговора и обеспечения точности анализа. Необходимо обрабатывать эти данные в соответствии с применимыми нормативами, всегда поддерживая конфиденциальность, безопасность и права субъектов данных.