# Salebot: как работает коннектор

В этой статье вы узнаете, как коннектор Salebot выгружает данные в хранилище ROMI center: что именно попадает в таблицу, с какой периодичностью идёт сбор и какие у этого есть особенности. Полный список полей — в статье [Salebot: описание выгружаемых полей](https://help-ru.romi.center/salebot-opisanie-vygruzhaemyh-polej).

## Что выгружается: клиенты бота и их переменные

Коннектор забирает из Salebot клиентов проекта и для каждого — значения переменных, перечисленных в настройках. Таблица одна, строка в ней — один клиент.

> **Важно**
> Переменные читаются один раз — когда коннектор впервые видит клиента. На бою от половины до трёх четвертей клиентов попадают в сбор в первые 10 минут после появления, остальные — позже, иногда через несколько часов. Значения, которые бот запишет после этого, и любые дальнейшие изменения в таблицу не попадают. Освежить их можно только перезагрузкой с удалением данных.

> **Важно**
> Клиент, у которого в момент сбора не заполнена ни одна из выбранных переменных, пропускается насовсем: коннектор к нему больше не возвращается. Переменная `client_id` из набора по умолчанию есть не у всех: у одного из подключений на бою — у 15% собранных клиентов. Поле клиента `platform_id` заполнено у каждого — с ним пропусков не будет.

Клиенты, удалённые в Salebot, остаются в таблице: коннектор только добавляет строки. Списки клиентов Salebot выгружаются не отдельными таблицами, а колонкой `lists` той же таблицы.

## Периодичность

Коннектор собирает новых клиентов из Salebot каждые 10 минут, не больше 300 клиентов за проход, и отправляет собранное в хранилище каждые 2 минуты. За переменными каждого нового клиента коннектор ходит отдельным запросом, так что проход в 300 клиентов — это около 300 запросов к Salebot. Если запрос упал, курсор дальше этого клиента не сдвигается и следующий проход начинает с него же: данные не теряются, а приходят позже.

> **Примечание**
> «Приостановить выгрузку» останавливает сбор новых клиентов; уже собранные строки всё равно доедут до хранилища.

## За какой период забираются данные

Периода у коннектора нет. Salebot отдаёт клиентов по порядку появления — от самого старого к самому новому, — и коннектор идёт по этому списку курсором: счётчиком уже обработанных клиентов.

Новое подключение забирает всю базу клиентов, начиная с самого первого: 300 — сразу при сохранении, дальше по 300 каждые 10 минут, до 43 200 в сутки. В обычной работе забираются клиенты, появившиеся с предыдущего прохода.

## Как сохраняет данные

*   **Куда:** хранилище ROMI center на движке ClickHouse.
*   **Запись в две стадии.** Сначала клиент со всеми полями ложится в промежуточную таблицу ROMI, затем отдельная задача переносит выбранные переменные в хранилище.
*   **Имя таблицы:** `salebot_<название подключения латиницей>_<id подключения>`.
*   **Структура таблицы:** движок `MergeTree`, без разбиения на партиции, ключ сортировки — `id` (номер клиента в Salebot).
*   **Строка на клиента.** Строка ищется по `id`. Найденная удаляется и вставляется заново, а `rc_created_at` переносится со старой.
*   **Структура догоняется, а не пересоздаётся.** Новая переменная приходит новой колонкой. Колонки никогда не удаляются: убранная переменная останется в таблице со старыми значениями, а новые строки будут писаться в неё пустыми. Смена имени переменной даёт новую колонку, прежняя перестаёт заполняться.

> **Важно**
> Недоставленные строки не повторяются. Если в момент отправки хранилище помечено ошибкой доступа или запись не удалась, строки больше не отправляются, а курсор уже ушёл дальше. Вернуть таких клиентов может только перезагрузка с удалением данных.

## Перезагрузка данных

Функция «Загрузить исторические данные» в меню подключения не учитывает выбранный период: коннектор одним проходом, без лимита в 300, дособирает всех клиентов после курсора. Уже выгруженных клиентов не перечитывает.

> **Важно**
> Галочка «Удалить ранее загруженные данные за период» удаляет таблицу целиком, стирает промежуточные данные подключения и обнуляет курсор — вся база клиентов перечитывается одним проходом с самого первого, со свежими значениями переменных. Это единственный способ обновить переменные уже выгруженных клиентов.

## Дополнительные настройки

| Настройка | Что делает |
| --- | --- |
| Токен и название | Шаг «Доступ»: API-токен проекта Salebot и название подключения, по умолчанию «SaleBot». Название входит в имя таблицы и после создания не меняется. |
| Переменные клиента | Шаг «Выбор полей»: список переменных — имя как в Salebot, подпись и тип. В новом подключении заранее заведены `client_id` и пять UTM-меток. |
| Списки клиентов | Шаг «Дополнительные настройки»: номера списков Salebot. Номера списков, в которых состоит клиент, пишутся в колонку `lists` его строки — отдельных таблиц под списки нет. |

Смена переменных действует для клиентов, которых коннектор соберёт после сохранения. Уже выгруженные клиенты получат новые переменные только после перезагрузки с удалением данных.

## Технические поля

| Колонка | Что внутри |
| --- | --- |
| `rc_created_at` | Когда строка клиента впервые записана в таблицу. При повторной записи переносится со старой. |

В предпросмотре данных служебные колонки скрыты — они отрезаются по префиксу `rc_`.