> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 数据湖入门

> 通过实践了解如何使用 ClickHouse 在开放表格式中查询、加速和回写数据。

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

<Info>
  **简而言之**

  本指南通过实践演示如何查询数据湖表、使用 MergeTree 对其进行加速，以及将结果回写到 Iceberg。所有步骤均使用公开数据集，并同时适用于 Cloud 和 OSS。
</Info>

本指南中的截图来自 [ClickHouse Cloud](https://console.clickhouse.cloud) 的 SQL 控制台。所有查询均适用于 Cloud 和自管理部署。

<Steps>
  <Step>
    ## 直接查询 Iceberg 数据

    最快的开始方式是使用 [`icebergS3()`](/zh/reference/functions/table-functions/iceberg) table function——将其指向 S3 中的 Iceberg 表，即可立即发起查询，无需任何设置。

    查看 schema：

    ```sql theme={null}
    DESCRIBE icebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')
    ```

    执行查询：

    ```sql theme={null}
    SELECT
        url,
        count() AS cnt
    FROM icebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')
    GROUP BY url
    ORDER BY cnt DESC
    LIMIT 5
    ```

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/ddNWBC5mE_w-syUp/images/datalake/iceberg-query-direct.png?fit=max&auto=format&n=ddNWBC5mE_w-syUp&q=85&s=c6aef3eac371cf007a33f27e811f4ea0" alt="Iceberg 查询" width="3836" height="1744" data-path="images/datalake/iceberg-query-direct.png" />

    ClickHouse 直接从 S3 读取 Iceberg 元数据，并自动推断 schema。同样的方法也适用于 [`deltaLake()`](/zh/reference/functions/table-functions/deltalake)、[`hudi()`](/zh/reference/functions/table-functions/hudi) 和 [`paimon()`](/zh/reference/functions/table-functions/paimon)。

    **了解更多：** [直接查询开放表格式](/zh/guides/use-cases/data-warehousing/getting-started/querying-directly) 涵盖这四种格式、用于分布式读取的集群变体，以及存储后端选项 (S3、Azure、HDFS、本地) 。
  </Step>

  <Step>
    ## 创建持久化表

    如需重复访问，可使用 Iceberg 表引擎创建一个表，这样就无需每次都传递 path。数据仍保存在 S3 中，不会发生数据复制：

    ```sql theme={null}
    CREATE TABLE hits_iceberg
        ENGINE = IcebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')
    ```

    现在可以像查询其他 ClickHouse 表一样查询它：

    ```sql theme={null}
    SELECT
        url,
        count() AS cnt
    FROM hits_iceberg
    GROUP BY url
    ORDER BY cnt DESC
    LIMIT 5
    ```

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/ddNWBC5mE_w-syUp/images/datalake/iceberg-query-engine.png?fit=max&auto=format&n=ddNWBC5mE_w-syUp&q=85&s=ce23b149547701490f3981f96eb455b9" alt="Iceberg 查询" width="3836" height="1744" data-path="images/datalake/iceberg-query-engine.png" />

    该表引擎支持数据缓存、元数据缓存、schema 演化和时间旅行。有关表引擎功能的详细信息，请参阅[直接查询](/zh/guides/use-cases/data-warehousing/getting-started/querying-directly)指南；如需查看完整的功能比较，请参阅[支持矩阵](/zh/guides/use-cases/data-warehousing/support-matrix)。
  </Step>

  <Step>
    ## 连接到目录

    大多数组织都会通过数据目录管理 Iceberg 表，以集中管理表元数据并进行数据发现。ClickHouse 支持使用 [`DataLakeCatalog`](/zh/reference/engines/database-engines/datalake) 数据库引擎连接到你的目录，并将目录中的所有表公开为一个 ClickHouse 数据库。这种方式扩展性更好，因此随着新的 Iceberg 表不断创建，无需额外操作，即可始终在 ClickHouse 中访问它们。

    下面是一个连接到 [AWS Glue](/zh/guides/use-cases/data-warehousing/glue-catalog) 的示例：

    ```sql theme={null}
    CREATE DATABASE my_lake
    ENGINE = DataLakeCatalog
    SETTINGS
        catalog_type = 'glue',
        region = '<your-region>',
        aws_access_key_id = '<your-access-key>',
        aws_secret_access_key = '<your-secret-key>'
    ```

    每种目录类型都需要单独的连接设置——有关受支持目录及其配置选项的完整列表，请参阅[目录指南](/zh/guides/use-cases/data-warehousing/reference)。

    浏览表并执行查询：

    ```sql theme={null}
    SHOW TABLES FROM my_lake;
    ```

    ```sql theme={null}
    SELECT count(*) FROM my_lake.`<database>.<table>`
    ```

    <Note>
      由于 ClickHouse 原生不支持多个命名空间，因此 `<database>.<table>` 必须用反引号括起来。
    </Note>

    **了解更多：** [连接到数据目录](/zh/guides/use-cases/data-warehousing/getting-started/connecting-catalogs) 介绍了完整的 Unity Catalog 配置流程，并提供了 Delta 和 Iceberg 示例。
  </Step>

  <Step>
    ## 执行查询

    无论你在上文使用的是哪种方式——表函数、表引擎还是 catalog——同一套 ClickHouse SQL 都适用于这三者：

    ```sql theme={null}
    -- 表函数
    SELECT url, count() AS cnt
    FROM icebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')
    GROUP BY url ORDER BY cnt DESC LIMIT 5

    -- 表引擎
    SELECT url, count() AS cnt
    FROM hits_iceberg
    GROUP BY url ORDER BY cnt DESC LIMIT 5

    -- 目录
    SELECT url, count() AS cnt
    FROM my_lake.`<database>.<table>`
    GROUP BY url ORDER BY cnt DESC LIMIT 5
    ```

    查询语法完全一致——只有 `FROM` 子句会发生变化。无论使用哪个数据源，所有 ClickHouse SQL 函数、JOIN 和聚合的用法都相同。
  </Step>

  <Step>
    ## 将部分数据加载到 ClickHouse

    直接查询 Iceberg 很方便，但其性能受限于网络吞吐量和文件布局。对于分析型工作负载，建议将数据加载到原生 MergeTree 表中。

    首先，对 Iceberg 表运行带过滤条件的查询，建立一个基线：

    ```sql theme={null}
    SELECT
        url,
        count() AS cnt
    FROM hits_iceberg
    WHERE counterid = 38
    GROUP BY url
    ORDER BY cnt DESC
    LIMIT 5
    ```

    此查询会扫描 S3 中的整个数据集，因为 Iceberg 无法识别 `counterid` 过滤条件——预计需要几秒钟。

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/ddNWBC5mE_w-syUp/images/datalake/iceberg-query.png?fit=max&auto=format&n=ddNWBC5mE_w-syUp&q=85&s=ee7be3390950a4d840ae3fcb5599d1b3" alt="Iceberg 查询" width="3836" height="1744" data-path="images/datalake/iceberg-query.png" />

    现在创建一个 MergeTree 表并加载数据：

    ```sql theme={null}
    CREATE TABLE hits_clickhouse
    (
        url String,
        eventtime DateTime,
        counterid UInt32
    )
    ENGINE = MergeTree()
    ORDER BY (counterid, eventtime);
    ```

    ```sql theme={null}
    INSERT INTO hits_clickhouse
    SELECT url, eventtime, counterid
    FROM hits_iceberg
    ```

    针对 MergeTree 表再次运行相同的查询：

    ```sql theme={null}
    SELECT
        url,
        count() AS cnt
    FROM hits_clickhouse
    WHERE counterid = 38
    GROUP BY url
    ORDER BY cnt DESC
    LIMIT 5
    ```

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/ddNWBC5mE_w-syUp/images/datalake/clickhouse-query.png?fit=max&auto=format&n=ddNWBC5mE_w-syUp&q=85&s=97ef1c0d0afe40dff99df42e8e3192b8" alt="ClickHouse 查询" width="3836" height="1744" data-path="images/datalake/clickhouse-query.png" />

    由于 `counterid` 是 `ORDER BY` 键中的第一列，ClickHouse 的稀疏主索引可以直接跳到相关粒度——只读取 `counterid = 38` 对应的行，而不必扫描全部 1 亿行。因此，查询速度会大幅提升。

    [加速分析](/zh/guides/use-cases/data-warehousing/getting-started/accelerating-analytics) 指南在此基础上进一步介绍了 `LowCardinality` 类型、全文索引和优化后的排序键，并展示了在一个 2.83 亿行数据集上实现 **约 40 倍性能提升** 的效果。

    **了解更多：**[使用 MergeTree 加速分析](/zh/guides/use-cases/data-warehousing/getting-started/accelerating-analytics) 涵盖了 schema 优化、全文索引，以及完整的性能优化前后对比。
  </Step>

  <Step>
    ## 回写到 Iceberg

    ClickHouse 还可以将数据回写到 Iceberg 表，从而支持反向 ETL 工作流——发布聚合结果或数据子集，供其他工具 (Spark、Trino、DuckDB 等) 使用。

    创建一个用于输出的 Iceberg 表：

    ```sql theme={null}
    CREATE TABLE output_iceberg
    (
        url String,
        cnt UInt64
    )
    ENGINE = IcebergS3('https://your-bucket.s3.amazonaws.com/output/', 'access_key', 'secret_key')
    ```

    写入聚合后的结果：

    ```sql theme={null}
    SET allow_experimental_insert_into_iceberg = 1;

    INSERT INTO output_iceberg
    SELECT
        url,
        count() AS cnt
    FROM hits_clickhouse
    GROUP BY url
    ORDER BY cnt DESC
    ```

    生成的 Iceberg 表可由任何兼容 Iceberg 的 engine 读取。

    **了解更多：**[将数据写入开放表格式](/zh/guides/use-cases/data-warehousing/getting-started/writing-data) 介绍了如何使用 UK Price Paid dataset 写入原始数据和聚合结果，包括将 ClickHouse 类型映射到 Iceberg 时的 schema 注意事项。
  </Step>
</Steps>

<div id="next-steps">
  ## 后续步骤
</div>

现在你已经看完了完整的工作流程，可以进一步深入了解各个部分：

* [直接查询](/zh/guides/use-cases/data-warehousing/getting-started/querying-directly) — 四种格式、集群方案、表引擎、缓存
* [连接到目录](/zh/guides/use-cases/data-warehousing/getting-started/connecting-catalogs) — 完整的 Unity Catalog 演练，涵盖 Delta 和 Iceberg
* [加速分析](/zh/guides/use-cases/data-warehousing/getting-started/accelerating-analytics) — schema 优化、索引、约 40 倍提速演示
* [写入数据湖](/zh/guides/use-cases/data-warehousing/getting-started/writing-data) — 原始写入、聚合写入、类型映射
* [支持矩阵](/zh/guides/use-cases/data-warehousing/support-matrix) — 不同格式和存储后端的功能对比