1. Главная
  2. Хаб
  3. Сценарии
  4. Поток событий из Kafka в ClickHouse: интеграция, таблица Kafka и материализованное представление

Сценарий 28

Поток событий из Kafka в ClickHouse: интеграция, таблица Kafka и материализованное представление

Подключаем управляемый ClickHouse к Managed Kafka без паролей в SQL: платформа сама заводит именованную коллекцию с адресами и учётными данными. Дальше — таблица на движке Kafka, материализованное представление и аналитика по заказам через секунды после события.

40 минСредний7 шагов Kafka, ClickHouse обновлено

Содержание
  1. 01Подготовьте Kafka: топик и пользователя для ClickHouse
  2. 02Создайте ClickHouse в той же сети
  3. 03Заведите пользователя и базу для потока
  4. 04Создайте интеграцию с Kafka
  5. 05Подключитесь к ClickHouse с сервера
  6. 06Создайте таблицу Kafka, хранилище и материализованное представление
  7. 07Отправьте события и посмотрите аналитику
  8. Проверка результата
  9. Как удалить ресурсы
  10. Типичные ошибки
  11. Сколько стоит

Что получится

ClickHouse 26.8 в той же VPC, что и Kafka; интеграция orders_kafka; таблица shop.orders, в которую события из топика orders попадают сами; агрегаты по выручке, которые обновляются в реальном времени.

Что понадобится

  • Кластер Kafka с топиком orders и сервер в той же сети — например, из сценария «События между микросервисами» в разделе Kafka. Можно начать и с пустого проекта: шаги ниже создают всё нужное.
  • CLI h3 с API-ключом проекта (h3 init): пользователи и интеграции ClickHouse настраиваются через API.
  • Сервер в сети проекта для SQL-клиента: ClickHouse без публичного IP доступен только из VPC.
  1. Шаг 1. Подготовьте Kafka: топик и пользователя для ClickHouse

    Если кластера ещё нет: Базы данных → Создать базу данных → СУБД Kafka, Брокеры «1 брокер», vCPU 1, RAM 2 ГБ, Диски 10 ГБ, Имя базы данных events → Создать базу данных.

    ClickHouse будет читать топик от своего пользователя с правом только на чтение, поэтому его права не пересекаются с правами сервисов.

    Консоль

    1. В карточке кластера Kafka в разделе «Топики» нажмите Создать топик: Имя топика orders, Партиции 3 → Создать (если топика ещё нет).
    2. В разделе «Пользователи» нажмите Создать пользователя: Имя пользователя clickhouse, Доступ — «Только чтение», Топики orders → Создать.
    3. Запишите Логин из окна «Пользователь создан», например clickhouse-1a2b3c4d. Пароль ClickHouse возьмёт сам — копировать его не нужно.

    CLI

    Терминал
    h3 db topic create <id Kafka> --name orders --partitions 3
    echo '{"name":"clickhouse","grants":[{"database":"orders","preset":"readonly"}]}' | h3 db user create <id Kafka> --from-file -
    h3 db user list <id Kafka>     # логин с суффиксом — в колонке имени

    Проверка

    В таблице «Пользователи» есть логин clickhouse-… с доступом «Только чтение» на orders.

  2. Шаг 2. Создайте ClickHouse в той же сети

    Интеграция работает только между базами одного проекта и одной VPC. Публичный IP не нужен: ClickHouse читает Kafka по внутренним адресам, а SQL-клиент работает с сервера в сети проекта.

    Консоль

    1. Базы данных → Создать. СУБД — ClickHouse 26.8. vCPU — 2, RAM — 4 ГБ (минимум для ClickHouse), Диски — 20 ГБ.
    2. Имя базы данных — analytics. Сеть — та же, что у Kafka. Публичный IP оставьте выключенным.
    3. Нажмите Создать базу данных.

    CLI

    Терминал
    h3 db create --name analytics --engine clickhouse --version 26.8 --cpu 2 --memory 4Gi --size 20
    h3 db get <id ClickHouse> -o json    # internalIP — адрес в VPC

    Проверка

    Статус — «Работает». В блоке «Подключение» на вкладке «Внутри VPC» — Адрес в VPC: запишите его.

  3. Шаг 3. Заведите пользователя и базу для потока

    Права в ClickHouse выдаются пресетом на базу: readonly, readwrite или admin. Пользователь etl будет владельцем базы shop (пресет admin: таблицы, представления, словари) и получит доступ к интеграции. Встроенному пользователю app интеграции не выдаются.

    CLI

    Терминал
    h3 db user create <id ClickHouse> --name etl          # сохраните пароль из ответа
    h3 db database create <id ClickHouse> --name shop --owner etl
    h3 db user list <id ClickHouse>

    Проверка

    У пользователя etl в доступе — shop с пресетом admin, статус «READY». Пароль можно посмотреть снова: h3 db user credentials <id ClickHouse> etl.

    Если не получилось

    • INVALID_NAME — имена пользователей и баз ClickHouse: латинские строчные буквы, цифры и _, начинаются с буквы или _. Дефис недопустим.
  4. Шаг 4. Создайте интеграцию с Kafka

    Интеграция — именованная коллекция ClickHouse с адресами брокеров, логином, паролем и сертификатом CA кластера Kafka. Платформа берёт пароль из своих записей, в запросах и ответах его нет, а пользователи из grantTo могут коллекцией пользоваться, но не могут её прочитать или подменить адрес.

    CLI

    Терминал
    h3 api POST /api/databases/v1/<id ClickHouse>/integrations -d '{
      "name": "orders_kafka",
      "kind": "kafka",
      "sourceDatabaseId": "<id Kafka>",
      "user": "<логин clickhouse-…>",
      "grantTo": ["etl"]
    }'
    h3 api GET /api/databases/v1/<id ClickHouse>/integrations

    Проверка

    Интеграция orders_kafka в статусе READY.

    Если не получилось

    • 409 SOURCE_NOT_REACHABLE — Kafka в другой сети: интеграция работает только в пределах одной VPC проекта.
    • UNKNOWN_USER — пользователя нет в /users ClickHouse. Встроенный app сюда не подходит, нужен созданный пользователь.
    • Ошибка авторизации Kafka при чтении — в user указано имя без суффикса. Нужен логин целиком.
  5. Шаг 5. Подключитесь к ClickHouse с сервера

    Подключение — только по TLS: нативный протокол на порту 9440, HTTPS — 8443. Сертификат сервера подписан CA платформы «h3llo Managed Databases CA» и содержит имя db.h3llo.cloud. Поэтому сопоставим это имя с адресом базы в /etc/hosts и включим строгую проверку.

    Скачайте в карточке ClickHouse Скачать сертификат CA (файл h3llo-db-ca.pem) и скопируйте его на сервер.

    На сервере
    echo "<адрес в VPC> db.h3llo.cloud" | sudo tee -a /etc/hosts
    curl https://clickhouse.com/ | sh            # скачает один файл ./clickhouse
    cat > ch.xml <<'EOF'
    <config>
      <openSSL><client>
        <loadDefaultCAFile>false</loadDefaultCAFile>
        <caConfig>/home/user/h3llo-db-ca.pem</caConfig>
        <verificationMode>strict</verificationMode>
        <invalidCertificateHandler><name>RejectCertificateHandler</name></invalidCertificateHandler>
      </client></openSSL>
    </config>
    EOF
    ./clickhouse client --config-file ch.xml --secure --host db.h3llo.cloud --port 9440 \
      --user etl --password '<пароль etl>' --database shop --query 'SELECT version()'

    Проверка

    Команда печатает версию 26.8.

    Если не получилось

    • certificate verify failed — указан не тот файл CA (у Kafka свой CA, он здесь не подходит) или путь в caConfig неверный.
    • Подключение висит — сервер в другой сети: ClickHouse без публичного IP доступен только из VPC проекта.
  6. Шаг 6. Создайте таблицу Kafka, хранилище и материализованное представление

    Таблица на движке Kafka ничего не хранит. Она работает как курсор потребителя: каждое чтение из неё забирает новые сообщения. Поэтому данные складывают в обычную таблицу MergeTree, а перекладывает их материализованное представление — оно срабатывает на каждую пачку сообщений.

    В Kafka(orders_kafka, …) передаются только топик, группа и формат: адрес и учётные данные зафиксированы в интеграции.

    schema.sql
    CREATE TABLE shop.orders_queue
    (
        order_id UInt64,
        user_id  UInt64,
        amount   Decimal(12, 2),
        ts       UInt32
    )
    ENGINE = Kafka(orders_kafka,
                   kafka_topic_list = 'orders',
                   kafka_group_name = 'clickhouse-orders',
                   kafka_format = 'JSONEachRow');
    
    CREATE TABLE shop.orders
    (
        order_id   UInt64,
        user_id    UInt64,
        amount     Decimal(12, 2),
        created_at DateTime
    )
    ENGINE = MergeTree
    PARTITION BY toYYYYMM(created_at)
    ORDER BY (created_at, order_id);
    
    CREATE MATERIALIZED VIEW shop.orders_mv TO shop.orders AS
    SELECT order_id, user_id, amount, toDateTime(ts) AS created_at
    FROM shop.orders_queue;
    Как выполнить
    ./clickhouse client --config-file ch.xml --secure --host db.h3llo.cloud --port 9440 \
      --user etl --password '<пароль etl>' --database shop --queries-file schema.sql

    Проверка

    Через несколько секунд в shop.orders появляются заказы, которые уже лежали в топике (группа новая, чтение с начала):

    Терминал
    ./clickhouse client --config-file ch.xml --secure --host db.h3llo.cloud --port 9440 \
      --user etl --password '<пароль etl>' --query 'SELECT count(), sum(amount) FROM shop.orders'

    Если не получилось

    • ACCESS_DENIED … NAMED COLLECTION — пользователь не указан в grantTo. Добавьте его: h3 api PUT /api/databases/v1/<id ClickHouse>/integrations/orders_kafka/grants -d '{"grantTo":["etl"]}'.
    • Сообщения не появляются, в system.kafka_consumers появляются ошибки разбора — формат события не совпал со схемой. Для JSONEachRow имена полей JSON должны совпадать с колонками таблицы Kafka.
    • Не делайте SELECT из orders_queue вручную: прочитанные сообщения уйдут из потока и не попадут в orders.
  7. Шаг 7. Отправьте события и посмотрите аналитику

    Отправьте несколько заказов продюсером из раздела Kafka или прямо через kcat с пользователем, у которого есть право записи в orders.

    Тестовое событие
    echo '{"order_id":1001,"user_id":7,"amount":1990.00,"ts":'"$(date +%s)"'}' | \
      kcat -P -b "<адреса брокеров>" -X security.protocol=SASL_SSL -X sasl.mechanisms=SCRAM-SHA-512 \
        -X sasl.username="<логин с правом записи>" -X sasl.password="<пароль>" -X ssl.ca.location=$HOME/kafka-ca.crt -t orders
    Выручка по минутам
    SELECT toStartOfMinute(created_at) AS minute, count() AS orders, sum(amount) AS revenue
    FROM shop.orders
    WHERE created_at > now() - INTERVAL 1 HOUR
    GROUP BY minute ORDER BY minute;

    Проверка

    Новое событие видно в shop.orders через секунды после отправки.

Проверка результата

Поток работает сам: группа clickhouse-orders читает топик, а таблица растёт. Состояние потребителя видно в системной таблице:

Терминал
./clickhouse client --config-file ch.xml --secure --host db.h3llo.cloud --port 9440 --user etl --password '<пароль etl>' \
  --query "SELECT database, table, num_messages_read, last_exception FROM system.kafka_consumers FORMAT Vertical"

Как удалить ресурсы

Удаление базы ClickHouse удаляет её данные. Kafka и топик при этом не меняются.

CLI

Терминал
h3 db delete <id ClickHouse>
h3 db user delete <id Kafka> <логин clickhouse-…>
  1. Сначала остановите поток: DROP VIEW shop.orders_mv; DROP TABLE shop.orders_queue;.
  2. Удалите интеграцию: h3 api DELETE /api/databases/v1/<id ClickHouse>/integrations/orders_kafka.
  3. Базы данных → analytics → меню «…» → Удалить. При необходимости удалите и пользователя clickhouse в Kafka.

Типичные ошибки

Можно ли просто указать адрес Kafka и пароль в `ENGINE = Kafka(...)`?

Нет: табличные функции и прямые адреса пользователям не выдаются. К Kafka, PostgreSQL и S3 ClickHouse подключается только через интеграции — так пароли не попадают в DDL, журналы запросов и руки аналитиков.

Как ускорить чтение большого топика?

Добавьте `kafka_num_consumers` (не больше числа партиций топика) и увеличьте число партиций в Kafka. Для ClickHouse с репликами создавайте таблицы с `ON CLUSTER c` и `ReplicatedMergeTree()`.

Что будет с событиями, пока ClickHouse остановлен?

Они остаются в топике в пределах срока хранения (по умолчанию 7 дней). После запуска группа продолжит чтение с сохранённого смещения.

Сколько интеграций можно создать?

До 20 на базу ClickHouse. Одна интеграция Kafka годится для любого числа топиков, на которые у пользователя Kafka есть права.

Связанные продукты и материалы

Сколько стоит

≈ 8,03 ₽ в час · 5 778 ₽ в месяц при работе 24/7

vCPU ClickHouse2 × 1 035 ₽
RAM ClickHouse, ГБ4 × 414 ₽
Диск ClickHouse до 20 000 IOPS*, ГБ20 × 14,40 ₽
vCPU брокера Kafka1 × 900 ₽
RAM брокера Kafka, ГБ2 × 360 ₽
Диск брокера до 20 000 IOPS*, ГБ10 × 14,40 ₽

Интеграции отдельно не оплачиваются. Сервер для SQL-клиента в расчёт не входит: подойдёт уже существующий. Трафик внутри VPC бесплатен.

Цены из прайс-листа, по которому работает биллинг; списание поминутное, месяц — 720 часов. Если удалить ресурсы после проверки, сценарий обойдётся в рубли.

Новым пользователям — 4 000 ₽ на 30 дней на любые сервисы: бонуса хватит, чтобы попробовать этот сценарий целиком. Бонус начисляется после подтверждения телефона и привязки карты.

* IOPS растут с объёмом диска; точные значения для вашего объёма видны в консоли при выборе.