表属性和表选项

项目
12/18/2023

适用于： check marked yes Databricks SQL Databricks Runtime

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

表属性

表属性是在执行 CREATE TABLE 或 CREATE VIEW 时可以初始化的键值对。可以使用 ALTER TABLE 或 ALTER VIEW，对现有的表属性运行 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

属性的值。该值必须是 BOOLEAN、STRING、INTEGER 或 DECIMAL 文本。

示例

-- 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

属性的新值。该值必须是 BOOLEAN、STRING、INTEGER 或 DECIMAL 文本。

示例

-- 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 SQL 在任意属性键不存在时不要引发错误。
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

属性的值。该值必须是 BOOLEAN、STRING、INTEGER 或 DECIMAL 文本。

在 Databricks SQL 和 Databricks Runtime 13.3 及更高版本中，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 = 'blue' || 'green');
> SHOW TBLPROPERTIES T;
option.this.is.my.key bluegreen
option.serialization.format     2

保留的表属性键

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

external

使用 CREATE EXTERNAL TABLE 创建外部表。
location

使用 ALTER TABLE 和 CREATE TABLE 的 LOCATION 子句设置表位置。
owner

使用 ALTER TABLE 和 ALTER VIEW 的 [SET] OWNER TO 子句来转移表或视图的所有权。在 Databricks SQL 中，允许将 SET 作为可选关键字。
provider

使用 CREATE TABLE 的 USING 子句设置表的数据源

不应使用以 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'），以控制要为“按时间顺序查看”查询保留多久的历史记录。