Hive 元数据缓存--ByteHouse云数仓版-火山引擎

文档中心

导航

Hive 元数据缓存

最近更新时间：2025.10.23 15:45:18首次发布时间：2025.10.23 15:45:18

为了加速对 Hive 外表的访问，ByteHouse 构建了 Hive 元数据缓存能力，将元数据信息缓存在 Server 内存中，实现减少 Hive Metastore 的访问开销，在业务频繁访问相同表或分区时，大幅提升查询性能。本文介绍了 Hive 源数据缓存功能及使用方法。

功能概述

Hive 元数据缓存流程

ByteHouse 支持将 Hive 外表元数据按照表结构、分区名、分区信息、远程文件等 4 个级别分别缓存至专属 Server 的内存中。

Hive 元数据缓存级别

Hive 元数据缓存包括 4 个级别，分别为 Schema Cache（表结构缓存）、Partition Name Cache（分区名缓存）、Partition Cache（分区信息缓存）、Remote File Cache（远程文件缓存），详细介绍如下：

缓存级别	缓存 Key	缓存 Value	缓存内容
Schema Cache （表结构缓存）	Hive 数据库、表名称，如 `db.table_name`。	`StorageInMemoryMetadata`	存储缓存表结构，列名，列类型，partition key。
Partition Name Cache （分区名缓存）	Hive 表名称。	分区名字符串集合（`List<String>`）	存储当前表的所有分区名，如 `dt=2025-05-20/region=us`。
Partition Cache （分区信息缓存）	Hive 分区名称。如 `db.table/dt=2025-05-20/region=us`。	`DataLakeCache::Partition`	存储表所包含的分区的物理路径信息和其他元属性。
Remote File Cache （远程文件缓存）	分区存储远端路径，包含 Hive 表名称+分区名称。	`List<DataLakeCache::RemoteFile>`	存储该分区下的所有文件名、文件大小、修改时间等信息，避免每次扫描都从远程存储（如 HDFS、S3）拉取目录内容。

缓存策略

元数据缓存策略采用 “LRU Cache（最近最少使用缓存，）+ TTL（存活时间）” 的组合方案，具体逻辑如下：

为每条元数据记录的缓存 Key 绑定独立 TTL 时间。在 TTL 有效期内，系统不会重复向远端发起数据获取请求，直接从本地缓存读取数据，以提升访问效率；
当缓存 Key 的 TTL 时间到期后，系统将自动删除该 Key 对应的缓存内容，随后重新向 Hive metastore（元数据存储）发起请求获取最新数据，并同步更新该 Key 的 TTL 时间，确保缓存数据的时效性。

不同缓存级别的 TTL 时间如下：

缓存级别	TTL 时间
Schema Cache（表结构缓存）	900 秒
Partition Name Cache（分区名缓存）	900 秒
Partition Cache（分区信息缓存）	21600 秒
Remote File Cache（远程文件缓存）	21600 秒

前提条件

Hive 元数据缓存功能依赖专属 Server，使用前需要购买专属 Server。开启 Hive 元数据缓存将会占用专属 server 的内存。专属 Server 的介绍和开通说明请参见专属 Server。

使用元数据缓存

ByteHouse 支持通过配置用户 SQL 级别参数启用 Hive 元数据缓存。启用后，您可通过租户 bh_system.query_log 系统表监控 Hive 元数据缓存的使用情况。需要注意的是，每次查询时均需要添加相关参数，否则 ByteHouse 将不会启用 Hive 元数据缓存。

启用元数据缓存

您可以在每次执行 SQL 语句时，通过添加用户 SQL 级别的 settings 参数，在 Query 级别控制 Hive 元数据缓存的启用状态以及各级缓存的过期时间。当前不支持在建表时启用。
ByteHouse 支持两种方式启用该功能：通过 SQL 参数组进行配置，或在查询语句中直接添加 settings 参数。

通过 SQL 参数组启用

在 ByteHouse 云数仓版控制台执行 SQL 语句时，您可以将 Hive 元数据相关参数添加为 SQL 参数组，在执行 SQL 语句前选中该参数组，ByteHouse 将在执行 SQL 语句时默认添加该参数组，设置方式请参考使用 SQL 参数组。当前支持设置的参数请参见参数说明。设置示例如下：

<sql_parameters>
       <enable_hive_schema_cache>false</enable_hive_schema_cache>
       <hive_schema_cache_ttl>1000</hive_schema_cache_ttl>
</sql_parameters>

通过 settings 参数启用

您可以在每次执行 SQL 语句时添加 settings 参数，启用 Hive 元数据缓存。当前支持设置的参数请参见参数说明。示例如下：

-- 查询时启用
SELECT * FROM ext.las 
SETTINGS 
    enable_hive_schema_cache = 'true', -- 启用 Hive 表结构缓存
    hive_schema_cache_ttl = '1000'; -- 设置 Hive 表结构缓存的过期时间为 1000 秒

说明

创建和使用 Hive 外表的操作说明请参见Hive 外表。

参数说明

参数项	参数说明
`enable_hive_schema_cache`	是否使用表结构缓存，支持设置为 false 或 true，您也可设置为 0（对应 false）或 1（对应 true），系统将对应转换。默认值为 true，数据类型为 Bool。
`hive_schema_cache_ttl`	设置表结构缓存的存活时间，单位为秒。默认值为 900，数据类型为 UInt64。
`enable_hive_partition_name_cache`	是否使用分区名缓存，支持设置为 false 或 true，您也可设置为 0（对应 false）或 1（对应 true），系统将对应转换。默认值为 true，数据类型为 Bool。
`hive_partition_name_cache_ttl`	设置分区名缓存的存活时间，单位为秒。默认值为 900，数据类型为 UInt64。
`enable_hive_partition_cache`	是否使用 Hive 分区元信息缓存，支持设置为 false 或 true，您也可设置为 0（对应 false）或 1（对应 true），系统将对应转换。默认值为 true，数据类型为 Bool。
`hive_partition_cache_ttl`	设置 Hive 分区缓存的存活时间，单位为秒。默认值为 21600，数据类型为 UInt64。
`enable_hive_remote_file_cache`	是否使用远程文件缓存，支持设置为 false 或 true，您也可设置为 0（对应 false）或 1（对应 true），系统将对应转换。默认值为 true，数据类型为 Bool。
`hive_remote_file_cache_ttl`	设置远程文件缓存的存活时间，单位为秒。默认值为 21600，数据类型为 UInt64。

监控缓存指标

您可通过查询租户的 bh_system.query_log 系统表，查看缓存指标，包括 SQL 是否命中 Hive 元数据缓存及过期缓存的发现次数。

注意

bh_system.query_log 系统表为非公开功能，需要开白使用，使用前，请提交工单或联系 ByteHouse 团队获取白名单权限，功能使用详情请参考详细日志（query_log）。

您可通过 bh_system.query_log 系统表，根据事件源 ProfileEvents 中的具体 Key，查询并获取对应缓存指标的数值。缓存指标与事件源的 Key 对应关系说明如下：

缓存指标	事件源（`query_log.ProfileEvents`）中的 Key
缓存命中次数	指标以 `DataLake{Schema\|PartitionName\|Partition\|RemoteFiles}CacheHits` 形式呈现，含义说明如下： `DataLakeSchemaCacheHits`：表结构缓存的命中次数 `DataLakePartitionNameCacheHits`：分区名缓存的命中次数 `DataLakePartitionCacheHits`：分区缓存的命中次数 `DataLakeRemoteFilesCacheHits`：远程文件缓存的命中次数
缓存 Miss 次数	指标以 `DataLake{Schema\|PartitionName\|Partition\|RemoteFiles}CacheMisses` 形式呈现，含义说明如下： `DataLakeSchemaCacheMisses`：表结构缓存的未命中次数 `DataLakePartitionNameCacheMisses`：分区名缓存的未命中次数 `DataLakePartitionCacheMisses`：分区缓存的未命中次数 `DataLakeRemoteFilesCacheMisses`：远程文件缓存的未命中次数
过期缓存的发现次数（重新从远端获取）	指标以 `DataLake{Schema\|PartitionName\|Partition\|RemoteFiles}CacheExpired` 形式呈现，含义说明如下： `DataLakeSchemaCacheExpired`：表结构缓存的存活时间 `DataLakePartitionNameCacheExpired`：分区名缓存的存活时间 `DataLakePartitionCacheExpired`：分区缓存的存活时间 `DataLakeRemoteFilesCacheExpired`：远程文件缓存的存活时间

缓存指标

事件源（query_log.ProfileEvents）中的 Key

缓存命中次数

指标以 DataLake{Schema|PartitionName|Partition|RemoteFiles}CacheHits 形式呈现，含义说明如下：

DataLakeSchemaCacheHits：表结构缓存的命中次数
DataLakePartitionNameCacheHits：分区名缓存的命中次数
DataLakePartitionCacheHits：分区缓存的命中次数
DataLakeRemoteFilesCacheHits：远程文件缓存的命中次数

缓存 Miss 次数

指标以 DataLake{Schema|PartitionName|Partition|RemoteFiles}CacheMisses 形式呈现，含义说明如下：

DataLakeSchemaCacheMisses：表结构缓存的未命中次数
DataLakePartitionNameCacheMisses：分区名缓存的未命中次数
DataLakePartitionCacheMisses：分区缓存的未命中次数
DataLakeRemoteFilesCacheMisses：远程文件缓存的未命中次数

过期缓存的发现次数（重新从远端获取）

指标以 DataLake{Schema|PartitionName|Partition|RemoteFiles}CacheExpired 形式呈现，含义说明如下：

DataLakeSchemaCacheExpired：表结构缓存的存活时间
DataLakePartitionNameCacheExpired：分区名缓存的存活时间
DataLakePartitionCacheExpired：分区缓存的存活时间
DataLakeRemoteFilesCacheExpired：远程文件缓存的存活时间

查询方式示例如下：

SELECT
    k,
    v
FROM bh_system.query_log
ARRAY JOIN
    mapKeys(ProfileEvents) AS k,
    mapValues(ProfileEvents) AS v
WHERE (query_id = '4e9xxxxx-xxxx-xxxx-xxxx-0bxxxxxxxxxx') AND (k LIKE '%DataLake%')

参数说明

参数项	参数说明
`k`	设置为 k，表示查询当前已启用的缓存事件的指标名称。
`v`	设置为 v，表示查询指标的统计值，即各类缓存事件的发生次数。
`ARRAY JOIN...AS...`	将提取出的键和值一一对应，形成多行数据，这里用于解析 `ProfileEvents` 字段中的键值对数据，并将其展开为多行记录。 `mapKeys(ProfileEvents) AS k`：解析`ProfileEvents`字段中存储的所有缓存指标名称。 `mapValues(ProfileEvents) AS v`：解析`ProfileEvents`字段中各指标对应的统计数值。
`WHERE...AND...`	使用 WHERE 对数据进行筛选，只保留符合条件的记录。 `AND`：表示两个条件需同时满足。 `query_id`：指定需要查询的目标 SQL 语句 ID。 `k LIKE '%DataLake%'`：筛选条件，表示仅保留所有 Hive 元数据缓存相关的指标。

输出结果示例如下：