查询条件缓存依赖 analyzer 工作,自
26.9 版本起 analyzer 是唯一的查询分析方式,并自 24.3 起成为默认方式。WHERE col = 'xyz') 进行求值,始终会得到相同的结果。
更具体地说,对于每个已求值的过滤器和每个粒度 (即一个块,默认包含 8192 行) ,查询条件缓存都会记录该粒度中是否没有任何行满足该过滤条件。
这些信息会以单个比特的形式记录:0 表示没有任何行匹配该过滤器,1 表示至少有一行匹配。
在前一种情况下,ClickHouse 可以在求值过滤条件时跳过相应的粒度;在后一种情况下,则必须加载该粒度并进行求值。
当以下三个前置条件满足时,查询条件缓存会非常有效:
- 第一,工作负载必须重复求值相同的过滤条件。如果同一个查询被多次重复执行,这种情况会自然出现;如果两个查询使用了相同的过滤器,也会出现这种情况,例如
SELECT product FROM products WHERE quality > 3和SELECT vendor, count() FROM products WHERE quality > 3。 - 第二,大多数数据必须是不可变的,也就是说,在多次查询之间不会发生变化。在 ClickHouse 中,这通常成立,因为 parts 是不可变的,并且只会通过 INSERT 创建。
- 第三,过滤器必须具有较高的选择性,也就是说,只有相对较少的行满足过滤条件。匹配过滤条件的行越少,被记录为 0 比特 (无匹配行) 的粒度就越多,后续求值过滤条件时可被“剪枝”的数据也就越多。
内存消耗
由于查询条件缓存对每个过滤条件和粒度仅存储一个比特,因此占用的内存很少。 查询条件缓存的最大大小可通过服务器设置query_condition_cache_size 配置 (默认值:100 MB) 。
100 MB 的缓存大小对应 100 * 1024 * 1024 * 8 = 838,860,800 个条目。
由于每个条目代表一个标记 (默认情况下为 8192 行) ,因此该缓存最多可覆盖单列的 6,871,947,673,600 (6.8 万亿) 行。
在实际场景中,过滤条件通常会在多个列上求值,因此这个数字需要除以被过滤的列数。
配置项及用法
设置 use_query_condition_cache 用于控制某个特定查询或当前会话中的所有查询是否使用查询条件缓存。 例如,首次执行该查询时use_query_condition_cache = true,将利用查询条件缓存以减少扫描的数据量。
Parquet 文件
查询条件缓存同样适用于通过File、S3、AzureBlobStorage、URL 以及数据湖表引擎读取的 Parquet 文件 (但不适用于通过表函数读取的情况,因为缓存条目归属于表) 。
对于此类文件,缓存记录的是行组而非粒度。
文件的缓存条目与文件版本绑定,因此文件一旦被修改便会重新读取:对象存储以 ETag 标识版本,本地文件和 URL 则以修改时间和大小标识版本。
由于 Web 服务器报告的修改时间 (Last-Modified) 精度仅为一秒,通过 URL 读取的文件只有同时满足以下条件时才会使用缓存:按 Web 服务器的时钟 (即其响应中的 Date) 计算,文件的最后修改时间距今已超过一分钟;且服务器报告了文件的修改时间、大小和日期。
涉及当前时间的条件
像WHERE time >= now() - INTERVAL 10 DAY 这样的条件是非确定性的:now() 折叠后的值每次查询都会变化,因此此类条件无法直接缓存。
为此,ClickHouse 会将当前时间常量舍入到时间网格上,从而由这些条件派生出确定性的条件。例如,time >= '2026-08-09 12:34:56' 会被缓存为 time >= '2026-08-09 00:00:00' (读取缓存时向下取整,写入缓存时向上取整,从而保证已缓存信息的正确性) 。
网格步长与该常量和当前时间之间的距离成正比——回溯十天的条件,步长为一天;回溯九十分钟的条件,步长为一小时——并被限制在一秒到一天的范围内。比例因子可通过设置 query_condition_cache_time_condition_grid_factor 进行配置 (默认值:1.0) 。
如果常量已与网格对齐,例如 WHERE time >= today() - 10 或 WHERE time >= toStartOfDay(now()) - INTERVAL 10 DAY,那么紧接着的下一次查询就能复用缓存,且缓存会一直有效,直到该常量发生变化 (例如直到当天结束) 。
对于未对齐的常量,例如 WHERE time >= now() - INTERVAL 10 DAY,在某个网格单元内写入的缓存条目将供下一个网格单元内的查询使用:昨天的查询会为今天的查询预热缓存。
这种复用仅适用于时间下界。对于上界 (例如 WHERE time < now()) ,无论是单独使用,还是用于两端均以当前时间为边界的滑动窗口 (如 WHERE time >= now() - INTERVAL 10 DAY AND time < now()) ,只有当其常量与网格对齐时才能被复用 (例如 WHERE time < today() 或 WHERE time >= today() - 10 AND time < today()) :若常量未对齐,后一次查询的条件并不包含在前一次查询的条件之内,因此无论网格如何划分,都无法可靠地应用前一次查询的缓存条目。
可以通过设置 use_query_condition_cache_for_time_conditions (默认:已启用) 禁用这种派生,该设置仅在 use_query_condition_cache 同时启用时才会生效。
它适用于 MergeTree 表;从文件和对象存储 (file、s3 等) 读取数据时,查询条件缓存仍然只用于确定性的条件。
使用动态过滤 (use_top_k_dynamic_filtering) 的 ORDER BY ... LIMIT N 形式的查询,会复用条件相同的其他查询所写入的条目。
当动态过滤器被添加到 PREWHERE,或条件保留在 WHERE 中时,此类查询自身不会为涉及当前时间的条件写入条目:它们跳过的行取决于满足条件的前 N 行,而映射到同一网格点的两个条件所对应的前 N 行并不相同。
如果动态过滤器无法添加到 PREWHERE (例如排序列为某些类型时) ,那么带有当前时间条件的 PREWHERE 所跳过的粒度并不依赖于前 N 行,因此会以派生条件记录下来,且这些条目仅会被具有相同 TopK 计划的查询复用 (参见下文) 。
ORDER BY ... LIMIT n (TopK) 查询
使用 TopK 优化的查询 (ORDER BY <column> LIMIT n,通过动态过滤或排序列上的 minmax 跳过索引加速) 也会使用查询条件缓存。
TopK 读取可根据查询执行期间不断变化的阈值跳过粒度,因此其缓存条目会按 TopK 计划参数以及读取的 parts 集合进行分区:只有使用相同计划读取相同 parts 的查询才会复用这些条目。
这同样适用于通过 File 表引擎对 Parquet 文件进行的 TopK 读取:此时,缓存会记录不包含任何结果行的行组,条目则按 TopK 计划参数、过滤条件 (如有) 以及所读取的文件集合及其版本进行分区,因此只要任一文件被修改,就会生成新的条目。
对于以 Parquet 作为数据文件的数据湖表 (例如 Iceberg、DeltaLake、Paimon),其 TopK 读取同样如此:条目按 TopK 计划参数、过滤条件 (如有) 以及表的快照进行分区,因此每生成一个新快照,都会产生新的条目。
与其他读取不同,此类 TopK 读取即使没有过滤条件也会使用缓存,例如 SELECT * FROM hits ORDER BY EventTime LIMIT 10。
可通过设置 use_query_condition_cache_for_top_k (默认:启用) 将此类读取完全排除在缓存之外;仅当同时启用 use_query_condition_cache 时,该设置才会生效。
管理
查询条件缓存不会在 ClickHouse 重启后保留。 要清除查询条件缓存,请运行SYSTEM CLEAR QUERY CONDITION CACHE。
缓存内容显示在系统表 system.query_condition_cache 中。
要以 MB 为单位计算当前查询条件缓存的大小,请运行 SELECT formatReadableSize(sum(entry_size)) FROM system.query_condition_cache。
如果你想查看单个过滤条件,可以检查 system.query_condition_cache 中的 condition 字段。请注意,该字段仅在 debug 构建中可用。
自数据库启动以来,查询条件缓存的命中次数和未命中次数会在系统表 system.events 中显示为事件 “QueryConditionCacheHits” 和 “QueryConditionCacheMisses”。
只有在设置 use_query_condition_cache = true 时运行的 SELECT 查询才会更新这两个计数器,其他查询不会影响 “QueryCacheMisses”。