data-lake-platform

数据湖平台

构建和运营可投入生产的数据湖和湖仓：可靠地摄取数据、以开放表格式存储数据、编目、维护并提供分析服务。数据转换（dbt/SQLMesh）和数据质量测试归属 data-analytics-engineering；Kafka/Flink 流式处理归属 data-streaming。

快速参考

任务	资源
选择表格式和规范版本	references/storage-formats.md
选择目录 / 控制平面	references/governance-catalog.md
设计批处理或 CDC 摄取路径	references/ingestion-patterns.md
搭建或检查 Iceberg 表	scripts/scaffold_iceberg_table.py、scripts/inspect_iceberg_metadata.sh
核实任何版本、规范支持或供应商功能状态声明	版本与支持查询

快速入门决策表

情况	默认选择
开放的多引擎分析	Iceberg + REST catalog（Polaris/Glue/Nessie）+ Trino/Spark
以 Databricks 为主要计算引擎	Delta + Unity Catalog；仅在存在外部读取方时添加 UniForm
以 CDC 为主、数据频繁变更且以 Spark 为核心	Hudi（读密集型用 CoW，写密集型用 MoR）+ Kafka/Debezium
以流式处理为主、数据频繁变更且以 Flink 为核心	Paimon + Flink CDC
单引擎嵌入式 / 分析师工作站	DuckLake，或 DuckDB + Parquet/Iceberg
低延迟 BI、高并发仪表板	ClickHouse 或 StarRocks 服务层，由数据湖供数
异构环境（Hive + Kafka + RDBMS）	Apache Gravitino，作为联邦式“目录的目录”

格式对比

属性	Apache Iceberg	Delta Lake	Apache Hudi	Apache Paimon
规范 / 协议	格式 v2 是广泛兼容性的基准；v3 支持情况因引擎而异（查询）	按表启用协议功能（读取方 / 写入方功能）	表版本随发布系列而定	以 Flink 为先的 LSM 表格式
行级删除	位置删除 / 等值删除文件（v2）；删除向量（v3 规范）	删除向量	MoR 日志文件	LSM 合并
目录策略	REST catalog 优先	由目录管理的表（Unity Catalog）	混合	Flink catalog 优先
分支和标签	一等支持	有限	因工作流而异	因工作流而异
多引擎读取	支持最广（Trino、Spark、DuckDB、Flink）	通过 UniForm 和原生连接器支持	支持范围较窄；需验证	支持范围较窄；需验证

• DuckLake 将目录保存在 SQL 数据库中（SQLite、PostgreSQL 或 DuckDB）。它适用于单引擎或小团队湖仓，不适合 Spark/Flink 并发写入。
• 如果任何必需引擎尚无法使用行级更新、删除和维护功能写入 v3，则默认采用 Iceberg 格式 v2。只有在下方的验证矩阵通过所有引擎验证后，才选择 v3。

决策树

Choosing a lakehouse path:
    ├─ Databricks is the primary platform?
    │   └─ Delta + Unity Catalog; add UniForm only if external readers matter
    ├─ Need open multi-engine access across Trino/Spark/DuckDB?
    │   └─ Iceberg + Polaris / Glue REST / Nessie / Open Catalog
    │       format v2 unless every writer passes v3 row-level ops and maintenance
    ├─ Heavy CDC, mutable tables, or streaming-first semantics?
    │   ├─ Flink-native stack -> Paimon first, compare with Hudi
    │   └─ Spark-heavy stack  -> Hudi first (CoW read-heavy, MoR write-heavy)
    ├─ Single-engine embedded or analyst workstation?
    │   └─ DuckLake (PostgreSQL catalog for multi-instance) or DuckDB + Parquet
    │       name the upgrade trigger to Iceberg (2nd engine or concurrent writers)
    ├─ Low-latency dashboards or embedded analytics?
    │   ├─ High-concurrency BI, proven by load test -> add ClickHouse / StarRocks / Doris
    │   └─ Local, notebook, CI -> DuckDB + Parquet/Iceberg
    └─ Heterogeneous multi-format estate?
        └─ Gravitino federation over existing catalogs

目录概览

目录	最适合	注意事项
Apache Polaris	开源的可自托管 Iceberg 控制平面	仍需单独的元数据 / 血缘工具
Glue Iceberg REST + S3 Tables	AWS 原生托管 Iceberg	以 AWS 为中心；托管表会自行执行压缩，因此不要重复安排
Snowflake Open Catalog	与 Snowflake 相邻的开放 Iceberg 互操作	验证写入路径和服务主体
Project Nessie	分支 / 标签晋级、隔离回填	治理范围较窄
Unity Catalog	以 Databricks 为中心的治理与计算	必须验证跨引擎行为
Apache Gravitino	联邦式多格式元数据	按部署验证生产就绪程度
DuckLake	单引擎或小团队的 SQL 原生湖仓	并非为 Spark/Flink 并发写入而设计

推荐前，请查询每一行对应的功能状态和 IAM 模型。

互操作性验证矩阵

在针对确切工作负载，为每条必需路径明确验证结果之前，平台选择都只是暂定的：

路径	验证方式
每个写入方 -> 目录 -> 表	创建、追加、架构演进、并发提交
每个读取方 -> 目录 -> 表	谓词下推、删除、时间旅行、所需类型
运维	压缩、快照过期、孤立文件清理、失败作业恢复
故障与回滚	部分提交、凭据中断、重放、恢复到先前快照

将每个单元格标记为 pass、unsupported 或 unverified，并注明引擎和连接器版本。规范中的功能或供应商的 GA 标签都不能让某个单元格通过验证。如果必需的单元格不受支持，请使用最低共同格式版本，或在承诺投入生产之前调整架构。

版本与支持情况查询

本技能有意不包含发布版本号、GA 日期或各引擎的支持状态，因为这些信息会随版本变化。本节是唯一说明如何查询这些信息的地方；其他文件均指向此处。

1. 准确描述要核实的说法：格式和规范版本（例如 Iceberg format v3）、功能（行级更新/删除、删除向量、行沿袭、OPTIMIZE/压缩、Variant 类型）以及操作（读取、写入、维护）。
2. 分别检查每个引擎，查看其自身文档或发布说明；对于 Trino，请查看 Iceberg 连接器页面；对于托管平台，请查看供应商的发布说明，而不是合作伙伴的博客。引擎的供应商发行版（例如商业版 Trino 发行版）与开源引擎是不同产品；有人说“Trino”时，切勿混为一谈。
3. 区分各个层面：“规范支持 X”≠“此引擎构建版本支持 X”≠“此目录和客户端库支持 X”。只有引擎、目录和客户端都支持某项功能时，该功能才可用。
4. 区分各类标签：GA、公开预览、实验性和只读代表不同的状态。平台达到 GA 不代表每项功能或外部客户端都达到 GA。
5. 来源等级：使用 data/sources.json 中 trust_tier: primary 的来源（项目发布说明、规范、供应商发布说明）。博客和聚合网站常常混淆预览版与 GA。
6. 临近上线时重新检查；在验证矩阵中记录已核实的版本和日期。
7. 如果无法浏览网页，请说明这一点，并将依赖版本或状态的建议标记为未经验证。

Delta 目录管理的表和协调提交、目录的功能状态（S3 Tables、Open Catalog、Unity Catalog、Gravitino、DuckLake），以及所有格式和引擎的当前版本，都遵循相同的流程。

工作流检查清单

在说明版本、功能状态、价格或基准测试数据之前，请先执行版本与支持情况查询。只有在阅读过基准测试所用的数据集结构和来源后，才引用基准测试结果；否则只说明趋势并注明不确定性。

1. 架构与数据摄取

• 选择架构模式：references/architecture-patterns.md
• 定义 CDC 或批量摄取路径：references/ingestion-patterns.md
• 如有需要，确定流处理语义：data-streaming 技能
• 如果组织采用分布式模式，确定领域所有权：references/data-mesh-patterns.md

2. 存储与目录

• 选择格式和规范版本：references/storage-formats.md；填写验证矩阵
• 选择目录：references/governance-catalog.md
• 在首次生产写入之前，安排压缩、快照保留和孤立文件清理

3. 转换与编排

• 转换工具和增量模型：data-analytics-engineering 技能；确认其支持目标目录和格式
• 编排器：references/orchestration-patterns.md

4. 查询与服务

• 数据湖查询引擎：references/query-engine-patterns.md
• 只有在并发或延迟要求得到验证后，才添加服务层
• BI 层：references/bi-visualization-patterns.md

5. 质量、安全与运维

• 质量契约与检查：data-analytics-engineering（data-quality-testing、lake-data-quality-patterns）
• 各引擎的访问控制：references/security-access-patterns.md
• 运维手册：references/operational-playbook.md
• 文件大小目标、保留策略与成本防护措施：references/cost-optimization.md

快速命令

# Generate Spark SQL DDL for a partitioned Iceberg table (exits non-zero on unknown/invalid partition columns):
python scripts/scaffold_iceberg_table.py --catalog rest --name analytics.events \
  --columns "event_id BIGINT, user_id BIGINT, event_type STRING, ts TIMESTAMP" \
  --partition ts_month,event_type --format-version 2 --target-file-size-mb 256

# Inspect S3-backed Iceberg table layout:
./scripts/inspect_iceberg_metadata.sh --location s3://my-bucket/warehouse/analytics/events --backend s3

# Iceberg maintenance order (Spark procedures; Trino: ALTER TABLE ... EXECUTE expire_snapshots/remove_orphan_files/optimize).
# older_than = now minus the time-travel window, computed by the scheduler; never hard-code a date.
CALL catalog.system.expire_snapshots(table => 'db.events', older_than => TIMESTAMP '<retention cutoff>', retain_last => <retained-snapshot-count-from-policy>);
# Preview orphan candidates; review the result before a separate cleanup call.
CALL catalog.system.remove_orphan_files(table => 'db.events', older_than => TIMESTAMP '<older than longest write>', dry_run => true);
CALL catalog.system.rewrite_data_files('db.events');
CALL catalog.system.rewrite_manifests('db.events');

应做 / 避免

应做

• 在首次写入前定义数据契约、负责人和保留规则。
• 确保每条流水线都具备幂等性、可重放性，并能安全地回填数据。
• 明确指定目录、血缘和访问控制方面的选择。
• 在承诺支持多引擎之前，先在真实引擎上验证互操作性（证明矩阵）。
• 通过版本与支持情况查询核实任何有关规范版本或供应商状态的说法。

避免

• 将 Delta、Iceberg、Hudi 和 Paimon 视为可互换的格式。
• 仅因供应商的标题宣称“支持”，就在线上启用某个格式版本或功能——这可能只是预览版或只读支持，而且可能只适用于部分客户端。
• 将治理隐藏在单一的供应商专属默认设置中。
• 在未处理删除、未制定保留策略、未进行重放演练的情况下上线 CDC。

常见陷阱

• 在验证实际环境中的引擎支持、目录行为、删除语义和维护工具之前，就为了适配供应商而选择表格式。
• 将对象存储加开放表格式视为完整平台，却放任压实、快照保留、元数据清理和孤立文件控制无人管理。
• 在同一张表中混用 CDC upsert、流式摄取和批量重写，却没有明确的幂等性、迟到数据和回滚规则。
• 假设所有引擎对架构演进、分区裁剪、删除文件和时间旅行的解释都一致。
• 将数据仓库式的小表习惯照搬到数据湖，导致小文件、清单和元数据在大规模下急剧膨胀。
• 假设 DuckLake 可与 Iceberg REST 互换，用于多引擎工作负载。
• 将协调提交或目录管理的表（Delta、Iceberg REST）迁移视为一个配置标志。这会改变提交路径的所有权，并可能要求升级每个读取方和写入方的客户端/连接器——应将其作为一次迁移来执行，并制定回滚计划。
• 只因某种格式有最亮眼的功能（行沿袭、删除向量、Variant）就选择它，却不检查客户端自己的目录、引擎和客户端库是否能使用这些功能。
• 将 Apache 顶级项目地位视为生产就绪。毕业是治理里程碑；应分别检查采用情况、发布节奏和运维体验。
• 在所有读取方通过验证矩阵之前升级 Iceberg 表的 format-version。升级是单向的（无法降级），因此落后的读取方会被排除在外；在此之前，新表应继续使用 v2（storage-formats.md）。
• 将 DELETE 视为数据擦除。行在旧快照中仍然可读，直到快照过期且物理文件被移除（Delta：VACUUM）；应确保时间旅行窗口短于擦除期限，并清除原始/bronze 数据及 CDC 副本（security-access-patterns.md）。
• 基于时间戳游标的增量加载（updated_at > last_max）会悄无声息地漏掉硬删除，以及以较早时间戳迟到提交的行。应使用基于日志的 CDC 或软删除列，重新读取一个回溯窗口，在边界处使用 >= 进行比较，并按键合并（ingestion-patterns.md）。
• 放任概念验证阶段对单一引擎的选择（DuckLake、嵌入式 DuckDB）悄然进入生产环境，直到第二个团队需要并发写入或使用另一个引擎。

导航

参考资料（按需加载）

文件	加载时机
references/architecture-patterns.md	选择 medallion、lambda、kappa 或 lakehouse 分层时
references/data-mesh-patterns.md	领域所有权、数据产品、联合治理
references/ingestion-patterns.md	批量或 CDC 摄取路径（dlt、Airbyte、Debezium）
references/orchestration-patterns.md	选择或配置编排器
references/storage-formats.md	格式选择、文件大小、压缩、Iceberg v3 就绪情况
references/governance-catalog.md	目录、血缘和元数据选择
references/query-engine-patterns.md	选择 Trino、Spark、DuckDB、ClickHouse 或 StarRocks
references/bi-visualization-patterns.md	数据湖上的 BI 层
references/security-access-patterns.md	表／行／列策略和引擎级 ACL
references/operational-playbook.md	压缩、恢复和 on-call 操作手册
references/cost-optimization.md	文件大小目标、保留期限、成本防护措施

模板（assets/）

• 蓝图：medallion、pipeline、migration、partitioning、schema evolution、cost
• 数据摄取：治理清单、增量加载、dlt（REST API 来源、数据库来源、增量与合并、仓库加载）、Airbyte、Dagster
• 质量：数据质量、质量治理、回填运行手册
• 格式：Iceberg 表、Iceberg 维护、Delta、Hudi、Parquet
• 引擎和 BI：DuckDB、DuckDB 导入/导出、ClickHouse、ClickHouse 设置、ClickHouse 数据摄取、ClickHouse 复制与分片、ClickHouse 物化视图、StarRocks、Doris、Metabase 请求、Metabase 连接清单、Metabase 事故处理手册

相关技能

• data-streaming - Kafka、Flink、CDC，以及向数据湖进行流式数据摄取
• data-analytics-engineering - dbt/SQLMesh 转换、语义层、数据质量测试
• ai-mlops - MLOps、部署、平台运维
• ai-ml-data-science - 分析和特征工程工作流
• data-sql-optimization - OLTP 调优和关系型操作
• ops-devops-platform - 基础设施、Kubernetes、可观测性和运行手册

经验反馈循环

如果以往的决策或陷阱与当前情况相关，请查阅 learnings.consolidated.md（如果存在）；仅在需要查看历史记录或将其作为可用备选时查阅 learnings.md。否则跳过这两个文件。

应用后，如果遇到值得记住的模式、值得避免的错误或令你意外的领域事实，请通过 agents-skills-feedback-loop/scripts/append_learning.py 向 learnings.md 追加一条带日期的项目。不要修改 SKILL.md 本身。