DataLakeCatalog

Движок базы данных DataLakeCatalog позволяет подключать ClickHouse к внешним каталогам данных и выполнять запросы к данным в открытых табличных форматах без дублирования данных. Это превращает ClickHouse в мощный движок запросов, который легко интегрируется с вашей существующей инфраструктурой озера данных.

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

Движок DataLakeCatalog поддерживает следующие каталоги данных:

Каталог AWS Glue — для таблиц Iceberg в средах AWS
Databricks Unity Catalog — для таблиц Delta Lake и Iceberg
Hive Metastore — традиционный каталог экосистемы Hadoop
REST-каталоги — любые каталоги, поддерживающие спецификацию Iceberg REST

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

Чтобы использовать движок DataLakeCatalog, необходимо включить указанные ниже настройки:

SET allow_database_iceberg = 1;
SET allow_database_unity_catalog = 1;
SET allow_database_glue_catalog = 1;
SET allow_experimental_database_hms_catalog = 1;
SET allow_experimental_database_paimon_rest_catalog = 1;

Базы данных с движком DataLakeCatalog можно создавать, используя следующий синтаксис:

CREATE DATABASE database_name
ENGINE = DataLakeCatalog(catalog_endpoint[, user, password])
SETTINGS
catalog_type,
[...]

Поддерживаются следующие настройки:

Настройка	Описание
`catalog_type`	Тип каталога: `glue`, `unity` (Delta или Delta и Iceberg с `use_unity_catalog_v2`), `rest` (Iceberg), `hive`, `onelake` (Iceberg), `delta_sharing` (Iceberg, плоские пространства имен), `horizon` (Snowflake Horizon Iceberg REST)
`warehouse`	Имя хранилища или базы данных, используемое в каталоге.
`catalog_credential`	Учетные данные для аутентификации в каталоге (например, API key или токен)
`use_unity_catalog_v2`	Для `catalog_type = 'unity'`: использовать новую реализацию, поддерживающую таблицы Delta Lake и Iceberg. Значение по умолчанию: `false`. Задайте параметр при выполнении `CREATE` или измените его для существующей базы данных с помощью `ALTER DATABASE ... MODIFY SETTING`.
`auth_header`	Пользовательский HTTP-заголовок для аутентификации в сервисе каталога
`auth_scope`	Область действия OAuth2 для аутентификации (если используется OAuth)
`storage_endpoint`	URL конечной точки нижележащего хранилища
`oauth_server_uri`	URI сервера авторизации OAuth2 для аутентификации
`vended_credentials`	Логическое значение, указывающее, следует ли использовать учетные данные, предоставленные каталогом (поддерживаются AWS S3 и Azure ADLS Gen2)
`aws_access_key_id`	Идентификатор ключа доступа AWS для доступа к S3/Glue (если не используются предоставленные учетные данные)
`aws_secret_access_key`	Секретный ключ доступа AWS для доступа к S3/Glue (если не используются предоставленные учетные данные)
`aws_role_arn`	ARN роли IAM, которую нужно принять для доступа к AWS/Glue. Если параметр задан, ClickHouse использует AWS STS `AssumeRole` с базовыми учетными данными из `aws_access_key_id` и `aws_secret_access_key`, когда заданы оба параметра, или в противном случае из стандартной цепочки учетных данных AWS (роль должна доверять идентификационным данным, под которыми работает сервер).
`aws_role_session_name`	Имя сеанса, используемое для вызова AWS STS `AssumeRole`. Необязательно; по умолчанию используется `ClickHouseSession`.
`aws_external_id`	Внешний идентификатор, передаваемый в AWS STS `AssumeRole`, соответствующий условию `sts:ExternalId` в trust policy роли. Используйте это, если роль принадлежит третьей стороне, такой как ClickHouse Cloud.
`region`	Регион AWS для сервиса (например, `us-east-1`)
`dlf_access_key_id`	Идентификатор ключа доступа для доступа к DLF
`dlf_access_key_secret`	Секретный ключ доступа для доступа к DLF
`force_add_bucket`	При формировании URL объектного хранилища на основе расположения таблицы, предоставленного каталогом, и `storage_endpoint` добавляет в начало имя бакета/контейнера, даже если оно уже присутствует в конечной точке. Значение по умолчанию: `false`. Установите `true` для каталогов, которые возвращают пути без бакета и требуют его добавления на этапе формирования URL (пути в стиле Polaris).

Примеры

См. разделы ниже с примерами использования движка DataLakeCatalog:

Unity Catalog
Unity Catalog с таблицами Delta Lake и Iceberg При use_unity_catalog_v2 = 1 каталог unity обслуживает как таблицы Delta Lake, так и таблицы Iceberg, определяя формат каждой таблицы.

CREATE DATABASE database_name
ENGINE = DataLakeCatalog('https://<workspace>.cloud.databricks.com/api/2.1/unity-catalog')
SETTINGS
    catalog_type = 'unity',
    use_unity_catalog_v2 = 1,
    warehouse = 'my_catalog',
    catalog_credential = '<client_id>:<client_secret>';
SHOW TABLES FROM database_name;
SELECT count() FROM database_name.`schema_name.table_name`;

catalog_credential принимает сервисный субъект OAuth в формате <client_id>:<client_secret>, персональный токен доступа (dapi...) или заранее полученный токен OAuth.

Каталог AWS Glue
Каталог OneLake Можно использовать при включении allow_database_iceberg.

CREATE DATABASE database_name
ENGINE = DataLakeCatalog(catalog_endpoint)
SETTINGS
    catalog_type = 'onelake',
    warehouse = warehouse,
    onelake_tenant_id = tenant_id,
    oauth_server_uri = server_uri,
    auth_scope = auth_scope,
    onelake_client_id = client_id,
    onelake_client_secret = client_secret;
SHOW TABLES IN database_name;
SELECT count() from database_name.table_name;

Чтобы пройти аутентификацию, не передавая секрет клиента, задайте для onelake_bearer_token заранее полученный Bearer-токен (с областью действия https://storage.azure.com) вместо onelake_client_id/onelake_client_secret. ClickHouse не обновляет токен, поэтому после истечения срока его действия базу данных нужно пересоздать.

Справочник по SQL

Типы данных

Движки

Функции

Форматы

Настройки

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

Озера данных

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

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

Примеры

​Поддерживаемые каталоги

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

​Примеры

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

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

Примеры