> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Подключите ClickHouse к внешним каталогам данных с помощью движка базы данных DataLakeCatalog, чтобы представить таблицы каталога как собственные базы данных ClickHouse.

export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
  if (link) {
    return <a href={link} target="_blank" rel="noopener noreferrer" className="betaBadge" onClick={galaxyTrack && galaxyEvent ? galaxyOnClick(galaxyEvent) : undefined}>
                <Icon />
                <span>Бета</span>
            </a>;
  }
  return <div className="betaBadge">
            <Icon />
            <span>
                Возможность в статусе бета. 
                <u>
                    <a href="/docs/docs/beta-and-experimental-features#beta-features">
                        Подробнее.
                    </a>
                </u>
            </span>
        </div>;
};

В [предыдущем разделе](/docs/ru/guides/use-cases/data-warehousing/getting-started/querying-directly) вы выполняли запросы к открытым табличным форматам, напрямую указывая пути в хранилище. На практике большинство организаций управляют метаданными таблиц через **каталог данных** — централизованный реестр, в котором отслеживаются местоположения таблиц, схемы и партиции. Когда вы подключаете ClickHouse к каталогу с помощью движка базы данных [`DataLakeCatalog`](/docs/ru/reference/engines/database-engines/datalake), весь каталог становится доступен как база данных ClickHouse. Каждая таблица в каталоге появляется автоматически, и к ней можно выполнять запросы, используя все возможности ClickHouse SQL, — не нужно знать пути к отдельным таблицам или управлять учетными данными для каждой таблицы.

В этом руководстве показано, как подключиться к [Databricks Unity Catalog](https://www.databricks.com/product/unity-catalog). ClickHouse также поддерживает следующие каталоги — полные инструкции по настройке см. в соответствующих справочных руководствах:

| Каталог              | Справочное руководство                                                         |
| -------------------- | ------------------------------------------------------------------------------ |
| AWS Glue             | [Каталог AWS Glue](/docs/ru/guides/use-cases/data-warehousing/glue-catalog)         |
| Iceberg REST Catalog | [REST-каталог](/docs/ru/guides/use-cases/data-warehousing/rest-catalog)             |
| Lakekeeper           | [Lakekeeper catalog](/docs/ru/guides/use-cases/data-warehousing/lakekeeper-catalog) |
| Project Nessie       | [Nessie catalog](/docs/ru/guides/use-cases/data-warehousing/nessie-catalog)         |
| Microsoft OneLake    | [Fabric OneLake](/docs/ru/guides/use-cases/data-warehousing/onelake-catalog)        |

<div id="connecting-to-unity-catalog">
  ## Подключение к Unity Catalog
</div>

<BetaBadge />

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

[Databricks Unity Catalog](https://www.databricks.com/product/unity-catalog) обеспечивает централизованное управление данными lakehouse в Databricks.

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

<Note>
  В настоящее время эта интеграция поддерживается только в AWS. Таблицы в управляемом хранилище Databricks не поддерживаются, поскольку Unity Catalog не предоставляет учетные данные для этих расположений. Подробности см. в [справочнике по Unity Catalog](/docs/ru/guides/use-cases/data-warehousing/unity-catalog).
</Note>

<div id="configuring-unity-in-databricks">
  ### Настройка Unity в Databricks
</div>

Чтобы ClickHouse мог взаимодействовать с Unity Catalog, необходимо убедиться, что ваш Unity Catalog настроен для работы с внешним клиентом чтения. Для этого следуйте руководству [ "Enable external data access to Unity Catalog"](https://docs.databricks.com/aws/en/external-access/admin).

Помимо включения внешнего доступа, убедитесь, что субъект, настраивающий интеграцию, имеет привилегию [`EXTERNAL USE SCHEMA`](https://docs.databricks.com/aws/en/external-access/admin#external-schema) для схемы, содержащей таблицы.

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

* Для клиентов Iceberg используйте аутентификацию через [сервисный субъект](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m).

* Для клиентов Delta используйте Personal Access Token ([PAT](https://docs.databricks.com/aws/en/dev-tools/auth/pat)).

<div id="connect-catalog">
  ### Подключение к каталогу
</div>

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

<Tabs>
  <Tab title="Delta">
    Для доступа к данным в формате Delta следует использовать [Unity Catalog](/docs/ru/guides/use-cases/data-warehousing/unity-catalog).

    ```sql theme={null}
    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';
    ```
  </Tab>

  <Tab title="Iceberg">
    ```sql theme={null}
    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';
    ```
  </Tab>
</Tabs>

<div id="list-tables">
  ### Список таблиц
</div>

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

```sql theme={null}
SHOW TABLES FROM unity
```

```response theme={null}
┌─name───────────────────────────────────────────────┐
│ unity.logs                                         │
│ unity.single_day_log                               │
└────────────────────────────────────────────────────┘

31 rows in set.
```

<div id="exploring-table-schemas">
  ### Изучение схем таблиц
</div>

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

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

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

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

```sql theme={null}
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://...')
```

<div id="querying-a-table">
  ### Запросы к таблице
</div>

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

```sql theme={null}
SELECT count()
FROM unity.`icebench.single_day_log`
```

```response theme={null}
┌───count()─┐
│ 282634391 │ -- 282,63 миллиона
└───────────┘

1 row in set. Elapsed: 1.265 sec.
```

Полные инструкции по настройке см. в [справочном руководстве по Unity Catalog](/docs/ru/guides/use-cases/data-warehousing/unity-catalog).