企业官网建设流程全解析

StarRocks inspect_hive_part_info 函数详解：以 JSON 方式查看 Hive 外表分区元数据

【免费下载链接】starrocksThe world's fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks

inspect_hive_part_info是 StarRocks 提供的一类元数据（Meta）内省函数，用于在 SQL 会话中直接获取指定 Hive 外部表（External Table）的分区信息，并以 JSON 字符串的形式返回。它在排查外表分区元数据不一致、验证分区统计信息、检查数据文件可拆分性等场景中非常实用。读完本文，你将掌握该函数的完整语法、JSON 返回结构的每个字段含义、底层实现调用链，以及在实际查询与排障中的用法。

函数概览

inspect_hive_part_info属于 StarRocks FE 端注册的常量函数（Constant Function），定义在 MetaFunctions.java 中，通过@ConstantFunction注解注册，isMetaFunction = true表明它是一个元数据内省函数。其完整函数签名为：

inspect_hive_part_info(table_name)

参数table_name在源码中通过TableName.fromString(name.getVarchar())解析，因此传入时必须携带 Catalog 名与库名。下面的调用链分析中可以看到，函数内部会依次完成“表解析 → 权限校验 → 分区信息获取 → JSON 序列化”四个步骤。

返回结果：JSON 结构逐字段解析

原文档给出的示例完整展示了该函数的真实输出。以一个 Hive 分区表t1（分区键为k3、k4）为例：

mysql> select inspect_hive_part_info('t1'); +----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | inspect_hive_part_info('t1') | +----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | {"k3=9999-12-03/k4=3":{"parameters":{"totalSize":"625","numRows":"1","starrocks_version":"bc39130-bc39130","numFiles":"1","starrocks_query_id":"0197ca18-dd10-76fd-bb85-253226af8365","transient_lastDdlTime":"1751442316","STATS_GENERATED_VIA_STATS_TASK":"workaround for potential lack of HIVE-12730"},"inputFormat":"PARQUET","textFileFormatDesc":{},"fullPath":"hdfs://emr-header-1.cluster-49091:9000/user/hive/warehouse/hive_db_b4425ea7d8184049a2b1e039c0a8f595.db/t1/k3=9999-12-03/k4=3","isSplittable":true}} | +----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 1 row in set (0.00 sec)

返回的是一个 JSON 对象，键为分区名（形如k3=9999-12-03/k4=3），值为该分区对应的Partition对象序列化结果。分区名的格式与 Hive 的分区目录规范一致，多个分区会并列输出为多个键值对。

从 Partition.java 的toJson()实现可以看出，每个分区的 JSON 值固定包含五个字段：

parameters 字段的常见统计项

parameters中的键值对直接透传自 Hive Metastore 的分区参数（Partition Parameters），实际内容取决于 Hive 侧统计任务的执行情况，常见的包括：

• totalSize：分区数据总大小（字节）；
• numRows：分区预估行数；
• numFiles：分区文件个数；
• transient_lastDdlTime：最近一次 DDL 变更的 Unix 时间戳；
• starrocks_version/starrocks_query_id：当分区由 StarRocks 写入或统计时，StarRocks 附加的版本与查询标识；
• STATS_GENERATED_VIA_STATS_TASK：Hive 统计任务生成标记（示例中的 value 与 Hive 的 HIVE-12730 问题 workaround 相关）。

这些统计项正是 Hive 分区裁剪、CBO 优化器估算行数与扫描代价的重要输入，因此通过该函数可以直观地核对外表分区统计信息是否齐全、是否过期。

底层实现：函数调用链与权限校验

从 FE 源码看，inspect_hive_part_info的执行路径非常清晰，整个过程不触发数据扫描，只访问元数据，开销极小：

1. 表名解析与元数据获取：inspectHivePartInfo首先用TableName.fromString解析三段式表名，随后调用 MetaFunctions.inspectExternalTable，通过GlobalStateMgr.getCurrentState().getMetadataMgr().getTable(...)从 Metadata Manager 中拿到Table对象；若表不存在，会抛出ERR_BAD_TABLE_ERROR语义异常。
2. 权限校验：inspectExternalTable内部调用Authorizer.checkAnyActionOnTable检查当前用户对目标表的任意操作权限，无权限时上报访问拒绝（Access Denied）异常。即：该函数要求用户对目标表拥有至少一种操作权限。
3. 分区信息获取：通过PartitionUtil.getPartitionNameWithPartitionInfo(table)获取“分区名 → PartitionInfo”的映射，该工具方法定义在 PartitionUtil.java，内部会依据表类型构建对应的ConnectorPartitionTraits实现（Hive 表对应 HivePartitionTraits.java）。这一层抽象意味着该框架同样适用于其他带分区语义的外部数据源。
4. JSON 序列化：遍历映射，仅对类型为Partition的条目调用part.toJson()（if (entry.getValue() instanceof Partition)做了类型过滤），最终把所有分区合并为一个 JSON 对象返回。

由于该函数是常量函数，在查询计划生成阶段即被求值折叠（Constant Folding），因此它也可以嵌入SELECT投影之外的表达式中使用。

使用示例

1. 查看 Hive 分区表的全部分区元数据

-- 使用三段式完整表名：catalog.database.table SELECT inspect_hive_part_info('hive_catalog.my_db.sales_partitioned');

2. 在函数结果上做 JSON 解析，提取关键字段

-- 借助 JSON 函数解析返回结果，提取每个分区的完整路径 SELECT JSON_KEYS(inspect_hive_part_info('hive_catalog.my_db.sales_partitioned')) AS partition_keys; -- 提取指定分区的数据大小 SELECT JSON_QUERY( inspect_hive_part_info('hive_catalog.my_db.sales_partitioned'), '$.`dt=2024-01-01`.parameters.totalSize' ) AS total_size;

注意：分区名作为 JSON 键包含=与/等字符，使用JSON_QUERY路径时需要加反引号包裹键名。

3. 配合 WHERE 条件进行针对性排查

SELECT inspect_hive_part_info('hive_catalog.my_db.sales_partitioned') WHERE JSON_LENGTH(inspect_hive_part_info('hive_catalog.my_db.sales_partitioned')) > 0;

典型使用场景

• 外表分区元数据排障：当查询 Hive 外表结果与预期不符、分区裁剪异常时，用该函数确认 FE 侧元数据缓存中实际识别到的分区列表，快速区分“Metastore 侧缺分区”与“StarRocks 缓存未刷新”两类问题；
• 统计信息核对：通过parameters字段核对numRows、totalSize、numFiles等统计信息，辅助判断优化器估算是否准确、是否需要执行 ANALYZE；
• 文件格式与可拆分性检查：通过inputFormat与isSplittable判断分区数据能否被并行拆分扫描，从而评估查询并发度与性能预期；
• 自动化运维与监控脚本：作为只读的元数据内省手段，可在脚本中周期性采集分区规模、路径分布等指标。

注意事项与限制

1. 必须使用三段式表名：table_name需要是catalog.database.table形式，否则表解析会失败并抛出语义异常（对应错误码ERR_BAD_TABLE_ERROR）；
2. 仅适用于外部表：从函数名与实现看，它面向 Hive 外部表的分区信息，普通内部表应使用分区相关的系统函数（如inspect_table_partition_info，见 meta-functions 目录）；
3. 需要目标表的操作权限：无权限用户调用会收到 Access Denied，这是 FE 侧Authorizer的强制校验；
4. 返回的是元数据快照：结果基于当前 FE 内存中的元数据状态（可能来自缓存），若 Hive 侧刚变更分区，可能需要刷新缓存后才能看到最新结果；
5. 返回结果可能较大：分区数量很多时 JSON 字符串会很长，建议在交互式排查中使用，或配合 JSON 解析函数只提取所需字段。

测试与验证

FE 单元测试 ConstantExpressionTest.java 的testInspectHivePartitionInfo覆盖了两个关键行为：

• 对不存在的表not_exist_catalog.no_db.no_table调用会抛出StarRocksPlannerException（验证表不存在时的报错路径）；
• 对真实 Hive 表hive0.partitioned_db.lineitem_par调用后，执行计划包含Project节点（验证常量折叠后该函数被正常求值并输出）。

这组测试用例可作为你本地验证函数行为、理解其错误语义的参考入口。

小结

inspect_hive_part_info是 StarRocks 元数据内省函数家族（inspect_*，完整列表见 meta-functions 文档目录）中面向 Hive 外表分区的专用工具。它以极低的成本（仅元数据访问、无数据扫描）将 Hive 分区名、统计参数、输入格式、文件路径与可拆分性等关键信息以结构化 JSON 暴露给 SQL 层，既是日常外表查询排障的利器，也是理解 StarRocks 外表分区元数据管理机制的绝佳窗口。

【免费下载链接】starrocksThe world's fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks