Iceberg外表（XIHE SQL）

语法

CREATE TABLE [IF NOT EXISTS] <db>.<table> (
    <col1>  <type1>  [COMMENT '<comment>'],
    <col2>  <type2>  [COMMENT '<comment>'],
    ...
)
[COMMENT '<table_comment>']
[PARTITIONED BY (<partition_expr1>[, <partition_expr2>, ...])]
STORED AS ICEBERG
[LOCATION '<oss_path>']                           -- 外湖必填
[TBLPROPERTIES (
    'format_version'    = '<2|3>',                 -- 默认2
    'catalog_type'      = 'ADB',                   -- 内湖必填
    'adb_lake_bucket'   = '<bucket_name>',          -- 内湖必填
    ...
)];

TBLPROPERTIES中可配置的表属性如下：

外湖建表示例

-- 创建数据库
CREATE DATABASE IF NOT EXISTS lake_db;

-- 创建外湖Iceberg表
CREATE TABLE lake_db.orders (
    order_id     BIGINT       COMMENT '订单ID',
    user_id      BIGINT       COMMENT '用户ID',
    status       STRING       COMMENT '订单状态',
    total_amount DECIMAL(18, 2) COMMENT '订单金额',
    created_at   TIMESTAMP    COMMENT '下单时间'
)
COMMENT '订单主表'
PARTITIONED BY (dt DATE)
STORED AS ICEBERG
LOCATION 'oss://<YOUR-BUCKET>/warehouse/lake_db/orders/';

内湖建表示例

CREATE TABLE lake_db.orders (
    order_id     BIGINT       COMMENT '订单ID',
    user_id      BIGINT       COMMENT '用户ID',
    status       STRING       COMMENT '订单状态',
    total_amount DECIMAL(18, 2) COMMENT '订单金额',
    created_at   TIMESTAMP    COMMENT '下单时间'
)
COMMENT '订单主表'
PARTITIONED BY (dt DATE)
STORED AS ICEBERG
TBLPROPERTIES (
    'catalog_type'    = 'ADB',
    'adb_lake_bucket' = 'adb-lake-cn-<region>-xxxx'
);

CTAS建表（CREATE TABLE AS SELECT）

CTAS在建表的同时写入查询结果，列名和类型从SELECT推导。

CREATE TABLE lake_db.orders_copy
PARTITIONED BY (dt DATE)
STORED AS ICEBERG
LOCATION 'oss://<YOUR-BUCKET>/warehouse/lake_db/orders_copy/'
AS SELECT * FROM lake_db.orders;

分区管理

Iceberg的分区与传统Hive分区有本质区别：

Iceberg支持identity分区（直接使用列值）和基于现有列的转换函数分区。写入时无需指定分区值，引擎根据列值自动路由。

针对不同数据特征，常用的分区场景与示例如下：

• 按时间维度分区（day，最常用）：时序数据按天分区最常用，兼顾查询性能与管理成本。使用day(created_at)分区时，无需单独维护dt列，Iceberg自动从created_at提取日期做分区。

  CREATE TABLE lake_db.orders_by_day (
      order_id     BIGINT,
      user_id      BIGINT,
      status       STRING,
      total_amount DECIMAL(18, 2),
      created_at   TIMESTAMP
  )
  PARTITIONED BY (day(created_at))
  STORED AS ICEBERG
  LOCATION 'oss://<YOUR-BUCKET>/warehouse/lake_db/orders_by_day/';

• 基于低基数分类字段进行分区（identity）：字段取值枚举少（如市场细分、地区），适合按原值分区。

  -- 按市场细分 mktsegment 原值分区，该字段仅少数几个枚举值，适合 identity
  CREATE TABLE lake_db.customer (
      c_custkey     BIGINT,
      c_name        STRING,
      c_acctbal     DECIMAL(15,2),
      c_mktsegment  STRING   -- 低基数：'AUTOMOBILE'、'BUILDING'、'FURNITURE' 等
  )
  PARTITIONED BY (c_mktsegment)
  STORED AS ICEBERG
  LOCATION 'oss://<YOUR-BUCKET>/warehouse/lake_db/customer/';

• 高频事件按小时分区（hour）：数据写入频繁、需近实时监控时，可按小时分区。

  -- 按收货时间戳的小时分区，支持近实时监控
  CREATE TABLE lake_db.lineitem_realtime (
      l_orderkey      BIGINT,
      l_partkey       BIGINT,
      l_quantity      DECIMAL(15,2),
      l_receipttime   TIMESTAMP   -- 精确到秒的收货时间
  )
  PARTITIONED BY (hour(l_receipttime))
  STORED AS ICEBERG
  LOCATION 'oss://<YOUR-BUCKET>/warehouse/lake_db/lineitem_realtime/';

• 基于高基数字段哈希分桶（bucket）：对高基数字段（如 ID）哈希分桶，可避免小文件并提升 JOIN 性能。

  -- 对高基数外键 l_partkey 哈希分 64 桶，均匀分布数据
  CREATE TABLE lake_db.lineitem (
      l_orderkey      BIGINT,
      l_partkey       BIGINT,      -- 高基数字段（约 2000 万唯一值）
      l_quantity      DECIMAL(15,2),
      l_shipdate      DATE
  )
  PARTITIONED BY (bucket(l_partkey, 64))
  STORED AS ICEBERG
  LOCATION 'oss://<YOUR-BUCKET>/warehouse/lake_db/lineitem/';

• 字符串前缀截断分区（truncate）：按字符串前若干位聚合分区，适合按前缀归类的场景。

  -- 按电话号码前 3 位分区（如 '13-' 代表某运营商号段）
  CREATE TABLE lake_db.customer_by_phone (
      c_custkey     BIGINT,
      c_name        STRING,
      c_phone       STRING       -- 格式：'13-888-999-1234'
  )
  PARTITIONED BY (truncate(c_phone, 3))
  STORED AS ICEBERG
  LOCATION 'oss://<YOUR-BUCKET>/warehouse/lake_db/customer_by_phone/';

• 多级复合分区：组合多个分区方式，在分区数量与数据均匀性之间取得平衡，适用于海量数据查询场景。

  -- 用户行为日志表：按天分区 + 高基数 ID 分桶 + 区域前缀截断，三级复合分区
  CREATE TABLE lake_db.user_event_log (
      event_id      BIGINT,
      user_id       BIGINT,          -- 高基数用户 ID
      event_type    STRING,
      event_time    TIMESTAMP,       -- 精确到秒的时间戳
      country_code  STRING           -- 国家代码，如 'CN'、'US'、'DE'
  )
  PARTITIONED BY (
      day(event_time),            -- 第一级：按天分区，高效时间裁剪
      bucket(user_id, 64),        -- 第二级：对高基数 user_id 哈希分 64 桶，防小文件
      truncate(country_code, 2)   -- 第三级：截取国家代码前 2 位，区域聚合
  )
  STORED AS ICEBERG
  LOCATION 'oss://<YOUR-BUCKET>/warehouse/lake_db/user_event_log/';

其他DDL操作

-- 查看表的完整建表语句
SHOW CREATE TABLE lake_db.orders;

-- 查看列结构
DESCRIBE lake_db.orders;

-- 删除表
DROP TABLE IF EXISTS lake_db.orders;

-- 删除数据库（库内不能有表，否则报错）
DROP DATABASE IF EXISTS lake_db;

INSERT INTO（追加写入）

INSERT INTO lake_db.orders
SELECT * FROM VALUES
    (1001, 501, 'paid', 299.90, TIMESTAMP '2026-06-11 10:00:00', DATE '2026-06-11'),
    (1002, 502, 'pending', 158.00, TIMESTAMP '2026-06-11 10:05:00', DATE '2026-06-11'),
    (1003, 503, 'shipped', 450.00, TIMESTAMP '2026-06-11 10:10:00', DATE '2026-06-12')
AS t(order_id, user_id, status, total_amount, created_at, dt);

INSERT OVERWRITE（覆写）

对分区表执行INSERT OVERWRITE时，Iceberg采用动态分区覆写策略——仅覆盖SELECT结果中涉及的分区，其余分区数据不受影响。

-- 仅覆盖dt='2026-06-11'分区的数据，其他分区不受影响
INSERT OVERWRITE lake_db.orders
SELECT * FROM VALUES
    (2001, 601, 'paid', 999.00, TIMESTAMP '2026-06-11 12:00:00', DATE '2026-06-11')
AS t(order_id, user_id, status, total_amount, created_at, dt);

DELETE（行级删除）

Iceberg表支持基于条件的行级删除。使用DELETE前，需在建表时将format_version设置为'3'。

-- 建表时指定 format_version=3，以支持行级删除
CREATE TABLE lake_db.orders_v3 (
    order_id     BIGINT,
    user_id      BIGINT,
    status       STRING,
    total_amount DECIMAL(18, 2),
    created_at   TIMESTAMP
)
PARTITIONED BY (day(created_at))
STORED AS ICEBERG
LOCATION 'oss://<YOUR-BUCKET>/warehouse/lake_db/orders_v3/'
TBLPROPERTIES (
    'format_version' = '3'
);

-- 删除满足条件的行
DELETE FROM lake_db.orders_v3 WHERE status = 'cancelled';

基本查询

SELECT * FROM lake_db.orders WHERE dt = DATE '2026-06-11';

SELECT dt, COUNT(*) AS cnt, SUM(total_amount) AS total
FROM lake_db.orders
GROUP BY dt;

分区裁剪

当WHERE条件中包含分区列或分区转换函数时，引擎自动进行分区裁剪，只扫描相关分区的数据文件。

-- identity分区：直接匹配分区列
SELECT * FROM lake_db.orders WHERE dt = DATE '2026-06-11';

-- day(col)分区：匹配时间范围
SELECT * FROM lake_db.orders_by_day
WHERE created_at >= TIMESTAMP '2026-06-11 00:00:00'
  AND created_at <  TIMESTAMP '2026-06-12 00:00:00';

谓词下推

Iceberg将WHERE条件中的谓词下推到数据文件层面，利用Parquet文件内部的统计信息（min/max/null count）过滤不满足条件的row group，减少实际读取的数据量。

谓词下推生效条件：

• WHERE条件中的列存在统计信息。

• 谓词为简单比较（=、<、>、<=、>=、IN、BETWEEN）。

• 列类型与统计信息类型匹配。

-- 谓词下推生效：order_id有min/max统计信息
SELECT * FROM lake_db.orders
WHERE order_id = 1001;

-- 范围谓词下推
SELECT * FROM lake_db.orders
WHERE total_amount BETWEEN 100 AND 500;

查询注意事项

• 分区裁剪仅对WHERE条件中直接引用分区列或分区转换函数的场景生效。

• 复杂谓词（如函数调用、OR条件）可能影响谓词下推效果。

• 跨Iceberg表JOIN性能取决于数据量和分区设计。