StarRocks 分区信息检查函数 inspect_table_partition_info 使用指南返回 JSON 格式的分区元数据【免费下载链接】starrocksThe worlds 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/starrocksinspect_table_partition_info是 StarRocks 提供的一个元数据Meta函数可以一次性返回指定表的全部分区信息并以 JSON 字符串呈现包含分区 ID、可见版本、最近刷新时间、最近文件修改时间与文件数等关键字段。本文结合 官方文档 与 FE 端源码实现详细介绍该函数的语法、返回结构、底层原理、典型使用场景与注意事项帮助你快速掌握并把它用于分区监控、物化视图刷新诊断与数据新鲜度排查等实战场景。函数概述inspect_table_partition_info是一个元数据检查函数用来获取一张表的分区信息。它属于 FEFrontend侧的元数据函数族与该家族中的inspect_mv_meta、inspect_related_mv等函数一样主要用于排查表结构、物化视图与分区相关的元数据问题而不是计算业务数据。在 StarRocks 中函数的元数据声明位于 FE 优化器的 MetaFunctions.java其定义如下ConstantFunction(name inspect_table_partition_info, argTypes {VARCHAR}, returnType VARCHAR, isMetaFunction true) public static ConstantOperator inspectTablePartitionInfo(ConstantOperator input)从这个声明可以确认三个关键事实参数类型为VARCHAR表名字符串返回类型为VARCHARJSON 字符串它是常量函数ConstantFunction即入参必须是常量表达式不能是列引用它被标记为isMetaFunction true说明其设计目的就是读取系统元数据供诊断与运维使用。语法与参数inspect_table_partition_info(table_name)参数类型说明table_nameVARCHAR目标表的名称。可以是db.table形式也可以仅写表名支持内表OLAP 表以及外部表如 Hive、Iceberg、Paimon 等连接器表参数解析规则从源码看该函数首先把入参字符串解析为TableName随后解析出库与表对象TableName.fromString(input.getVarchar())负责把db.table格式的字符串拆分为库名与表名MetaFunctions.javainspectTable(tableName)通过GlobalStateMgr的本地元数据服务LocalMetastore查找数据库与表若库或表不存在会分别抛出ERR_BAD_DB_ERROR或ERR_BAD_TABLE_ERROR语义异常MetaFunctions.java若解析出的对象为空或不是表则抛出ERR_INVALID_PARAMETER异常提示xxx is not a tableMetaFunctions.java。因此传入不存在的库、不存在的表、或空值都会直接报错而不是返回空 JSON。返回值返回一个VARCHAR字符串内容是以表名为键、以各分区元数据为值的 JSON 对象。返回 JSON 结构详解示例输出文档给出的典型输出如下执行select inspect_table_partition_info(ss);{ss:{id:28672,version:4,lastRefreshTime:1751439875145,lastFileModifiedTime:-1,fileNumber:-1}}从源码实现看输出的 JSON 结构是{ 表名: { ... } }即表名下挂载一个对象但需要特别说明的是当表有多个分区时getTablePartitionInfo实际会为每个分区分别生成一个条目键为分区名文档示例中的ss是一个无分区或单分区表的场景。真正多分区表的输出形如{p1:{id:28672,version:4,lastRefreshTime:-1,lastFileModifiedTime:-1,fileNumber:-1},p2:{id:28673,version:2,lastRefreshTime:-1,lastFileModifiedTime:-1,fileNumber:-1}}字段语义每个分区条目的字段与MaterializedView.BasePartitionInfo类的序列化字段一一对应定义于 MaterializedView.javaJSON 字段类型含义idlong分区 ID外部表场景下固定为 -1versionlong分区的可见版本visible version。OLAP 表来自物理分区的getVisibleVersion()外部表来自连接器提供的版本号lastRefreshTimelong分区最近一次刷新时间毫秒时间戳。OLAP 表场景下为 -1外部表场景下为该连接器的时间戳lastFileModifiedTimelong分区数据路径下最近一次文件修改时间OLAP 表默认 -1fileNumberlong分区数据路径下的文件数量OLAP 表默认 -1需要注意lastFileModifiedTime与fileNumber主要服务于外部表Hive/Iceberg/Paimon 等的数据新鲜度检测对 OLAP 内表通常保持 -1。BasePartitionInfo的默认构造会显式把这两个字段初始化为 -1MaterializedView.java。底层实现不同表类型的差异化处理inspect_table_partition_info的核心逻辑位于MetaFunctions.getTablePartitionInfo方法MetaFunctions.java它根据表类型走两条完全不同的路径1. OLAP 内表OlapTable分支遍历olapTable.getPartitions()对每个分区用partition.getDefaultPhysicalPartition()取可见版本与可见版本时间构造BasePartitionInfo(partition.getId(), visibleVersion, visibleVersionTime)后序列化为 JSONMetaFunctions.java。2. 外部表分支通过ConnectorPartitionTraits.build(table).getPartitionNameWithPartitionInfo()获取分区名到PartitionInfo的映射再用BasePartitionInfo.fromExternalTable(...)转换MetaFunctions.java。其中外部表分区的id被固定置为 -1version取自连接器的info.getVersion()lastRefreshTime取info.getModifiedTime()并保留连接器原始时间单位Hive 为秒、Iceberg 为微秒、OLAP/JDBC/Paimon 为毫秒不在转换层做有损换算MaterializedView.java若某个分区取不到PartitionInfo则对应条目输出null。此外函数在执行时会对目标表加读锁lockTableWithIntensiveDbLock(..., LockType.READ)并在 finally 中释放保证读取到的分区元数据一致MetaFunctions.java。使用示例示例 1查看 OLAP 表的全部分区mysql select inspect_table_partition_info(ss); ----------------------------------------------------------------------------------------------------------- | inspect_table_partition_info(ss) | ----------------------------------------------------------------------------------------------------------- | {ss:{id:28672,version:4,lastRefreshTime:1751439875145,lastFileModifiedTime:-1,fileNumber:-1}} | ----------------------------------------------------------------------------------------------------------- 1 row in set (0.00 sec)示例 2跨库查看表的分区信息mysql select inspect_table_partition_info(tpch.lineitem); ------------------------------------------------------------------------------------------------------ | inspect_table_partition_info(tpch.lineitem) | ------------------------------------------------------------------------------------------------------ | {p19940101:{id:16970,version:12,lastRefreshTime:-1,lastFileModifiedTime:-1,fileNumber:-1}}| ------------------------------------------------------------------------------------------------------ 1 row in set (0.00 sec)示例 3结合 json 函数解析返回结果由于返回的是标准 JSON可以配合 StarRocks 的 JSON 函数做进一步解析与过滤-- 查看某个分区的可见版本 mysql select inspect_table_partition_info(ss) - $.ss.version as visible_version; ----------------- | visible_version | ----------------- | 4 | -----------------应用场景1. 排查物化视图与分区的刷新/新鲜度问题该函数返回的version、lastRefreshTime、lastFileModifiedTime、fileNumber等字段与异步物化视图刷新框架的BasePartitionInfo是同一套数据结构——异步物化视图的刷新上下文baseTableVisibleVersionMap正是用BasePartitionInfo记录基表各分区可见版本以判断哪些分区需要增量刷新参见 MaterializedView.java 中getBaseTableVisibleVersionMap的相关代码。因此当物化视图刷新结果与预期不符时可以先用本函数对比基表分区的version与物化视图记录的版本快速定位哪个分区没刷到。2. 监控外部表数据文件变化对于 Hive/Iceberg/Paimon 等外部表lastFileModifiedTime与fileNumber反映数据目录下文件的最新修改时间与文件数量配合定时任务采集即可量化感知外部数据的新鲜度与文件规模变化。3. 运维巡检脚本可以把该函数作为运维 SQL 的基础构件例如-- 找出所有分区 version 小于 3 的表示意写法 mysql select inspect_table_partition_info(orders);再在应用层解析 JSON做阈值告警如lastFileModifiedTime距今超过 N 小时。使用限制与注意事项参数必须为常量该函数是ConstantFunction参数必须是字符串字面量或常量表达式不能直接传入列名因此它无法直接对多张表做集合式扫描严格的入参校验库不存在、表不存在、传入空值都会抛出SemanticException调用前应确认表名拼写与所属库名权限约束该函数在 FE 元数据层执行与同族的元数据检查函数一样建议仅授予有元数据查看权限的运维/管理账号使用外部表字段语义id-1与时间戳单位差异是外部表场景的正常表现不要与 OLAP 表的字段语义混淆结果为元数据快照输出反映调用时刻的分区元数据状态读锁保护下的一致性快照并非实时文件系统扫描结果。测试验证仓库中的单元测试 MetaFunctionsTest.java 覆盖了该函数的主要行为inspectTablePartitionInfoReturnsValidJsonForOlapTable对包含p1、p2两个 range 分区的 OLAP 表调用函数断言返回 JSON 中同时包含p1与p2MetaFunctionsTest.javainspectTablePartitionInfoHandlesEmptyPartitions验证无分区的表也能返回包含表名的合法 JSON不会抛出异常MetaFunctionsTest.java多组异常用例分别验证了非法表名、不存在的表、空入参会抛出SemanticExceptionMetaFunctionsTest.java。这些测试直接印证了文档所述返回 JSON 格式分区信息的行为边界可作为阅读源码与理解函数语义的入口。小结inspect_table_partition_info用一条 SQL 就能拿到表的全部分区元数据 JSON是排查分区状态、物化视图刷新差异与外部表数据新鲜度的轻量工具。理解其返回字段id、version、lastRefreshTime、lastFileModifiedTime、fileNumber与内表/外部表两条实现路径能让你更准确地解读输出并将其灵活嵌入日常巡检与诊断流程。【免费下载链接】starrocksThe worlds 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考