使用 Apache Iceberg v3 功能

Apache Iceberg v3 提升了查询性能，并为 Unity Catalog 中使用 Iceberg 的托管表以及支持 Iceberg 读取的 Delta Lake 托管表引入了新能力。

Iceberg v3 的主要功能包括：

• VARIANT 数据类型：支持存储和处理半结构化数据。 请参阅 Apache Iceberg 和 Delta Lake 的 Variant 类型支持。
• 行世系：跟踪对表数据的增量更改。 请参阅 Azure Databricks 中的行跟踪。
• 几何和地理数据类型：存储和查询地理空间数据，用于空间分析和连接。 参见 GEOMETRY 类型 和 GEOGRAPHY 类型。
• 写入默认值：指定当写入操作省略某一列时应用于新行的列值。 参见 创建带有写默认值的表。

要求

要使用带有 Iceberg v3 功能的托管表，如地理空间类型，您必须满足以下要求：

• 一个启用了 Unity Catalog 的工作区。
• Databricks Runtime 18 LTS 及更高版本。

使用 Iceberg v3 创建新表

为支持 Iceberg 读取的托管 Delta Lake 表和托管 Iceberg 表创建启用 Iceberg v3 的新表。

Delta Lake

要使用 Delta Lake 创建新的托管表，支持 Iceberg 读取并启用 Iceberg v3，请使用以下 SQL 命令：

CREATE OR REPLACE TABLE main.schema.table (c1 INT) TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'iceberg',
  'delta.enableIcebergCompatV3' = 'true'
);

有关 Iceberg 读取的更多信息，请参阅 使用 Iceberg 客户端读取 Delta Lake 表。

Iceberg

若要使用 Iceberg v3 创建新的托管表，请使用以下 SQL 命令：

CREATE OR REPLACE TABLE main.schema.table (c1 INT)
USING iceberg
TBLPROPERTIES ('format-version' = 3);

有关 Iceberg 表的详细信息，请参阅《Azure Databricks 中的 Apache Iceberg 是什么？》。

将现有表升级到 Iceberg v3

可以通过以下方式将现有表升级到 Iceberg v3：

1. 启用表上的任何 v3 功能。

2. 将数据表的 Iceberg 格式版本设置为 3（如下所示）。

   Important

   可以通过将表恢复到升级到 v3 之前的表版本，将表从 v3 降级到 v2 RESTORE。 请参阅 将表降级到以前的版本。

Delta Lake

要将使用 Delta Lake 且支持 Iceberg 读取的受管表升级到 v3，请使用以下命令：

ALTER TABLE catalog.schema.table SET TBLPROPERTIES(
  'delta.enableIcebergCompatV3' = 'true',
  'delta.enableIcebergCompatV2' = 'false'
);

Iceberg

若要使用 Iceberg 升级到 v3 的托管表，请使用以下命令：

ALTER TABLE catalog.schema.table SET TBLPROPERTIES (
  'format-version' = 3
);

Delta Lake

要使用Delta Lake创建一个新的管理表，启用Iceberg读取、Iceberg v3和删除向量，请设置以下表属性：

CREATE TABLE catalog.schema.table (c1 INT) TBLPROPERTIES(
  'delta.enableDeletionVectors' = 'true',
  'delta.enableIcebergCompatV3' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg'
);

Iceberg

若要使用已启用删除矢量的 Iceberg v3 创建新的托管表，请设置 iceberg.enableDeletionVectors 表属性：

CREATE TABLE catalog.schema.table (c1 INT)
USING ICEBERG TBLPROPERTIES (
  'iceberg.enableDeletionVectors' = 'true'
);

使用 VARIANT 数据类型

VARIANT 数据类型允许存储和查询半结构化数据。

Delta Lake

要使用 Delta Lake 创建一个新的托管表，包含 Iceberg 读取和 VARIANT 列：

CREATE TABLE catalog.schema.deltaTable (col VARIANT) TBLPROPERTIES(
  'delta.enableIcebergCompatV3' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg'
);

Iceberg

若要使用 Iceberg v3 创建包含 VARIANT 列的新托管表，

CREATE TABLE catalog.schema.icebergTable (col VARIANT) USING iceberg;

若要向现有表添加 VARIANT 列，请使用 ALTER TABLE 以下命令：

ALTER TABLE catalog.schema.table ADD COLUMN variant_col VARIANT;

使用 GEOMETRY 和 GEOGRAPHY 数据类型

使用 GEOMETRY 和 GEOGRAPHY 数据类型来存储和查询地理空间数据。 参见 GEOMETRY 类型 和 GEOGRAPHY 类型。

Delta Lake

要使用支持 Iceberg 读取以及 GEOMETRY 或 GEOGRAPHY 列的 Delta Lake 创建新的托管表：

CREATE TABLE catalog.schema.table (
  geom_col GEOMETRY(3857),
  geog_col GEOGRAPHY(4326)
) TBLPROPERTIES(
  'delta.enableIcebergCompatV3' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg'
);

Iceberg

要使用 Iceberg v3 创建包含 GEOMETRY 或 GEOGRAPHY 列的新托管表：

CREATE TABLE catalog.schema.table (
  geom_col GEOMETRY(3857),
  geog_col GEOGRAPHY(4326)
) USING iceberg;

要向现有表中添加 GEOMETRY 或 GEOGRAPHY 列，请使用 ALTER TABLE 命令：

ALTER TABLE catalog.schema.table ADD COLUMN geom_col GEOMETRY(3857);
ALTER TABLE catalog.schema.table ADD COLUMN geog_col GEOGRAPHY(4326);

创建具有写入默认值的表

Iceberg v3 定义了两种默认值：

• 写入默认值会在写入操作省略相应列时应用于新行。 Azure Databricks 支持写入默认值。
• 初始默认值适用于添加新列时已有的行。 Azure Databricks不支持初始默认设置。

Delta Lake

要使用 Delta Lake 创建新的托管表，并启用 Iceberg 读取和默认写入：

CREATE TABLE catalog.schema.table (
  id INT,
  row_status STRING DEFAULT 'active'
) TBLPROPERTIES(
  'delta.enableIcebergCompatV3' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg'
);

Iceberg

要用 Iceberg v3 创建带有写默认值的新托管表：

CREATE TABLE catalog.schema.table (
  id INT,
  row_status STRING DEFAULT 'active'
) USING iceberg;

要查看默认值的应用效果，请插入一行且不包含 row_status：

INSERT INTO catalog.schema.table (id) VALUES (1);
SELECT * FROM catalog.schema.table;

前一查询返回如下内容，默认映射为 row_status：

id  row_status
1   active

将表降级到以前的 Apache Iceberg 版本

如果需要在将表升级到 Iceberg v3 之前将表还原到某个状态，可以使用该 RESTORE 命令。

set spark.databricks.delta.restore.protocolDowngradeAllowed = true;
RESTORE TABLE catalog.schema.table TO VERSION AS OF 1;
set spark.databricks.delta.restore.protocolDowngradeAllowed = false;

局限性

Azure Databricks 支持 Iceberg 规范的版本 3，但有以下例外：

• 不支持初始默认值。 当添加新列时，初始默认值会为已有的行设置值。
• 不支持以下数据类型：
  • 未知类型
  • 纳秒精度时间戳。
• 不支持多参数转换。