ClickHouse и Python: clickhouse-connect, JDBC, ODBC и Power BI

ClickHouse редко живет сам по себе: к нему подключаются Python-скрипты, backend-сервисы, BI-инструменты, Java-приложения и ETL-пайплайны. В этом уроке главный фокус на Python-библиотеке clickhouse-connect, а в конце разберем, где появляются JDBC, ODBC и Power BI

Какие порты использовать

Если локальный ClickHouse запущен через Docker с пробросом -p 8123:8123, Python-клиенту обычно нужен host localhost и port 8123

Установка clickhouse-connect

pip install clickhouse-connect

Для проекта лучше ставить пакет в виртуальное окружение, чтобы версии библиотек не конфликтовали с системным Python

Первое подключение из Python

import clickhouse_connect
client = clickhouse_connect.get_client(
    host='localhost',
    port=8123,
    username='default',
    password=''
)
result = client.query('SELECT version()')
print(result.result_set)

Если ClickHouse в Cloud или за HTTPS, параметры будут другими: host сервиса, порт HTTPS, пользователь, пароль и secure-соединение. Не хардкодьте пароли в коде, берите их из переменных окружения или секретов

query: получить данные

rows = client.query('''
    SELECT event_type, count() AS events
    FROM demo.events
    GROUP BY event_type
    ORDER BY events DESC
''')
for row in rows.result_set:
    print(row)

command: выполнить DDL или запрос без результата

client.command('CREATE DATABASE IF NOT EXISTS demo')
client.command('''
    CREATE TABLE IF NOT EXISTS demo.python_events
    (
        event_date Date,
        event_time DateTime,
        user_id UInt64,
        event_type LowCardinality(String),
        amount Decimal(12, 2)
    )
    ENGINE = MergeTree
    ORDER BY (event_date, event_type, user_id)
''')

insert: вставка пачки строк

client.insert(
    'demo.python_events',
    [
        ['2026-05-19', '2026-05-19 10:00:00', 101, 'view', 0],
        ['2026-05-19', '2026-05-19 10:01:00', 101, 'purchase', 990],
    ],
    column_names=['event_date', 'event_time', 'user_id', 'event_type', 'amount']
)

Как и в обычном ClickHouse, лучше вставлять данные пачками. Python-цикл, который отправляет по одной строке на каждый запрос, быстро станет узким местом

JDBC для Java и JVM-инструментов

JDBC нужен Java-приложениям, Spark/ETL-инструментам и части BI-систем. В Java-проектах драйвер подключают как Maven/Gradle-зависимость, а соединение задают строкой вида jdbc:ch:http://host:8123 или через HTTPS-адрес Cloud-сервиса

Проверяйте совместимость версии драйвера, протокол, TLS и параметры пользователя. Ошибка "connection refused" часто означает не проблему SQL, а неправильный host/port или закрытый firewall

ODBC и Power BI

ODBC чаще нужен на Windows и для BI-инструментов, включая Power BI. Здесь типовые проблемы такие: установлен не тот драйвер, выбран неверный DSN, пользователь не имеет прав на базу, локальный ClickHouse слушает только внутри контейнера или порт не проброшен наружу

Частые ошибки подключения

• Неверный порт. HTTP-клиент идет на 8123, native-клиент — на 9000.
• Контейнер не пробросил порт. Проверьте docker ps и секцию ports в Compose.
• Пароль пустой локально, но обязателен в Cloud. Не переносите локальные настройки в production.
• TLS включен, а клиент идет по HTTP. Для Cloud обычно нужен secure/HTTPS.
• Типы не совпали при insert. Дата, Decimal и Nullable требуют аккуратной подготовки данных.

Переменные окружения вместо паролей в коде

Даже в учебном проекте лучше привыкать не хранить пароль прямо в Python-файле. Используйте переменные окружения: так код можно положить в репозиторий без секретов

import os
import clickhouse_connect
client = clickhouse_connect.get_client(
    host=os.getenv('CLICKHOUSE_HOST', 'localhost'),
    port=int(os.getenv('CLICKHOUSE_PORT', '8123')),
    username=os.getenv('CLICKHOUSE_USER', 'default'),
    password=os.getenv('CLICKHOUSE_PASSWORD', '')
)

Как проверять интеграцию перед bulk insert

• Сначала выполните SELECT version().
• Затем выполните DESCRIBE TABLE для целевой таблицы.
• Вставьте две строки с явным column_names.
• Проверьте count() и несколько последних строк.
• Только после этого запускайте большую пачку.

Такой порядок экономит время. Большинство проблем с ClickHouse-интеграцией проявляются до большой загрузки: неверный порт, права, типы колонок, формат даты или порядок полей

Что проверить перед подключением BI и приложений

Почему сначала стоит проверить запрос в clickhouse-client?

Так вы отделяете проблему драйвера от проблемы SQL, прав и схемы. Если запрос не работает в клиенте, Python или Power BI его не исправят. Базовый порядок проверки есть в уроке ClickHouse Client, INSERT INTO и первые SELECT-запросы

Что чаще всего ломает insert из приложения?

Порядок колонок, формат даты, Nullable, Decimal и массивы. Перед bulk insert полезно явно передать column_names и свериться с материалом Типы данных ClickHouse

Когда нужен отдельный слой витрин для BI?

Когда BI-инструмент каждый раз гоняет тяжелые JOIN и агрегаты по сырым событиям. В таком случае лучше подготовить таблицы под чтение, а для повторяемых расчетов посмотреть Materialized View в ClickHouse