> ## 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.

# Polaris 目录

> 本指南将逐步介绍如何使用 ClickHouse 和 Snowflake Polaris 目录查询 您的数据。

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>Beta</span>
            </a>;
  }
  return <div className="betaBadge">
            <Icon />
            <span>
                Beta 版功能。 
                <u>
                    <a href="/docs/docs/beta-and-experimental-features#beta-features">
                        了解更多。
                    </a>
                </u>
            </span>
        </div>;
};

<BetaBadge />

ClickHouse 支持与多个目录 (Unity、Glue、Polaris 等) 集成。本指南将逐步介绍如何使用 ClickHouse 和 [Apache Polaris Catalog](https://polaris.apache.org/releases/1.1.0/getting-started/using-polaris/#setup) 查询您的数据。
Apache Polaris 支持 Iceberg 表和 Delta Tables (通过 Generic Tables) 。目前，此集成仅支持 Iceberg 表。

<Note>
  由于该功能仍处于 Experimental 阶段，您需要使用以下命令启用它：
  `SET allow_experimental_database_unity_catalog = 1;`
</Note>

<div id="prerequisites">
  ## 前置条件
</div>

要连接到 Polaris 目录，您需要具备：

* Snowflake Open Catalog (托管的 Polaris) 或自托管的 Polaris 目录
* 您的 Polaris 目录 URI (例如，`https://<account-id>.<region>.aws.snowflakecomputing.com/polaris/api/catalog/v1` 或 `http://polaris:8181/api/catalog/v1/oauth/tokens`)
* Catalog 凭据 (client ID 和 client secret)
* 您的 Polaris 实例的 OAuth 令牌 URI
* 存储 Iceberg 数据的对象存储端点 (例如 S3)
* ClickHouse 26.1+ 版本

对于 Open Catalog (Snowflake 托管的 Polaris 服务) ，URI 会包含 `/polaris`；而对于自托管部署，则可能不包含。

<Steps>
  <Step title="在 Polaris 和 ClickHouse 之间创建连接" id="connecting">
    创建一个数据库，将 ClickHouse 连接到您的 Polaris 目录：

    ```sql theme={null}
    CREATE DATABASE polaris_catalog
    ENGINE = DataLakeCatalog('https://<catalog_uri>/api/catalog/v1')
    SETTINGS
        catalog_type = 'rest',
        catalog_credential = '<client-id>:<client-secret>',
        warehouse = 'snowflake',
        auth_scope = 'PRINCIPAL_ROLE:ALL',
        oauth_server_uri = 'https://<catalog_uri>/api/catalog/v1/oauth/tokens',
        storage_endpoint = '<storage_endpoint>'
    ```
  </Step>

  <Step title="使用 ClickHouse 查询 Polaris 目录" id="query-polaris-catalog">
    连接建立后，您可以查询 Polaris：

    ```sql title="查询" theme={null}
    USE polaris_catalog;
    SHOW TABLES;
    ```

    要查询某个表：

    ```sql title="查询" theme={null}
    SELECT count(*) FROM `polaris_db.my_iceberg_table`;
    ```

    <Note>
      必须使用反引号，例如 `schema.table`。
    </Note>

    要查看表的 DDL：

    ```sql theme={null}
    SHOW CREATE TABLE `polaris_db.my_iceberg_table`;
    ```
  </Step>

  <Step title="将 Polaris 中的数据加载到 ClickHouse" id="loading-data-into-clickhouse">
    要将 Polaris 中的数据加载到 ClickHouse 表中，请先按所需的 schema 创建目标表，然后从 Polaris 表中插入数据：

    ```sql title="查询" theme={null}
    CREATE TABLE my_clickhouse_table
    (
        -- 定义与您的 Iceberg 表匹配的列
        `id` Int64,
        `name` String,
        `event_time` DateTime64(3)
    )
    ENGINE = MergeTree
    ORDER BY id;

    INSERT INTO my_clickhouse_table
    SELECT * FROM polaris_catalog.`polaris_db.my_iceberg_table`;
    ```
  </Step>
</Steps>