Apache Spark SQL 中 SHOW TBLPROPERTIES 语句全面解析：语法、过滤规则与底层实现

Apache Spark SQL 中 SHOW TBLPROPERTIES 语句全面解析语法、过滤规则与底层实现【免费下载链接】sparkApache Spark - A unified analytics engine for large-scale data processing项目地址: https://gitcode.com/gh_mirrors/sp/spark本指南聚焦 Apache Spark SQL 的SHOW TBLPROPERTIES语句详细讲解如何查询表级属性Table Properties的键值对、按指定键查询单个属性值以及哪些属性会被系统过滤不显示。读完本文你将掌握该语句的完整语法、参数形式、输出结构并能结合源码理解其属性脱敏、保留属性排除、结果排序等底层行为可直接用于日常表元数据排查与数据治理。语句概述SHOW TBLPROPERTIES用于返回一张已存在表的表属性。给定一个可选的属性键时它返回该键对应的属性值若不指定键则返回该表的全部属性键值对。它是 Spark SQL 元数据查询家族SHOW TABLES、SHOW TABLE EXTENDED、DESCRIBE TABLE中专门用于查看TBLPROPERTIES的语句。从官方文档 SHOW TBLPROPERTIES 的定义看属性一般是在建表时通过CREATE TABLE ... TBLPROPERTIES (...)指定的也可以在后续通过ALTER TABLE ... SET TBLPROPERTIES (...)修改。语法SHOW TBLPROPERTIES table_identifier [ ( unquoted_property_key | property_key_as_string_literal ) ]在语法上table_identifier是必选项括号内的属性键是可选项。两种键的写法二选一不加引号的标识符键可包含点号分隔的多个部分或字符串字面量键。该语句在仓库中的 ANTLR 语法规则定义位于 SqlBaseParser.g4| SHOW TBLPROPERTIES tableidentifierReference (LEFT_PAREN keypropertyKeyOrStringLit RIGHT_PAREN)? #showTblProperties从该规则可以确认两点表名使用identifierReference解析因此支持database.table形式的多段限定名也支持 SQL 参数标记parameter marker等特性属性键是可选的(...)?且通过propertyKeyOrStringLit规则统一解析它既接受点分标识符也接受字符串字面量。参数详解table_identifier指定一张已存在表的表名可以用数据库名做限定。语法[ database_name. ] table_name如果不加数据库限定则在当前所在的数据库中解析该表如果表不存在Spark 会抛出AnalysisException测试SHOW TBLPROPERTIES WITH TABLE NOT EXIST验证了这一行为见 ShowTblPropertiesSuiteBase.scala。unquoted_property_key以不加引号的形式指定属性键键可以由点号分隔的多个部分组成。语法[ key_part1 ] [ .key_part2 ] [ ... ]例如created.by.user就是一个由三段组成的未加引号属性键。在 AstBuilder.scala 中visitPropertyKeyOrStringLit会将该形式解析为点分标识符键。property_key_as_string_literal以字符串字面量的形式指定属性键值例如created.date。字符串字面量形式支持字符串拼接coalescing以及参数标记parameter marker灵活性更强。返回结果与输出结构当不指定属性键时返回两列列名类型可空性keySTRING非空valueSTRING非空该输出结构定义在逻辑计划 v2Commands.scala 中object ShowTableProperties { def getOutputAttrs: Seq[Attribute] Seq( AttributeReference(key, StringType, nullable false)(), AttributeReference(value, StringType, nullable false)()) }测试套件 ShowTblPropertiesSuiteBase.scala 也对该 schema 做了断言assert(properties.schema schema)当指定属性键时默认只返回一列value旧版行为详见下文输出结构兼容性。属性过滤规则哪些属性不会显示文档明确指出SHOW TBLPROPERTIES返回的属性会排除一部分 Spark 与 Hive 内部使用的属性所有以spark.sql前缀开头的属性诸如EXTERNAL、comment这样的属性键Hive 内部生成、用于存储统计信息的属性例如numFiles、numPartitions、numRows。这些统计类属性的变化会随数据写入而更新不属于用户自定义属性因此默认不展示。从源码实现看物理执行计划 ShowTablePropertiesExec.scala 中执行了保留属性过滤// The reserved properties are accessible through DESCRIBE val properties conf.redactOptions(catalogTable.properties.asScala.toMap) .filter { case (k, _) !CatalogV2Util.TABLE_RESERVED_PROPERTIES.contains(k) }CatalogV2Util.TABLE_RESERVED_PROPERTIES定义于 CatalogV2Util.scalaval TABLE_RESERVED_PROPERTIES Seq(TableCatalog.PROP_COMMENT, // comment TableCatalog.PROP_COLLATION, // collation TableCatalog.PROP_LOCATION, // location TableCatalog.PROP_PROVIDER, // provider TableCatalog.PROP_OWNER, // owner TableCatalog.PROP_EXTERNAL, // external TableCatalog.PROP_IS_MANAGED_LOCATION, // is_managed_location TableCatalog.PROP_TABLE_TYPE) // table_type这些常量在 TableCatalog.java 中定义。代码注释表明这些保留属性属于表的固有元数据需要通过DESCRIBE TABLE等专用语句查看因此从SHOW TBLPROPERTIES的结果中剔除。属性脱敏与结果排序除了过滤保留属性ShowTablePropertiesExec还调用了conf.redactOptions对属性值做脱敏处理。这意味着敏感属性值如密码类键值在输出时会被替换为*********(redacted)。测试套件中的SHOW TBLPROPERTIES BASIC用例验证了这一点见 ShowTblPropertiesSuiteBase.scalaval expected Seq( Row(password, *********(redacted)), Row(status, status), Row(user, user))此外当查询全部属性不指定键时结果按键名排序输出见 ShowTablePropertiesExec.scalacase None properties.toSeq.sortBy(_._1).map(kv toCatalystRow(kv._1, kv._2))完整示例以下示例均来自官方文档 sql-ref-syntax-aux-show-tblproperties.md可直接在spark-sql或spark.sql()中运行。第一步在salesdb数据库中建表并指定两个自定义属性USE salesdb; CREATE TABLE customer(cust_code INT, name VARCHAR(100), cust_addr STRING) TBLPROPERTIES (created.by.user John, created.date 01-01-2001);第二步查看该表的全部用户指定属性SHOW TBLPROPERTIES customer; ------------------------------- | key| value| ------------------------------- | created.by.user| John| | created.date|01-01-2001| |transient_lastDdlTime|1567554931| -------------------------------可以看到除了两个自定义属性外还返回了transient_lastDdlTime。这是 Hive 元数据中记录最后一次 DDL 操作时间戳的属性属于 Hive 生成的元数据之一。测试代码在断言时通常显式过滤掉它见 ShowTblPropertiesSuiteBase.scalaval properties sql(sSHOW TBLPROPERTIES $tbl) .filter(key ! transient_lastDdlTime) .filter(key ! option.serialization.format)第三步查看带数据库限定的表SHOW TBLPROPERTIES salesdb.customer; ------------------------------- | key| value| ------------------------------- | created.by.user| John| | created.date|01-01-2001| |transient_lastDdlTime|1567554931| -------------------------------结果与不带限定名时一致。第四步按未加引号的属性键查询单个值SHOW TBLPROPERTIES customer (created.by.user); ----- |value| ----- | John| -----第五步按字符串字面量键查询单个值SHOW TBLPROPERTIES customer (created.date); ---------- | value| ---------- |01-01-2001| ----------指定键时只返回value一列这正是当前默认的输出结构。键不存在时的行为当指定的属性键在该表中不存在时Spark 不会报错而是返回一行value其内容为错误提示文本。该行为在 ShowTablePropertiesExec.scala 中实现propertyKey match { case Some(p) val propValue properties .getOrElse(p, sTable $tableName does not have property: $p) ...对应测试SHOW TBLPROPERTIES(KEY) KEY NOT FOUND见 ShowTblPropertiesSuiteBase.scala验证结果仍返回一行value列包含does not have property: nonExistingKey字样。因此在使用时建议先通过SHOW TBLPROPERTIES table查看全部键或对返回的 value 做存在性判断。输出结构兼容性legacy schema指定属性键时输出的列数受配置项spark.sql.legacy.keepCommandOutputSchema控制默认false返回单列value开启true保留旧版输出结构当指定键时仍返回key、value两列。该兼容逻辑在分析规则 KeepLegacyOutputs.scala 中实现case s: ShowTableProperties if s.propertyKey.isDefined s.copy(output Seq(s.output.last))测试KEEP THE LEGACY OUTPUT SCHEMA见 ShowTblPropertiesSuiteBase.scala对两种配置下的列名与结果分别做了断言。执行层ShowTablePropertiesExec也正是根据output.length来决定返回一行还是两行见 ShowTablePropertiesExec.scala。底层执行链路SHOW TBLPROPERTIES的完整执行链路可以概括为解析ANTLR 语法规则 SqlBaseParser.g4 匹配语句产出showTblProperties语法树节点AST 构建AstBuilder.scala 的visitShowTblProperties将其转换为逻辑计划ShowTableProperties(table, propertyKey)表名通过createUnresolvedTableOrView解析属性键通过visitPropertyKeyOrStringLit解析支持点分标识符、字符串字面量、参数标记分析ShowTableProperties是UnaryCommand其输出 schema 固定为key、value两列v2Commands.scala若开启spark.sql.legacy.keepCommandOutputSchemaKeepLegacyOutputs.scala 会改写输出列物理执行ShowTablePropertiesExecShowTablePropertiesExec.scala从 catalog 的Table.properties读取属性依次执行脱敏conf.redactOptions、保留属性过滤CatalogV2Util.TABLE_RESERVED_PROPERTIES、按键排序未指定键时或键查找指定键时最终以InternalRow形式返回。跨目录测试覆盖该命令在仓库中覆盖了 V1 与 V2 两套表目录体系的测试统一基础测试ShowTblPropertiesSuiteBase.scalaV1 In-Memory Catalogv1/ShowTblPropertiesSuite.scalaV1 Hive 外部目录hive 模块的 ShowTblPropertiesSuite.scalaV2 表目录v2/ShowTblPropertiesSuite.scala。这些测试用例覆盖了基础查询、按键查询、表不存在、键不存在以及输出 schema 兼容等主要场景可作为理解该语句行为边界的参考。相关语句CREATE TABLE通过TBLPROPERTIES子句在建表时定义表属性ALTER TABLE SET TBLPROPERTIES在建表后修改或新增表属性SHOW TABLES列出数据库中的表SHOW TABLE EXTENDED展示表的信息与扩展信息包含部分属性细节。【免费下载链接】sparkApache Spark - A unified analytics engine for large-scale data processing项目地址: https://gitcode.com/gh_mirrors/sp/spark创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考