Начало работы с озерами данных

Самый быстрый способ начать — особенно для разовых запросов или если вы не используете каталог, — использовать табличную функцию icebergS3(). Укажите путь к таблице Iceberg в S3 и сразу выполняйте запросы — без какой-либо настройки.

Проверьте схему:

DESCRIBE icebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')

Выполните запрос:

SELECT
    url,
    count() AS cnt
FROM icebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')
GROUP BY url
ORDER BY cnt DESC
LIMIT 5

ClickHouse напрямую читает метаданные Iceberg из S3 и автоматически определяет схему. Тот же подход работает для deltaLake(), hudi() и paimon().

Узнать больше: В разделе Прямые запросы к открытым табличным форматам рассматриваются все четыре формата, варианты для cluster при распределённом чтении и варианты хранилища (S3, Azure, HDFS, локальное).

Если вы не используете каталог, но планируете многократно запрашивать один и тот же путь, создайте таблицу с движком таблицы Iceberg, чтобы не передавать путь каждый раз. Данные остаются в S3 — дублирования данных не происходит:

CREATE TABLE hits_iceberg
    ENGINE = IcebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')

Теперь отправляйте к ней запросы, как к любой таблице ClickHouse:

SELECT
    url,
    count() AS cnt
FROM hits_iceberg
GROUP BY url
ORDER BY cnt DESC
LIMIT 5

Движок таблицы поддерживает кэширование данных, кэширование метаданных, эволюцию схемы и запросы к прошлым версиям данных. Подробные сведения о возможностях движка таблицы см. в руководстве Прямые запросы, а полное сравнение возможностей — в матрице поддержки.

Если ваша организация использует каталог данных, мы рекомендуем этот путь интеграции. Каталоги централизуют метаданные таблиц и их поиск — вместо того чтобы управлять определением таблицы для каждого пути в хранилище, один раз подключитесь с помощью движка базы данных DataLakeCatalog. Каждая таблица в каталоге отображается как таблица ClickHouse, включая таблицы, добавленные в каталог уже после создания подключения.

Вот пример подключения к AWS Glue:

CREATE DATABASE my_lake
ENGINE = DataLakeCatalog
SETTINGS
    catalog_type = 'glue',
    region = '<your-region>',
    aws_access_key_id = '<your-access-key>',
    aws_secret_access_key = '<your-secret-key>'

Для каждого типа каталога требуются свои настройки подключения — полный список поддерживаемых каталогов и параметры их конфигурации см. в руководствах по каталогам.

Просматривайте таблицы и выполняйте запросы:

SHOW TABLES FROM my_lake;

SELECT count(*) FROM my_lake.`<database>.<table>`

Узнайте больше: в разделе Подключение к каталогу данных пошагово показана полная настройка Unity Catalog с примерами для Delta и Iceberg.

Независимо от того, какой метод вы использали выше — table function, движок таблицы или DataLakeCatalog, — во всех случаях используется один и тот же ClickHouse SQL. В продакшн при использовании каталога выполняйте запросы через базу данных DataLakeCatalog; остальные примеры по-прежнему полезны для быстрых тестов и доступа по пути:

-- Table function
SELECT url, count() AS cnt
FROM icebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')
GROUP BY url ORDER BY cnt DESC LIMIT 5

-- Table engine
SELECT url, count() AS cnt
FROM hits_iceberg
GROUP BY url ORDER BY cnt DESC LIMIT 5

-- Catalog
SELECT url, count() AS cnt
FROM my_lake.`<database>.<table>`
GROUP BY url ORDER BY cnt DESC LIMIT 5

Синтаксис запроса одинаков — меняется только предложение FROM. Все функции ClickHouse SQL, JOIN и агрегации работают одинаково независимо от источника данных.

Выполнять запросы напрямую к Iceberg удобно, но производительность ограничена пропускной способностью сети и структурой файлов. Для аналитических рабочих нагрузок загрузите данные в таблицу MergeTree.

Сначала выполните к таблице Iceberg запрос с фильтрацией, чтобы получить базовый уровень для сравнения:

SELECT
    url,
    count() AS cnt
FROM hits_iceberg
WHERE counterid = 38
GROUP BY url
ORDER BY cnt DESC
LIMIT 5

Этот запрос сканирует весь набор данных в S3, поскольку Iceberg не знает о фильтре counterid, — его выполнение займет несколько секунд.

Теперь создайте таблицу MergeTree и загрузите данные:

CREATE TABLE hits_clickhouse
(
    url String,
    eventtime DateTime,
    counterid UInt32
)
ENGINE = MergeTree()
ORDER BY (counterid, eventtime);

INSERT INTO hits_clickhouse
SELECT url, eventtime, counterid
FROM hits_iceberg

Повторно выполните тот же запрос к таблице MergeTree:

SELECT
    url,
    count() AS cnt
FROM hits_clickhouse
WHERE counterid = 38
GROUP BY url
ORDER BY cnt DESC
LIMIT 5

Поскольку counterid — первый столбец в ключе ORDER BY, разреженный первичный индекс ClickHouse сразу переходит к нужным гранулам, считывая только строки для counterid = 38 вместо сканирования всех 100 миллионов строк. Это дает заметный прирост скорости.

В руководстве ускорение аналитики эта тема рассматривается подробнее: типы LowCardinality, полнотекстовые индексы и оптимизированные ключи сортировки дают примерно 40-кратный прирост производительности на наборе данных из 283 миллионов строк.

Узнайте больше: в руководстве Ускорение аналитики с MergeTree рассматриваются оптимизация схемы, полнотекстовая индексация и полное сравнение производительности до и после.

ClickHouse также может записывать данные обратно в таблицы Iceberg, что позволяет реализовать сценарии обратного ETL: публиковать агрегированные результаты или подмножества данных для использования в других инструментах (Spark, Trino, DuckDB и т. д.).

Создайте таблицу Iceberg для вывода:

CREATE TABLE output_iceberg
(
    url String,
    cnt UInt64
)
ENGINE = IcebergS3('https://your-bucket.s3.amazonaws.com/output/', 'access_key', 'secret_key')

Запишите агрегированные результаты:

SET allow_experimental_insert_into_iceberg = 1;

INSERT INTO output_iceberg
SELECT
    url,
    count() AS cnt
FROM hits_clickhouse
GROUP BY url
ORDER BY cnt DESC

Получившаяся таблица Iceberg может читаться любым движком, совместимым с Iceberg.

Подробнее: Запись данных в открытые табличные форматы рассматривает запись сырых данных и агрегированных результатов с использованием набора данных UK Price Paid, включая особенности схемы при сопоставлении типов ClickHouse с Iceberg.