Подключение к каталогу данных

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

В этом руководстве показано, как подключиться к Databricks Unity Catalog. ClickHouse также поддерживает следующие каталоги — полные инструкции по настройке см. в соответствующих справочных руководствах:

Каталог	Справочное руководство
AWS Glue	Каталог AWS Glue
Iceberg REST Catalog	REST-каталог
Lakekeeper	Каталог Lakekeeper
Project Nessie	Каталог Nessie
Microsoft OneLake	Fabric OneLake

Подключение к Unity Catalog

Beta feature. Learn more.

В качестве примера мы будем использовать Unity Catalog.

Databricks Unity Catalog предоставляет централизованное управление данными lakehouse в Databricks.

Databricks поддерживает несколько форматов данных для своего lakehouse. С помощью ClickHouse вы можете выполнять запросы к таблицам Unity Catalog как к таблицам Delta и Iceberg.

Примечание

Интеграция с Unity Catalog работает как с управляемыми, так и с внешними таблицами. В настоящее время эта интеграция поддерживается только в AWS.

Настройка Unity в Databricks

Чтобы разрешить ClickHouse взаимодействовать с каталогом Unity, необходимо убедиться, что ваш Unity Catalog настроен на взаимодействие с внешним клиентом чтения. Для этого следуйте руководству «Enable external data access to Unity Catalog».

Помимо включения внешнего доступа, убедитесь, что субъект безопасности, настраивающий интеграцию, имеет привилегию EXTERNAL USE SCHEMA для схемы, содержащей таблицы.

После настройки каталога необходимо сгенерировать учетные данные для ClickHouse. В зависимости от режима взаимодействия с Unity можно использовать два разных метода:

• Для клиентов Iceberg используйте аутентификацию через сервисный субъект.

• Для клиентов Delta используйте персональный токен доступа (PAT).

Подключение к каталогу

Используя эти учетные данные, вы можете подключиться к соответствующему эндпоинту и выполнять запросы к таблицам Iceberg или Delta.

Delta

Для доступа к данным в формате Delta следует использовать Unity Catalog.

SET allow_experimental_database_unity_catalog = 1;

CREATE DATABASE unity
ENGINE = DataLakeCatalog('https://<workspace-id>.cloud.databricks.com/api/2.1/unity-catalog')
SETTINGS warehouse = 'CATALOG_NAME', catalog_credential = '<PAT>', catalog_type = 'unity';

Iceberg

SET allow_database_iceberg = 1;

CREATE DATABASE unity
ENGINE = DataLakeCatalog('https://<workspace-id>.cloud.databricks.com/api/2.1/unity-catalog/iceberg-rest')
SETTINGS catalog_type = 'rest', catalog_credential = '<client-id>:<client-secret>', warehouse = 'workspace',
oauth_server_uri = 'https://<workspace-id>.cloud.databricks.com/oidc/v1/token', auth_scope = 'all-apis,sql';

Просмотр списка таблиц

После подключения к каталогу вы можете вывести список таблиц.

SHOW TABLES FROM unity

┌─name───────────────────────────────────────────────┐
│ unity.logs                                         │
│ unity.single_day_log                               │
└────────────────────────────────────────────────────┘

31 rows in set.

Изучение схем таблиц

Мы можем использовать стандартную команду SHOW CREATE TABLE, чтобы посмотреть, как были созданы таблицы.

Обратные кавычки обязательны

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

Ниже предполагается выполнение запросов к REST-каталогу Iceberg:

SHOW CREATE TABLE unity.`icebench.single_day_log`

CREATE TABLE unity.`icebench.single_day_log`
(
    `pull_request_number` Nullable(Int64),
    `commit_sha` Nullable(String),
    `check_start_time` Nullable(DateTime64(6, 'UTC')),
    `check_name` Nullable(String),
    `instance_type` Nullable(String),
    `instance_id` Nullable(String),
    `event_date` Nullable(Date32),
    `event_time` Nullable(DateTime64(6, 'UTC')),
    `event_time_microseconds` Nullable(DateTime64(6, 'UTC')),
    `thread_name` Nullable(String),
    `thread_id` Nullable(Decimal(20, 0)),
    `level` Nullable(String),
    `query_id` Nullable(String),
    `logger_name` Nullable(String),
    `message` Nullable(String),
    `revision` Nullable(Int64),
    `source_file` Nullable(String),
    `source_line` Nullable(Decimal(20, 0)),
    `message_format_string` Nullable(String)
)
ENGINE = Iceberg('s3://...')

Запрос к таблице

Поддерживаются все функции ClickHouse. И снова: пространство имен и имя таблицы должны быть заключены в обратные кавычки.

SELECT count()
FROM unity.`icebench.single_day_log`

┌───count()─┐
│ 282634391 │ -- 282.63 million
└───────────┘

1 row in set. Elapsed: 1.265 sec.

Полные инструкции по настройке см. в справочном руководстве по Unity Catalog.