Apache Iceberg: от read-only до bidirectional

Apache Iceberg — открытый табличный формат с ACID-семантикой, schema evolution и time travel. ClickHouse поддерживает полный спектр интеграции: от простого read-only чтения через table function до полноценного двунаправленного доступа через IcebergMergeTree.

Read-only: iceberg() table function (все версии)

Для чтения Iceberg-таблиц без записи используется icebergS3 (и другие варианты для GCS, Azure). Эта возможность доступна во всех версиях ClickHouse, включая 26.3 LTS. Подробное описание базовых сценариев — в Модуле 11 урок 09. Здесь мы фокусируемся на write-сценариях.

-- Read-only: прямой запрос к Iceberg-таблице через S3 (все версии)
SELECT user_id, event_type, count()
FROM icebergS3(
    's3://analytics-bucket/events/',
    'ACCESS_KEY_ID',
    'SECRET_ACCESS_KEY'
)
WHERE event_date >= '2026-01-01'
GROUP BY user_id, event_type
LIMIT 10;

Для распределённого чтения по кластеру используется icebergS3Cluster('cluster_name', ...) — доступен GA с 24.12+.

IcebergMergeTree: write support (25.8+)

IcebergMergeTree — движок таблицы, позволяющий ClickHouse писать данные в Iceberg-формате, совместимом с другими движками (Spark, Trino, Flink). Таблица физически хранится в S3 в Iceberg-формате.

-- Создание IcebergMergeTree таблицы (ClickHouse 25.8+)
CREATE TABLE events_iceberg
(
    event_id    UInt64,
    user_id     UInt32,
    event_type  String,
    event_time  DateTime,
    payload     String
)
ENGINE = IcebergMergeTree(
    's3://my-data-lake/events/',
    'ACCESS_KEY_ID',
    'SECRET_ACCESS_KEY'
)
ORDER BY (user_id, event_time)
PARTITION BY toYYYYMM(event_time);

Отличия от обычного MergeTree:

Bidirectional: timeline возможностей (25.7-25.9)

Bidirectional поддержка появлялась поэтапно в нескольких минорных версиях 25.x:

ClickHouse 25.7:

-- INSERT INTO существующую Iceberg-таблицу (первая write-возможность)
INSERT INTO TABLE FUNCTION icebergS3(
    's3://my-lake/existing-table/',
    'ACCESS_KEY_ID',
    'SECRET_ACCESS_KEY'
)
SELECT * FROM staging_events WHERE event_date = today();

ClickHouse 25.8 (основная версия bidirectional):

-- CREATE TABLE новой IcebergMergeTree таблицы
CREATE TABLE new_events ENGINE = IcebergMergeTree('s3://my-lake/new-events/', ...)
ORDER BY (user_id, ts);

-- ALTER DELETE (equality deletes через Iceberg)
ALTER TABLE events_iceberg
DELETE WHERE event_time < '2025-01-01';

ClickHouse 25.9:

-- ALTER UPDATE (ClickHouse 25.9+)
ALTER TABLE events_iceberg
UPDATE payload = '{"status":"archived"}' WHERE event_type = 'legacy';

-- Distributed writes для кластерных конфигураций (25.9+)
INSERT INTO events_iceberg_distributed
SELECT * FROM source_cluster_table;

DataLakeCatalog: REST, Glue, Unity, Hive (beta 25.8)

DataLakeCatalog — интерфейс для работы с Iceberg через каталог вместо прямого S3-пути. Доступен в beta с ClickHouse 25.8.

-- Подключение через REST Catalog (Apache Iceberg REST Catalog spec)
CREATE TABLE events_via_rest
ENGINE = IcebergMergeTree()
SETTINGS
    catalog_type = 'rest',
    catalog_url = 'http://iceberg-catalog:8181',
    warehouse = 'my_warehouse',
    namespace = 'analytics',
    table_name = 'events';

-- AWS Glue Catalog
CREATE TABLE users_via_glue
ENGINE = IcebergMergeTree()
SETTINGS
    catalog_type = 'glue',
    catalog_url = 'https://glue.us-east-1.amazonaws.com',
    warehouse = 's3://my-data-lake/',
    namespace = 'prod',
    table_name = 'users',
    aws_access_key_id = 'KEY_ID',
    aws_secret_access_key = 'SECRET';

Поддерживаемые каталоги в 25.8 beta:

Catalog ecosystem 25.x-26.x

К 26.3 LTS набор поддерживаемых каталогов значительно расширен. Каталог — это абстракция: ClickHouse подключается к catalog-сервису, тот возвращает список таблиц с их metadata-указателями, и ClickHouse автоматически делает каждую таблицу видимой как объект в database. Никаких ручных CREATE TABLE для каждой Iceberg-таблицы не нужно — они появляются автоматически.

Timeline появления каталогов

REST Catalog: фундамент экосистемы

rest — это imeplementация Apache Iceberg REST Catalog Spec, открытого протокола. Он лежит в основе нескольких managed-сервисов: Apache Polaris (open-source proper), Snowflake Open Catalog (managed Polaris от Snowflake) и Tabular (managed Iceberg-сервис, поглощённый Databricks).

-- Apache Polaris (self-hosted)
CREATE DATABASE polaris_db
ENGINE = DataLakeCatalog
SETTINGS
    catalog_type = 'rest',
    catalog_url = 'http://polaris:8181/api/catalog',
    warehouse = 'analytics_warehouse',
    auth_header = 'Bearer ' || getEnv('POLARIS_TOKEN');

-- Snowflake Open Catalog (managed Polaris)
CREATE DATABASE snowflake_oc
ENGINE = DataLakeCatalog
SETTINGS
    catalog_type = 'rest',
    catalog_url = 'https://<account>.snowflakecomputing.com/polaris/api/catalog/v1/<catalog_name>',
    warehouse = 'analytics_warehouse',
    oauth_server_uri = 'https://<account>.snowflakecomputing.com/oauth/token',
    oauth_client_id = '<client_id>',
    oauth_client_secret = '<secret>';

-- Все таблицы из Polaris/Open Catalog становятся видны автоматически
SHOW TABLES FROM polaris_db;
SELECT count() FROM polaris_db.events_2026 WHERE region = 'eu-west-1';

AWS Glue Catalog

CREATE DATABASE aws_lake
ENGINE = DataLakeCatalog
SETTINGS
    catalog_type = 'glue',
    region = 'us-east-1',
    aws_access_key_id = '...',
    aws_secret_access_key = '...';

SELECT count() FROM aws_lake.production_events;

Glue-провайдер использует AWS Glue Data Catalog API. ClickHouse подтягивает metadata-локацию каждой таблицы и читает файлы напрямую из S3.

Microsoft OneLake (25.11+)

Microsoft Fabric использует OneLake — единое хранилище в Azure. Tables API в OneLake предоставляет Iceberg-совместимый интерфейс. Интеграция дебютировала в beta в ClickHouse 25.11 и доступна в ClickHouse Cloud.

CREATE DATABASE onelake_fabric
ENGINE = DataLakeCatalog
SETTINGS
    catalog_type = 'onelake',
    workspace_id = '<fabric-workspace-uuid>',
    lakehouse_id = '<lakehouse-uuid>',
    azure_tenant_id = '<tenant>',
    azure_client_id = '<client>',
    azure_client_secret = '<secret>';

-- Чтение Fabric Lakehouse-таблиц из ClickHouse
SELECT user_id, sum(amount)
FROM onelake_fabric.bronze_orders
WHERE order_date >= '2026-01-01'
GROUP BY user_id;

Google Lakehouse Runtime Catalog (26.2+)

В ClickHouse 26.2 добавлена интеграция с Google BigLake Iceberg-каталогом. Это позволяет ClickHouse читать (и в перспективе писать) в таблицы, управляемые BigLake, без необходимости развёртывания отдельного Polaris в GCP.

CREATE DATABASE google_biglake
ENGINE = DataLakeCatalog
SETTINGS
    catalog_type = 'google',
    project_id = 'my-gcp-project',
    location = 'us-central1',
    warehouse = 'gs://my-warehouse/',
    -- service-account credentials через ADC
    credentials_file = '/etc/clickhouse/gcp-sa.json';

SELECT * FROM google_biglake.iceberg_events LIMIT 100;

Vended credentials и multi-cloud

REST-каталоги (Polaris, Snowflake Open Catalog) поддерживают vended credentials — catalog-сервис выдаёт ClickHouse временные signed URLs / STS-credentials для конкретной таблицы вместо постоянных секретов. Для AWS Glue ClickHouse (с фиксом, появившимся в 26.x) использует Azure ADLS Gen2 vended credentials, что особенно важно для multi-cloud сценариев, где данные физически живут в Azure, а каталог — в AWS.

Выбор каталога в production

Iceberg read/write data flow

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

1. Read-only через icebergS3 доступен во всех версиях ClickHouse. Для углублённых сценариев чтения — см. Модуль 11 урок 09 с icebergS3Cluster и deltaLakeS3.

2. IcebergMergeTree (25.8+) позволяет ClickHouse записывать данные в Iceberg-формате, совместимом со Spark, Trino и Flink. Ключевое отличие от MergeTree — данные физически живут в S3 в стандартном Iceberg-формате.

3. Bidirectional timeline: INSERT INTO существующие таблицы — 25.7, CREATE TABLE новых IcebergMergeTree + ALTER DELETE + DataLakeCatalog beta — 25.8, ALTER UPDATE + distributed writes — 25.9. INSERT-ы официально объявлены production-ready в 26.2 (Feb 2026). Все возможности доступны в ClickHouse 26.3 LTS — с оговоркой: optimistic concurrency Iceberg ограничивает frequency коммитов (~15/min на таблицу), что делает паттерн пригодным для batch/periodic write, но не для high-frequency streaming.

4. DataLakeCatalog ecosystem (24.12-26.2) поддерживает REST/Apache Polaris (24.12), AWS Glue + Unity (25.3), Hive Metastore (25.5), Microsoft OneLake (25.11), Google Lakehouse Runtime Catalog (26.2) и Snowflake Open Catalog (через REST-протокол). REST-протокол объединяет Polaris, Snowflake Open Catalog и проприетарные REST-каталоги — миграция между ними меняет только catalog_url и схему auth. Vended credentials позволяют избежать постоянных секретов в multi-cloud сценариях.

5. Практический выбор: Для production write-сценариев в 26.3 LTS используйте прямой S3-путь (IcebergMergeTree('s3://...')). DataLakeCatalog — для сред с существующим каталогом (например, AWS Glue) при понимании beta-статуса.