Установка и первое знакомство — ClickHouse: от

Установка и первое знакомство с ClickHouse

Закреплённая версия, понятный запуск и первый измеряемый запрос

#Результат урока

Вы запустите закреплённую версию ClickHouse, проверите интерфейсы подключения и создадите первую MergeTree-таблицу. В конце у вас будет команда, которая воспроизводит окружение без зависимости от изменяемого тега latest.

#Способы установки

#1. Docker (рекомендуется для начала)

Самый быстрый способ запустить ClickHouse локально:

docker run -d \
  --name clickhouse-server \
  -p 8123:8123 \
  -p 9000:9000 \
  -v clickhouse_data:/var/lib/clickhouse \
  clickhouse/clickhouse-server:26.3

Порты:

8123 — HTTP-интерфейс (веб-UI, curl, HTTP-запросы)
9000 — Native TCP (clickhouse-client, драйверы)

Проверка запуска:

docker logs clickhouse-server
# Ищите: "Ready for connections"

#2. Нативная установка (Linux)

# Ubuntu/Debian: официальный репозиторий с отдельным keyring
sudo apt-get install -y apt-transport-https ca-certificates curl gnupg
curl -fsSL 'https://packages.clickhouse.com/rpm/lts/repodata/repomd.xml.key' \
  | sudo gpg --dearmor -o /usr/share/keyrings/clickhouse-keyring.gpg

ARCH=$(dpkg --print-architecture)
echo "deb [signed-by=/usr/share/keyrings/clickhouse-keyring.gpg arch=${ARCH}] https://packages.clickhouse.com/deb lts main" \
  | sudo tee /etc/apt/sources.list.d/clickhouse.list
sudo apt-get update
sudo apt-get install -y clickhouse-server clickhouse-client
sudo service clickhouse-server start

Команда apt-key оставлена только в старых инструкциях дистрибутивов и не нужна в новом окружении. Для рабочей системы закрепляйте конкретную версию всех пакетов и сначала проверяйте обновление на реплике или стенде.

#3. macOS (через Colima или Docker Desktop)

# Через Colima + Docker
brew install colima docker
colima start
docker run -d --name clickhouse-server -p 8123:8123 -p 9000:9000 clickhouse/clickhouse-server:26.3

# Или через Homebrew (ограниченная поддержка)
brew install clickhouse

#Подключение к ClickHouse

#clickhouse-client (CLI)

# Локальное подключение
docker exec -it clickhouse-server clickhouse-client

# Или через сеть
clickhouse-client --host localhost --port 9000

# С указанием пользователя и пароля
clickhouse-client --host localhost --user default --password mypassword

#Веб-интерфейс (Play UI)

Откройте в браузере: http://localhost:8123/play

Веб-интерфейс поддерживает:

Выполнение запросов
Просмотр результатов в таблице/JSON/CSV
Историю запросов
Форматирование SQL

#HTTP-интерфейс через curl

# Простой запрос
curl "http://localhost:8123/?query=SELECT+1"

# С данными для вставки
curl "http://localhost:8123/?query=INSERT+INTO+table+FORMAT+TabSeparated" \
  --data-binary "value1\tvalue2"

# С выводом в JSON
curl "http://localhost:8123/?query=SELECT+1+AS+x+FORMAT+JSON"

#Первая база данных и таблица

#Создание базы данных

CREATE DATABASE IF NOT EXISTS tutorial;
USE tutorial;

#Создание первой таблицы

Создадим таблицу для хранения событий просмотров страниц:

CREATE TABLE page_views
(
    event_time      DateTime DEFAULT now(),
    user_id         UInt64,
    page_url        String,
    referer         String,
    user_agent      String,
    country         LowCardinality(String),
    city            LowCardinality(String),
    screen_width    UInt16,
    screen_height   UInt16,
    is_mobile       UInt8
)
ENGINE = MergeTree()
PARTITION BY toYYYYMM(event_time)
ORDER BY (event_time, user_id)
SETTINGS index_granularity = 8192;

Разберём ключевые части:

Компонент	Назначение
`ENGINE = MergeTree()`	Основной движок для аналитики
`PARTITION BY toYYYYMM(event_time)`	Разбиение данных по месяцам
`ORDER BY (event_time, user_id)`	Сортировка данных внутри партиции
`index_granularity = 8192`	Размер гранулы для индексов

#Вставка данных

INSERT INTO page_views 
(user_id, page_url, referer, country, city, screen_width, screen_height, is_mobile)
VALUES 
(1, 'https://example.com/home', 'https://google.com', 'RU', 'Moscow', 1920, 1080, 0),
(2, 'https://example.com/products', 'https://google.com', 'US', 'New York', 1440, 900, 0),
(3, 'https://example.com/cart', 'https://example.com/products', 'RU', 'Saint Petersburg', 390, 844, 1);

#Простые запросы

-- Количество событий
SELECT count() FROM page_views;

-- События по странам
SELECT country, count() AS views 
FROM page_views 
GROUP BY country 
ORDER BY views DESC;

-- События за сегодня
SELECT * FROM page_views 
WHERE event_time >= today();

-- Мобильные пользователи
SELECT city, count() AS mobile_views
FROM page_views
WHERE is_mobile = 1
GROUP BY city
ORDER BY mobile_views DESC;

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

Метаданные и текущее состояние сервера доступны в системных таблицах:

-- Список баз данных
SELECT name FROM system.databases;

-- Список таблиц в текущей БД
SELECT name, engine FROM system.tables 
WHERE database = 'tutorial';

-- Информация о столбцах
SELECT name, type, default_expression 
FROM system.columns 
WHERE table = 'page_views';

-- Текущие запросы
SELECT query, elapsed, read_rows 
FROM system.processes;

-- История запросов
SELECT query, read_rows, read_bytes, elapsed 
FROM system.query_log 
WHERE event_date = today()
ORDER BY event_time DESC 
LIMIT 10;

#Конфигурация

#Расположение конфигов

/etc/clickhouse-server/
├── config.xml          # Основной конфиг
├── users.xml           # Пользователи и квоты
└── conf.d/             # Дополнительные конфиги

#Важные настройки

<!-- config.xml -->
<clickhouse>
    <!-- Порт для HTTP -->
    <http_port>8123</http_port>
    
    <!-- Порт для TCP -->
    <tcp_port>9000</tcp_port>
    
    <!-- Максимум памяти на запрос -->
    <max_memory_usage>10000000000</max_memory_usage>
    
    <!-- Таймаут запроса -->
    <max_execution_time>60</max_execution_time>
    
    <!-- Путь к данным -->
    <path>/var/lib/clickhouse/</path>
</clickhouse>

#Применение настроек через Docker

docker run -d \
  --name clickhouse-server \
  -p 8123:8123 -p 9000:9000 \
  -v ./config.xml:/etc/clickhouse-server/config.xml \
  -v clickhouse_data:/var/lib/clickhouse \
  clickhouse/clickhouse-server

#Драйверы для приложений

#Python

pip install clickhouse-driver

from clickhouse_driver import Client

client = Client('localhost')

# Простой запрос
result = client.execute('SELECT count() FROM page_views')
print(result[0][0])

# Вставка данных
client.execute(
    'INSERT INTO page_views (user_id, page_url, country) VALUES',
    [(4, 'https://example.com/about', 'DE'),
     (5, 'https://example.com/contact', 'FR')]
)

# Запрос с параметрами
result = client.execute(
    'SELECT country, count() FROM page_views WHERE country = %(country)s GROUP BY country',
    {'country': 'RU'}
)

#Node.js

npm install @clickhouse/client

import { createClient } from '@clickhouse/client';

const client = createClient({
  host: 'http://localhost:8123',
});

const resultSet = await client.query({
  query: 'SELECT count() FROM page_views',
  format: 'JSON',
});

const result = await resultSet.json();
console.log(result.data[0].count());

#Go

go get github.com/ClickHouse/clickhouse-go/v2

conn, err := clickhouse.Open(&clickhouse.Options{
    Addr: []string{"localhost:9000"},
    Auth: clickhouse.Auth{Database: "default"},
})

rows, err := conn.Query(context.Background(), "SELECT count() FROM page_views")

#Форматы данных

Формат ввода и вывода задаётся прямо в запросе. Для начала достаточно следующих вариантов:

# JSON
curl "http://localhost:8123/?query=SELECT+*+FROM+page_views+FORMAT+JSON"

# JSONCompact (массивы вместо объектов)
curl "http://localhost:8123/?query=SELECT+*+FROM+page_views+FORMAT+JSONCompact"

# CSV
curl "http://localhost:8123/?query=SELECT+*+FROM+page_views+FORMAT+CSV"

# TabSeparated (табуляция)
curl "http://localhost:8123/?query=SELECT+*+FROM+page_views+FORMAT+TabSeparated"

# Pretty (таблица для человека)
curl "http://localhost:8123/?query=SELECT+*+FROM+page_views+LIMIT+5+FORMAT+Pretty"

# Native (бинарный, для драйверов)
curl "http://localhost:8123/?query=SELECT+*+FROM+page_views+FORMAT+Native"

#Остановка и удаление

# Остановить контейнер
docker stop clickhouse-server

# Запустить снова
docker start clickhouse-server

# Удалить контейнер (данные сохранятся в volume)
docker rm clickhouse-server

# Удалить всё, включая локальный учебный том. Команда необратима.
docker rm -f clickhouse-server
docker volume rm clickhouse_data

Перед удалением тома выполните docker volume inspect clickhouse_data и убедитесь, что это именно учебное окружение.

Компонент

Назначение

ENGINE = MergeTree()

Основной движок для аналитики

PARTITION BY toYYYYMM(event_time)

Разбиение данных по месяцам

ORDER BY (event_time, user_id)

Сортировка данных внутри партиции

index_granularity = 8192

Размер гранулы для индексов

/etc/clickhouse-server/ ├── config.xml # Основной конфиг ├── users.xml # Пользователи и квоты └── conf.d/ # Дополнительные конфиги