表属性和表选项

  • 项目

为表和视图定义用户定义的标记。

  • 表属性

    表属性是在执行 CREATE TABLE 或 CREATE VIEW 时可以初始化的键值对。 可以使用 ALTER TABLE 或 ALTER TABLE，对现有的表属性运行 UNSET，或对新的或现有的表属性运行 SET。

    可以使用表属性来标记包含不受 SQL 跟踪的信息的表。

  • 表选项

    表选项的用途是将存储属性传递到基础存储，例如将 SERDE 属性传递到 Hive。

    表选项是在执行 CREATE TABLE 时可以初始化的键值对。 不能对表选项运行 SET 或 UNSET。

TBLPROPERTIES

在新的表或视图中设置一个或多个表属性。

可以使用表属性来标记包含不受 SQL 跟踪的信息的表。

语法

TBLPROPERTIES ( property_key [ = ] property_val [, ...] )

property_key
  { identifier [. ...] | string_literal }

参数

  • property_key

    属性键。 该键可以由一个或多个以点分隔的标识符或一个字符串字面量组成。

    属性键必须唯一，且区分大小写。

  • property_val

    属性的值。 该值必须是布尔值、字符串、整数或十进制文本。

示例

-- Create table with user defined table properties
> CREATE TABLE T(c1 INT) TBLPROPERTIES('this.is.my.key' = 12, this.is.my.key2 = true);
> SHOW TBLPROPERTIES T;
option.serialization.format     1
this.is.my.key  12
this.is.my.key2 true
transient_lastDdlTime   1649783569

SET TBLPROPERTIES

在现有的表或视图中设置一个或多个表属性。

语法

SET TBLPROPERTIES ( property_key [ = ] property_val [, ...] )

property_key
  { identifier [. ...] | string_literal }

参数

  • property_key

    属性键。 该键可以由一个或多个以点分隔的标识符或一个字符串字面量组成。

    属性键必须唯一，且区分大小写。

  • property_val

    属性的新值。 该值必须是布尔值、字符串、整数或十进制文本。

示例

-- Alter the a table's table properties.
>  ALTER TABLE T SET TBLPROPERTIES(this.is.my.key = 14, 'this.is.my.key2' = false);
> SHOW TBLPROPERTIES T;
option.serialization.format     1
this.is.my.key  14
this.is.my.key2 false
transient_lastDdlTime   1649783980

UNSET TBLPROPERTIES

从表或视图中删除一个或多个表属性。

语法

UNSET TBLPROPERTIES [ IF EXISTS ] ( property_key [, ...] )

property_key
  { identifier [. ...] | string_literal }

参数

  • IF EXISTS

    一个可选的子句，指示 Databricks Runtime 在任意属性键不存在时不要引发错误。

  • property_key

    要删除的属性键。 该键可以由一个或多个以点分隔的标识符或一个字符串字面量组成。

    属性键区分大小写。 如果 property_key 不存在，则引发错误，除非已指定 IF EXISTS。

示例

-- Remove a table's table properties.
>  ALTER TABLE T UNSET TBLPROPERTIES(this.is.my.key, 'this.is.my.key2');
> SHOW TBLPROPERTIES T;
option.serialization.format     1
transient_lastDdlTime   1649784415

OPTIONS

在新表中设置一个或多个表选项。

表选项的用途是将存储属性传递到基础存储，例如将 SERDE 属性传递到 Hive。

为 Delta Lake 表指定表选项也会将这些选项回显为表属性。

语法

OPTIONS ( property_key [ = ] property_val [, ...] )

property_key
  { identifier [. ...] | string_literal }

参数

  • property_key

    属性键。 该键可以由一个或多个以点分隔的标识符或一个字符串字面量组成。

    属性键必须唯一，且区分大小写。

  • property_val

    属性的值。 该值必须是布尔值、字符串、整数或十进制文本。

示例

-- Create table with user defined table option
-- The options appears with an `option.` prefix.
> CREATE TABLE T(c1 INT) OPTIONS(this.is.my.key = 'green');
> SHOW TBLPROPERTIES T;
option.a.b green
option.serialization.format     2

保留的表属性键

Databricks Runtime 保留某些属性键供自身使用，如果你尝试使用这些键，将引发错误：

不应使用以 option 标识符开头的属性键。 SHOW TBLPROPERTIES 中会筛选掉此前缀标识符。 option 前缀还用于显示表选项。

常用的 TBLPROPERTIES 和 OPTIONS 键

Delta Lake 通常使用以下设置：

  • delta.appendOnly：设置为 true 会禁用 UPDATE 和 DELETE 操作。
  • delta.dataSkippingNumIndexedCols：设置为要收集和考虑其统计信息的前导列数。
  • delta.deletedFileRetentionDuration：设置为某个间隔（例如 'interval 7 days'），以控制何时允许 VACUUM 删除文件。
  • delta.logRetentionDuration：设置为某个间隔（例如 'interval 60 days'），以控制要为“按时间顺序查看”查询保留多久的历史记录。