ClickHouse Client, INSERT INTO и первые SELECT-запросы

После запуска ClickHouse первый рабочий цикл выглядит так: подключиться через clickhouse-client, создать таблицу, вставить данные через INSERT INTO и выполнить SELECT с фильтрацией и агрегацией. В этом уроке пройдем весь путь на маленьком наборе событий

Как открыть clickhouse-client

Если ClickHouse запущен в Docker, откройте клиент внутри контейнера:

docker exec -it clickhouse-server clickhouse-client

Если ClickHouse установлен пакетами на Linux, обычно достаточно команды:

clickhouse-client

Проверьте соединение:

SELECT version(), currentDatabase();

Создаем учебную таблицу

CREATE DATABASE IF NOT EXISTS demo;
CREATE TABLE IF NOT EXISTS demo.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 INTO VALUES

INSERT INTO demo.events VALUES
('2026-05-19', '2026-05-19 10:00:00', 101, 'view', 0),
('2026-05-19', '2026-05-19 10:01:00', 101, 'cart', 0),
('2026-05-19', '2026-05-19 10:02:00', 101, 'purchase', 990),
('2026-05-19', '2026-05-19 10:03:00', 102, 'view', 0),
('2026-05-20', '2026-05-20 12:00:00', 103, 'purchase', 1490);

Для учебного примера VALUES удобен. В реальной загрузке лучше отправлять данные пачками: тысячи или десятки тысяч строк за одну вставку. ClickHouse оптимизирован под большие batch-вставки, а не под поток одиночных строк

Первые SELECT-запросы

SELECT *
FROM demo.events
ORDER BY event_time
LIMIT 10;

Фильтр по дате:

SELECT user_id, event_type, amount
FROM demo.events
WHERE event_date = '2026-05-19'
ORDER BY event_time;

Агрегация по типу события:

SELECT
    event_type,
    count() AS events,
    sum(amount) AS revenue
FROM demo.events
GROUP BY event_type
ORDER BY events DESC;

Условные счетчики

Для отчетов часто нужны отдельные счетчики по условиям. В ClickHouse удобно использовать countIf и sumIf

SELECT
    event_date,
    countIf(event_type = 'view') AS views,
    countIf(event_type = 'purchase') AS purchases,
    sumIf(amount, event_type = 'purchase') AS revenue
FROM demo.events
GROUP BY event_date
ORDER BY event_date;

Загрузка из файла коротко

Для реальных данных часто используют CSV, TSV, Parquet или JSONEachRow. Пример с JSONEachRow:

cat events.jsonl | clickhouse-client \
  --query="INSERT INTO demo.events FORMAT JSONEachRow"

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

Частые ошибки

• Открыли не ту базу. Используйте полный путь demo.events или команду USE demo.
• Путаете порты. clickhouse-client обычно использует native protocol, а HTTP-драйверы — порт 8123.
• Делаете слишком маленькие вставки. Для ClickHouse лучше пачки, а не одиночные строки.
• Дата не парсится. Проверяйте формат YYYY-MM-DD и YYYY-MM-DD HH:MM:SS.
• Ожидаете мгновенных транзакционных обновлений. ClickHouse рассчитан на аналитическую загрузку.

Полезные режимы вывода

clickhouse-client умеет выводить результат в разных форматах. Это удобно, когда нужно передать результат дальше в скрипт или быстро посмотреть таблицу глазами

SELECT * FROM demo.events FORMAT PrettyCompact;
SELECT * FROM demo.events FORMAT JSONEachRow;
SELECT * FROM demo.events FORMAT CSVWithNames;

Для человека удобны Pretty-форматы, для пайплайнов — JSONEachRow, CSV, TSV или Parquet. Не привязывайте автоматизацию к визуальному табличному выводу: он предназначен для чтения, а не для надежного парсинга

Как безопасно тестировать INSERT

• Сначала вставьте 3-5 строк руками и проверьте типы.
• Затем загрузите небольшой файл на 100-1000 строк.
• Проверьте count(), минимальные и максимальные даты.
• Только после этого запускайте полную загрузку.
• Если данные критичны, пишите в новую таблицу и переименовывайте ее после проверки.

Что еще настроить перед реальными вставками

Когда учебный INSERT пора заменить batch-загрузкой?

Как только данные приходят регулярно: события приложения, логи, выгрузки из очереди или CSV-файлы. Одиночные вставки удобны для проверки синтаксиса, но рабочий пайплайн лучше строить пачками и с заранее выбранными типами данных ClickHouse

Что делать, если SELECT уже работает, но отчетов мало?

Добавьте условные агрегаты: countIf, sumIf, argMax, dateDiff. Они позволяют собрать несколько метрик одним проходом по данным; подробные примеры есть в уроке Функции ClickHouse: countIf, sumIf, argMax, dateDiff, if и multiIf

Когда переходить к Python или BI-инструментам?

После того как вручную проверены таблица, вставка и базовый SELECT. Тогда ошибки подключения легче отличить от ошибок схемы. Для следующего шага подойдет материал ClickHouse и Python: clickhouse-connect, JDBC, ODBC и Power BI