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

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

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

Для примера будем использовать Unity Catalog.

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

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

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

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

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

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

• Для клиентов Delta используйте Personal Access Token (PAT).

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

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';

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, чтобы посмотреть, как были созданы таблицы.

Ниже предполагается выполнение запросов к 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 миллиона
└───────────┘

1 row in set. Elapsed: 1.265 sec.

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