大网数据广告活动
数据库部署与 SQL 参考

Iceberg DDL 操作

· 52CE 我爱测

所有非分区列必须使用 作为默认值。分区列必须在非分区列之后定义,且不能使用 作为默认值。

Iceberg DDL 操作

本文档介绍 StarRocks 中 Iceberg catalog 的数据定义语言(DDL)操作,包括创建和管理数据库、表和视图。

您必须具有适当的权限才能执行 DDL 操作。有关权限的更多信息,请参阅权限。


CREATE DATABASE

在 Iceberg catalog 中创建数据库。此功能从 v3.1 开始支持。

语法

CREATE DATABASE [IF NOT EXISTS] <database_name>
[PROPERTIES ("location" = "<prefix>://<path_to_database>/<database_name.db>/")]

参数

  • location: 指定创建数据库的文件路径。支持 HDFS 和云存储。如果未指定,数据库将创建在 Iceberg catalog 的默认文件路径中。

prefix 根据存储系统而异:

  • HDFS: hdfs
  • Google GCS: gs
  • Azure Blob Storage (HTTP): wasb
  • Azure Blob Storage (HTTPS): wasbs
  • Azure Data Lake Storage Gen1: adl
  • Azure Data Lake Storage Gen2 (HTTP): abfs
  • Azure Data Lake Storage Gen2 (HTTPS): abfss
  • AWS S3 或 S3 兼容存储: s3

示例

CREATE DATABASE iceberg_db
PROPERTIES ("location" = "s3://my_bucket/iceberg_db/");

DROP DATABASE

从 Iceberg catalog 中删除空数据库。此功能从 v3.1 开始支持。

只能删除空数据库。删除数据库时,存储上的文件路径不会被删除。

语法

DROP DATABASE [IF EXISTS] <database_name>

示例

DROP DATABASE iceberg_db;

CREATE TABLE

在 Iceberg 数据库中创建表。此功能从 v3.1 开始支持。

语法

CREATE TABLE [IF NOT EXISTS] [database.]table_name
(
    column_definition1[, column_definition2, ...],
    partition_column_definition1, partition_column_definition2, ...
)
[partition_desc]
[ORDER BY sort_desc]
[PROPERTIES ("key" = "value", ...)]
[AS SELECT query]

参数

column_definition

col_name col_type [COMMENT 'comment'] [DEFAULT default_value]

所有非分区列必须使用 NULL 作为默认值。分区列必须在非分区列之后定义,且不能使用 NULL 作为默认值。

默认值

从 v4.1 开始,StarRocks 支持为 Iceberg 表的列设置默认值。此功能需要 Iceberg 格式版本 3 及以上。

用途:

  • 写入时填充:当执行 INSERT 语句时,如果未为某列指定值,系统将自动使用该列的默认值填充。
  • Schema Evolution 填充:当为已存在的表添加新列后,读取旧数据文件(不包含新列)时,系统将使用新列的默认值进行填充。

语法:

col_name col_type DEFAULT default_value

要求:

  • 表必须使用 Iceberg 格式版本 3 及以上。
  • 数值类型(INT、BIGINT、FLOAT、DOUBLE)、BOOLEAN、STRING 和 DATE/TIMESTAMP 类型的默认值必须使用引号包裹。例如:DEFAULT "18"、DEFAULT "100.0"、DEFAULT "true"。

示例:

  • 创建带有默认值的表:
CREATE TABLE user_info (
    id INT,
    name STRING,
    age INT DEFAULT "18",
    score DOUBLE DEFAULT "100.0",
    status STRING DEFAULT 'active',
    is_active BOOLEAN DEFAULT "true"
) PROPERTIES ("format-version" = "3");
  • 添加带有默认值的列:
ALTER TABLE user_info ADD COLUMN bonus DOUBLE DEFAULT "50.5";
  • 修改列的默认值:
ALTER TABLE user_info MODIFY COLUMN status STRING DEFAULT "inactive";

partition_desc

PARTITION BY (partition_expr[, partition_expr...])

每个 partition_expr 可以是:

  • column_name(标识转换)
  • transform_expr(column_name)
  • transform_expr(column_name, parameter)

StarRocks 支持以下分区转换:identity(列名或 identity())、year()、month()、day()、hour()、truncate()、bucket() 和 void()。使用其他转换会返回错误。

分区列支持除 FLOAT、DOUBLE、DECIMAL 和 DATETIME 之外的所有数据类型。

ORDER BY (v4.0+)

为 Iceberg 表指定排序键:

ORDER BY (column_name [ASC | DESC] [NULLS FIRST | NULLS LAST], ...)

PROPERTIES

关键表属性:

  • location: 表的文件路径。在使用 AWS Glue 且未指定数据库级别位置时是必需的。
  • file_format: 文件格式。仅支持 parquet(默认)。
  • compression_codec: 压缩算法。选项:SNAPPY、GZIP、ZSTD、LZ4(默认:zstd)。
  • format-version: 表的 Iceberg 格式版本。选项:1、2、3、4(默认:2)。格式版本 4 从 v26.4 开始支持,StarRocks 对格式版本 4 的表的读写与格式版本 3 相同。Iceberg 将格式版本 4 的表的 Manifest 写为 Parquet 文件。格式版本 4 的表的 location 必须带 URI scheme,例如 s3:// 或 hdfs://,因此 location 不带 scheme 的表无法升级到格式版本 4。
  • write.metadata.metrics.default: StarRocks 写入数据文件的列统计信息的默认 metrics 模式。选项:none、counts、truncate(N)、full(默认:truncate(16))。none 不写统计信息,counts 只写值个数和 NULL 个数,truncate(N) 还会写上下界,其中 STRING 和 BINARY 的上下界截断为 N 个字符(字节),full 写不截断的上下界。
  • write.metadata.metrics.column.<col>: 列 <col> 的 metrics 模式,覆盖默认模式。选项与 write.metadata.metrics.default 相同。
  • write.metadata.metrics.max-inferred-column-defaults: 未设置 write.metadata.metrics.default 时,只有前 N 列使用默认的 truncate(16),其余列为 none(默认:100)。

示例

创建非分区表:

CREATE TABLE unpartition_tbl
(
    id int,
    score double
);

创建分区表:

CREATE TABLE partition_tbl
(
    action varchar(20),
    id int,
    dt date
)
PARTITION BY (id, dt);

创建具有隐藏分区的表:

CREATE TABLE hidden_partition_tbl
(
    action VARCHAR(20),
    id INT,
    dt DATE
)
PARTITION BY bucket(id, 10), year(dt);

通过查询创建表:

CREATE TABLE new_tbl
PARTITION BY (id, dt)
AS SELECT * FROM existing_tbl;

ALTER TABLE(演进分区规范)

通过添加或删除分区列来修改 Iceberg 表的分区规范。

语法

ALTER TABLE [catalog.][database.]table_name
ADD PARTITION COLUMN partition_expr [, partition_expr ...];

ALTER TABLE [catalog.][database.]table_name
DROP PARTITION COLUMN partition_expr [, partition_expr ...];

ALTER TABLE [catalog.][database.]table_name
REPLACE PARTITION COLUMN old_partition_expr WITH new_partition_expr;

支持的 partition_expr 格式:

  • 列名(标识转换)
  • 转换表达式:year()、month()、day()、hour()、truncate()、bucket()

示例

添加分区列:

ALTER TABLE sales_data
ADD PARTITION COLUMN month(sale_date), bucket(customer_id, 10);

删除分区列:

ALTER TABLE sales_data
DROP PARTITION COLUMN day(sale_date);

替换分区列:

ALTER TABLE sales_data
REPLACE PARTITION COLUMN day(sale_date) WITH month(sale_date);

ALTER TABLE(添加或删除嵌套字段)

在 STRUCT 列或其中嵌套的 STRUCT 中添加或删除字段。

ALTER TABLE [catalog.][database.]table_name MODIFY COLUMN column_name
ADD FIELD field_path field_type [FIRST | AFTER field_name];

ALTER TABLE [catalog.][database.]table_name MODIFY COLUMN column_name
DROP FIELD field_path;

field_path 是字段在列中的路径,例如 c2.v3。ARRAY 的元素用 [*] 表示,例如 c2.[*].v3。

对于使用 Hive metastore 的 Catalog,如果 metastore 配置为不允许不兼容的列类型变更(hive.metastore.disallow.incompatible.col.type.changes),该变更会被 metastore 拒绝。

示例:

假设列 fx 的类型为 STRUCT<c1 INT, c2 ARRAY<STRUCT<v1 INT>>>。

-- 在 ARRAY c2 内的 STRUCT 中添加字段 v2
ALTER TABLE t MODIFY COLUMN fx ADD FIELD c2.[*].v2 STRING AFTER v1;
-- 删除字段 c1
ALTER TABLE t MODIFY COLUMN fx DROP FIELD c1;

DROP TABLE

删除 Iceberg 表。此功能从 v3.1 开始支持。

删除表时,默认情况下不会删除存储上的文件路径和数据。

语法

DROP TABLE [IF EXISTS] <table_name> [FORCE]

参数

  • FORCE: 指定时,删除表在存储上的数据,同时保留文件路径。

示例

DROP TABLE iceberg_db.sales_data;

-- 强制删除并删除数据
DROP TABLE iceberg_db.temp_data FORCE;

CREATE VIEW

创建 Iceberg 视图。此功能从 v3.5 开始支持。

语法

CREATE VIEW [IF NOT EXISTS]
[<catalog>.<database>.]<view_name>
(
    <column_name> [COMMENT 'column comment']
    [, <column_name> [COMMENT 'column comment'], ...]
)
[COMMENT 'view comment']
[PROPERTIES ("key" = "value", ...)]
AS <query_statement>

示例

CREATE VIEW IF NOT EXISTS iceberg_db.sales_summary AS
SELECT region, SUM(amount) as total_sales
FROM iceberg_db.sales
GROUP BY region;

使用属性(v4.0.3+):

CREATE VIEW IF NOT EXISTS iceberg_db.sales_summary
PROPERTIES (
  "key1" = "value1"
)
AS
SELECT region, SUM(amount) as total_sales
FROM iceberg_db.sales
GROUP BY region;

ALTER VIEW

为现有的 Iceberg 视图添加或修改 StarRocks 方言。此功能从 v3.5 开始支持。

您只能为每个 Iceberg 视图定义一个 StarRocks 方言。

语法

ALTER VIEW [<catalog>.<database>.]<view_name>
(
    <column_name> [, <column_name>]
)
{ ADD | MODIFY } DIALECT
<query_statement>

示例

添加 StarRocks 方言:

ALTER VIEW iceberg_db.spark_view ADD DIALECT
SELECT k1, k2 FROM iceberg_db.source_table;

修改 StarRocks 方言:

ALTER VIEW iceberg_db.spark_view MODIFY DIALECT
SELECT k1, k2, k3 FROM iceberg_db.source_table;

本文来自 StarRocks 文档贡献者,按 Apache 2.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
StarRocks 文档贡献者
适用范围
main 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
Apache 2.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。