Настройка среды

В этом уроке мы поднимем локальное ClickHouse-окружение с нуля: запустим single-node кластер через Docker Compose, познакомимся с clickhouse-local для ad-hoc аналитики без сервера, и выполним первые запросы к системным таблицам.

Часть 1: Docker Compose — запуск ClickHouse 26.3

В курсе используется Docker Compose файл из директории labs/single-node/. Если вы клонировали репозиторий курса, файл уже готов. Вот его содержимое:

# labs/single-node/docker-compose.yml
services:
  clickhouse:
    image: clickhouse/clickhouse-server:26.3
    container_name: clickhouse-lab
    ports:
      - "8123:8123"   # HTTP interface
      - "9000:9000"   # Native TCP interface
    ulimits:
      nofile:
        soft: 262144
        hard: 262144
    volumes:
      - clickhouse-data:/var/lib/clickhouse
      - ./exercises:/exercises:ro
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://localhost:8123/?query=SELECT+1 || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

volumes:
  clickhouse-data:

Запуск

# Из директории labs/single-node/
docker compose up -d

Флаг -d запускает контейнер в detached mode (в фоне). Первый запуск займёт 1–2 минуты — Docker скачивает образ clickhouse/clickhouse-server:26.3 (около 400 МБ).

Проверка здоровья контейнера:

docker compose ps
# NAME              IMAGE                               STATUS
# clickhouse-lab    clickhouse/clickhouse-server:26.3   Up (healthy)

Статус (healthy) означает, что ClickHouse прошёл healthcheck (SELECT 1 через HTTP-интерфейс).

Проверка версии

Подключитесь к контейнеру и выполните первый запрос:

docker compose exec clickhouse clickhouse-client --query "SELECT version()"

Ожидаемый вывод:

26.3.x.x

Если вы видите строку, начинающуюся с 26.3 — сервер запущен с правильной версией.

Часть 2: clickhouse-local — аналитика без сервера

clickhouse-local — это отдельный бинарник ClickHouse, который запускается как обычная CLI-программа, без сервера, без Docker, без конфигурации. Это мощный инструмент для:

• Анализа CSV, TSV, JSON, Parquet файлов без импорта в базу
• Одноразовых ad-hoc запросов, которые не нужно хранить
• Локальной разработки и прототипирования
• ETL-скриптов, которые нужно запустить один раз

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

На macOS:

curl https://clickhouse.com/install.sh | sh

На Linux:

curl https://clickhouse.com/install.sh | CLICKHOUSE_VERSION=26.3 sh

После установки бинарник доступен как clickhouse-local или просто clickhouse local.

Первый запрос с clickhouse-local

clickhouse-local --query "SELECT number, number * number AS square FROM system.numbers LIMIT 5"

Вывод:

0	0
1	1
2	4
3	9
4	16

system.numbers — виртуальная таблица, генерирующая бесконечную последовательность целых чисел. Это не файл на диске — генерация происходит “на лету” через специальный table function.

Анализ файла без импорта

Допустим, у вас есть CSV-файл с данными:

echo -e "date,event,user_id\n2026-01-01,login,1\n2026-01-01,purchase,2\n2026-01-02,login,1" > /tmp/events.csv

clickhouse-local --query "
SELECT
    date,
    event,
    count() AS cnt
FROM file('/tmp/events.csv', CSV, 'date Date, event String, user_id UInt32')
GROUP BY date, event
ORDER BY date, cnt DESC
"

Вывод:

2026-01-01	login	1
2026-01-01	purchase	1
2026-01-02	login	1

ClickHouse читает файл напрямую, без создания таблицы. Поддерживаются форматы: CSV, TSV, JSON, JSONLines, Parquet, ORC и десятки других.

clickhouse-local vs сервер: когда что использовать

Используйте clickhouse-local, когда: нужно быстро проанализировать файл, написать прототип трансформации, отладить SQL-запрос без поднятия сервера.

Используйте Docker-сервер, когда: нужно хранить данные между сессиями, работать с HTTP API, тестировать реальное поведение MergeTree с частями, воспроизводить lab-упражнения курса.

Часть 3: Первый запрос к серверу — системные таблицы

Подключитесь к запущенному Docker-контейнеру через clickhouse-client:

docker compose exec clickhouse clickhouse-client

Вы увидите интерактивную консоль:

ClickHouse client version 26.3.x.x.
Connecting to localhost:9000 as user default.
Connected to ClickHouse server version 26.3.x.x.

clickhouse-lab :)

Системные таблицы

ClickHouse имеет богатую коллекцию системных таблиц в базе данных system. Они хранят метаданные о самой СУБД:

-- Посмотреть все системные таблицы
SELECT name, comment
FROM system.tables
WHERE database = 'system'
ORDER BY name
LIMIT 20;

-- Посмотреть информацию о текущих базах данных
SELECT name, engine, data_path
FROM system.databases;

-- Выполнить первый аналитический запрос
SELECT count() FROM system.numbers LIMIT 1;

Вывод последнего запроса:

1

system.numbers генерирует бесконечную последовательность. LIMIT 1 ограничивает до одной строки. count() без аргумента — ClickHouse-расширение SQL (в стандарте нужно count(*)).

Проверка конфигурации сервера

-- Версия и основные параметры
SELECT
    version(),
    getSetting('max_memory_usage') AS max_memory,
    getSetting('max_threads') AS max_threads;

-- Список поддерживаемых движков таблиц
SELECT name, description
FROM system.table_engines
WHERE name LIKE '%MergeTree%'
ORDER BY name;

Вы увидите семейство MergeTree: MergeTree, ReplicatedMergeTree, ReplacingMergeTree, SummingMergeTree, AggregatingMergeTree — это темы последующих модулей курса.

Остановка и очистка

# Остановить контейнер (данные сохранятся в volume)
docker compose stop

# Запустить снова
docker compose start

# Полная очистка (удалит данные!)
docker compose down -v

Ключевые выводы

1. docker compose up -d из директории labs/single-node/ поднимает ClickHouse 26.3 LTS с healthcheck
2. Проверка: docker compose exec clickhouse clickhouse-client --query "SELECT version()" должна вернуть 26.3.x.x
3. clickhouse-local — отдельный бинарник для ad-hoc аналитики файлов без сервера; не нужен Docker
4. Системные таблицы (system.tables, system.databases, system.numbers) — первая точка входа для изучения работающего ClickHouse
5. system.numbers — виртуальная таблица-генератор, полезная для тестов и бенчмарков