Caching on Opensource internals

ClickHouse's Query Result Cache: A Hash of the AST, Not the Text

Jay Hubbert — Wed, 21 Oct 2026 09:00:00 +0000

TL;DR: ClickHouse caches query results by hashing the parsed query, not the text you typed, plus the settings and database that could change the answer. Everything else - TTLs instead of invalidation, per-user quotas, an optional on-disk tier - follows from that one decision.

Every database has this feature and most of them get it half-right. The idea is old and simple: run the same query twice, serve the second one from memory.

The hard part was never the storage. It was the key.

Textual equality is hopeless. The same query can be spelled with different whitespace, different letter case, a different current database, or a different value of a setting that changes the answer. Meanwhile two queries that look different on the surface may produce identical rows, and you would love them to share an entry.

ClickHouse’s answer: hash the parsed query. That decision ripples through the whole design - the key construction, the TTL cache, the writer’s long list of reasons to refuse an entry, the reader’s access checks, and the on-disk backend that parks entries in a filesystem cache.

Let’s walk it end to end.

Why caching results is hard to get right

The header of the cache class states the contract plainly:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.h:48
/// Maps queries to query results. Useful to avoid repeated query calculation.
///
/// The cache does not aim to be transactionally consistent (which is difficult to get right). For example, the cache is not invalidated
/// when data is inserted/deleted into/from tables referenced by queries in the cache. In such situations, incorrect results may be
/// returned. In order to still obtain sufficiently up-to-date query results, a expiry time (TTL) must be specified for each cache entry
/// after which it becomes stale and is ignored. Stale entries are removed opportunistically from the cache, they are only evicted when a
/// new entry is inserted and the cache has insufficient capacity.

Read that again, because it is the whole correctness story: TTL, not invalidation. A result is valid for as long as its TTL says, and the entry is not invalidated when the underlying table changes.

This is a deliberate trade. Tracking table versions per entry would make every cache entry depend on the write path - and the write path is exactly the hot, latency-sensitive thing you do not want to slow down for the read path’s convenience.

The key: a hash of the AST, not of the text

The hashed part of the key is an IASTHash - a 128-bit hash of the parsed query:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.h:59
 struct Key
 {
 /// ----------------------------------------------------
 /// The actual key (data which gets hashed):

 /// The hash of the query AST.
 /// Unlike the query string, the AST is agnostic to lower/upper case (SELECT vs. select).
 IASTHash ast_hash;

Notice the comment. SELECT and select produce the same AST, so they produce the same hash, so they share one cache entry. That is the whole trick, and it falls out for free.

The AST is not hashed as-is, though. Two normalisations happen first.

Query-cache settings are stripped. A query that says SETTINGS use_query_cache = true should hit the entry written by the same query without that clause:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.cpp:500
ASTPtr removeQueryResultCacheSettings(ASTPtr ast)
{
 RemoveQueryResultCacheSettingsMatcher::Data visitor_data;
 RemoveQueryResultCacheSettingsVisitor(visitor_data).visit(ast);

 return ast;
}

And the predicate that decides which settings get pruned is deliberately generous about output-format settings, since those change how the answer is rendered, not what it is:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.cpp:413
bool settingDoesNotAffectQueryResultCache(const String & setting_name)
{
 return setting_name == "log_comment"
 /// As of today, the output format settings only affect the final output.
 /// However, it should be taken with caution - we should not use these settings in deterministic SQL functions.
 || setting_name.starts_with("output_format_")
 /// This setting is used to tune the server response, but does not affect the query behavior.
 /// An example why it should not affect query caching:
 /// - if you run a query as usual, and then run the same query with asking the server
 /// for Content-Disposition: attachment to download the result.
 || setting_name == "http_response_headers";
}

That last comment is a great one. Ask the server for the same rows as a download and you still want the same cached rows. Output format is not part of the result.

Planner-generated table aliases are removed for subqueries, so two identical subqueries that ended up under different plans share one entry. The pattern is matched exactly, because a user identifier that happens to look like __table1 must not be rewritten:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.cpp:513
bool isPlannerGeneratedTableAlias(std::string_view name)
{
 constexpr std::string_view prefix = "__table";
 if (!name.starts_with(prefix))
 return false;
 auto suffix = name.substr(prefix.size());
 if (suffix.empty())
 return false;
 for (char c : suffix)
 {
 if (c < '0' || c > '9')
 return false;
 }
 return true;
}

Strictly __table plus digits. No regex looseness, no user input sneaking through. This is the kind of detail that bites you years later if you get it wrong, and it took about four lines to get right.

What else goes into the hash

After the AST, the hash takes the current database and the changed settings:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.cpp:578
IASTHash calculateASTHash(ASTPtr ast, const String & current_database, const Settings & settings, const bool is_subquery, const bool pre_cleaned = false)
{
 if (!pre_cleaned)
 {
 ast = ast->clone();
 if (is_subquery)
 ast = removeTableAliases(ast);
 }
 ast = removeQueryResultCacheSettings(ast);

 /// Hash the AST, we must consider aliases (issue #56258)
 SipHash hash;
 ast->updateTreeHash(hash, /*ignore_aliases=*/ false);

 /// Also hash the database specified via SQL `USE db`, otherwise identifiers in same query (AST) may mean different columns in different
 /// tables (issue #64136)
 hash.update(current_database);

The current_database line is worth pausing on. An unqualified column name means different things in different databases, so the database is part of the identity of the answer. Hashing the AST alone would have been wrong here.

Then the settings, sorted, because Settings::changes() returns them in random order and a hash must be order-independent:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.cpp:596
 /// Finally, hash the (changed) settings as they might affect the query result (e.g. think of settings `additional_table_filters` and `limit`).
 /// Note: allChanged() returns the settings in random order. Also, update()-s of the composite hash must be done in deterministic order.
 /// Therefore, collect and sort the settings first, then hash them.
 auto changed_settings = settings.changes();
 std::vector<std::pair<String, String>> changed_settings_sorted; /// (name, value)
 for (const auto & change : changed_settings)
 {
 const String & name = change.name;
 if (!isSettingIgnoredInQueryResultCache(name)) /// see removeQueryResultCacheSettings() and isSubquerySpecificSetting() for why this is a good idea
 changed_settings_sorted.push_back({name, Settings::valueToStringUtil(change.name, change.value)});
 }

Only changed settings are hashed - a setting nobody touched cannot change the result relative to the default.

But there is a subtlety for subqueries, because the planner forcibly sets extremes, max_result_bytes and max_result_rows for them. Left alone, a subquery’s key would differ from the same query run at top level, and the cache would never hit:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.cpp:608
 /// The Planner forcibly sets `extremes`, `max_result_bytes`, `max_result_rows` for subqueries, which makes them
 /// appear in `settings.changes()`. Non-subquery executions of the same AST typically don't have these in their
 /// changed settings. To ensure cache hits between subquery writes and subquery reads, normalize by always
 /// including the default values of these settings for subqueries.
 if (is_subquery)
 {
 if (!changed_settings.tryGet("extremes"))
 changed_settings_sorted.push_back({"extremes", settings[Setting::extremes].toString()});

The equality of two keys

Now note what is not in the equality check. Two keys are equal if the AST hashes match and they are both subqueries or both not:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.cpp:715
bool QueryResultCache::Key::operator==(const Key & other) const
{
 return ast_hash == other.ast_hash && is_subquery == other.is_subquery;
}

The user id and the roles are not part of the key. They get checked at read time instead, which is why one entry per query is enough to still enforce access control. More on that below.

The hasher is trivial, because the AST hash is already a good hash:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.cpp:720
size_t QueryResultCache::KeyHasher::operator()(const Key & key) const
{
 SipHash hash;
 hash.update(key.ast_hash.low64);
 hash.update(key.is_subquery);
 return hash.get64();
}

What may be cached at all

Not every query may be cached. A query with a non-deterministic function (now(), rand()) would return a different answer the second time. The check walks the AST and asks the function factory:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.cpp:105
 if (const auto func = FunctionFactory::instance().tryGet(function->name, data.context))
 {
 if (!func->isDeterministic())
 data.has_non_deterministic_functions = true;
 return;
 }

Two escape hatches get special care.

The eval table function hides its real query inside an opaque string, so ClickHouse cannot inspect it. What it cannot see, it must not trust:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.cpp:96
 /// The `eval` table function hides its real query inside an opaque string argument, so the
 /// generated query cannot be inspected here. Treat it as non-deterministic (and, in
 /// HasSystemTablesMatcher, as touching a system table) to keep such queries out of the cache,
 /// e.g. `eval('SELECT now()')` must not be cached as if it were deterministic.
 if (function->name == "eval")
 {
 data.has_non_deterministic_functions = true;
 return;
 }

And SQL UDFs, whose determinism ClickHouse simply does not know:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.cpp:111
 if (const auto udf_sql = UserDefinedSQLFunctionFactory::instance().tryGet(function->name))
 {
 /// Driver-created executable functions are also persisted in the SQL-object storage,
 /// but their determinism is described by the generated executable UDF configuration checked below.
 if (!udf_sql->as<ASTCreateFunctionWithDriverQuery>())
 {
 /// ClickHouse currently doesn't know if SQL-based UDFs are deterministic or not. We must assume they are non-deterministic.
 data.has_non_deterministic_functions = true;
 return;
 }
 }

The obfuscate table function is subtler still: it is deterministic if a seed is given, and the seed can be overridden by a SETTINGS clause on any enclosing query. So the check has to descend into the AST while tracking the effective settings:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.cpp:309
 if (const auto * function = node->as<ASTFunction>())
 if (function->name == "obfuscate" && context->getSettingsRef()[Setting::obfuscate_seed].value.empty())
 return true;

What the user wants to happen on a violation is a setting, with three values (throw, save, ignore):

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.cpp:371
 const QueryResultCacheNondeterministicFunctionHandling nondeterministic_function_handling
 = settings[Setting::query_cache_nondeterministic_function_handling];
 const QueryResultCacheSystemTableHandling system_table_handling = settings[Setting::query_cache_system_table_handling];

 if (ast_contains_nondeterministic_functions && nondeterministic_function_handling == QueryResultCacheNondeterministicFunctionHandling::Throw)
 throw Exception(ErrorCodes::QUERY_CACHE_USED_WITH_NONDETERMINISTIC_FUNCTIONS,
 "The query result was not cached because the query contains a non-deterministic function."
 " Use setting `query_cache_nondeterministic_function_handling = 'save'` or `= 'ignore'` to cache the query result regardless, or omit caching");

So:

 sql
 
 
-- A non-deterministic query is refused by default:
SELECT * FROM events WHERE ts > now() - INTERVAL 1 HOUR;
-- ERROR: The query result was not cached because the query contains a non-deterministic function.

-- ... unless you insist:
SELECT * FROM events WHERE ts > now() - INTERVAL 1 HOUR
SETTINGS query_cache_nondeterministic_function_handling = 'save';

Gotcha: the default is throw, and the error message arrives after the query has already run. You paid for the computation, then threw the result away.

The cache itself

The cache is a TTL cache with per-user quotas and its own metrics:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.cpp:1180
QueryResultCache::QueryResultCache(size_t max_size_in_bytes, size_t max_entries, size_t max_entry_size_in_bytes_, size_t max_entry_size_in_rows_)
 : cache(std::make_unique<TTLCachePolicy<Key, Entry, KeyHasher, EntryWeight, IsStale>>(
 CurrentMetrics::QueryCacheBytes, CurrentMetrics::QueryCacheEntries, std::make_unique<PerUserTTLCachePolicyUserQuota>()))
{
 updateConfiguration(max_size_in_bytes, max_entries, max_entry_size_in_bytes_, max_entry_size_in_rows_);
}

Staleness is a pure function of the key:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.cpp:738
bool QueryResultCache::IsStale::operator()(const Key & key) const
{
 return (key.expires_at < std::chrono::system_clock::now());
};

The eviction policy is worth spelling out, because it is not an LRU. When an insert does not fit, the cache first purges the stale entries - the ones whose TTL has passed - and if that is still not enough, the insert is simply refused and the new result is dropped. The cache never evicts a fresh entry to make room for another fresh entry:

 cpp
 
 
// src/Common/TTLCachePolicy.h:237
 if (!sufficient_space_in_cache() || !sufficient_space_in_cache_for_user())
 {
 /// Remove stale entries
 for (auto it = cache.begin(); it != cache.end();)
 {
 if (is_stale_function(it->first))
 {
 size_t sz = weight_function(*it->second);
 if (it->first.user_id.has_value())
 Base::user_quotas->decreaseActual(*it->first.user_id, sz);
 it = cache.erase(it);
 size_in_bytes -= sz;
 }
 else
 ++it;
 }
 }

That’s a deliberate refusal to thrash. A cache that evicts live entries to admit fresh ones can end up with a 0% hit rate under pressure. This one keeps its hot set and simply refuses new work when full.

The weight of an entry is the number of bytes its chunks actually allocate:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.cpp:728
size_t QueryResultCache::EntryWeight::operator()(const Entry & entry) const
{
 size_t res = 0;
 for (const auto & chunk : entry.chunks)
 res += chunk.allocatedBytes();
 res += entry.totals.has_value() ? entry.totals->allocatedBytes() : 0;
 res += entry.extremes.has_value() ? entry.extremes->allocatedBytes() : 0;
 return res;
}

Per-user quotas are pushed into the cache on every write, because there is no better hook for “the settings profile of this user changed”:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.cpp:1220
 /// Update the per-user cache quotas with the values stored in the query context. This happens per query which writes into the query
 /// cache. Obviously, this is overkill but I could find the good place to hook into which is called when the settings profiles in
 /// users.xml change.
 /// user_id == std::nullopt is the internal user for which no quota can be configured
 if (key.user_id.has_value())
 cache.setQuotaForUser(*key.user_id, max_query_result_cache_size_in_bytes_quota, max_query_result_cache_entries_quota);

The comment admits it: this is overkill. It works, but it is the kind of thing you notice on a Friday afternoon and want to fix. It never gets fixed.

The two backends

 text
 
 
 query AST
 | clone + strip cache settings + strip planner aliases
 | hash(AST) + hash(current_database) + hash(changed settings)
 v
 QueryResultCache::Key { ast_hash, user_id, roles, is_shared, ttl, header }
 |
 +--> in-memory TTLCachePolicy <-- Chunks (optionally compressed)
 | | weight = allocated bytes, per-user quota
 | v
 | SourceFromChunks --> the query pipeline
 |
 +--> on-disk: FileCacheKey(salted hash) --> filesystem cache
 | FixedHeader (magic, version, sizes, ttl, build fingerprint, checksum)
 | AccessMetadata (is_shared, user, roles, tag)
 | CompressedWriteBuffer + NativeWriter (header + chunks + totals + extremes)
 v
 filesystem cache (evicted by the same rules as any other data)

Writing: many reasons to refuse

The writer buffers the result chunks as they stream by and decides at the very end whether to keep them. That is deliberate - a query that dies half-way must not leave a partial entry:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.h:222
/// Buffers multiple partial query result chunks (buffer()) and eventually stores them as cache entry (finalizeWrite()).
///
/// Implementation note: Queries may throw exceptions during runtime, e.g. out-of-memory errors. In this case, no query result must be
/// written into the query result cache. Unfortunately, neither the Writer nor the special transform added on top of the query pipeline
/// which holds the Writer know whether they are destroyed because the query ended successfully or because of an exception (otherwise, we
/// could simply implement a check in their destructors). To handle exceptions correctly nevertheless, we do the actual insert in
/// finalizeWrite() as opposed to the Writer destructor. This function is then called only for successful queries in finish_callback() which
/// runs before the transform and the Writer are destroyed, whereas for unsuccessful queries we do nothing (the Writer is destroyed w/o
/// inserting anything).

Here’s the thing: the insert happens in finalizeWrite(), not in a destructor. Destructors cannot tell “the query finished” from “the query threw”, so the code routes the decision through a callback that only fires on success. That is a small piece of engineering taste that saves a lot of corrupted cache entries.

The list of refusal reasons in finalizeWrite is the interesting part:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.cpp:862
 if (result_is_incomplete)
 {
 LOG_TRACE(logger, "Skipped insert because the query result is incomplete (a consumer stopped reading it before the end), query: {}", doubleQuoteString(key.query_string));
 return;
 }

 if (auto query_runtime = std::chrono::duration_cast<std::chrono::milliseconds>(std::chrono::system_clock::now() - query_start_time); query_runtime < min_query_runtime)
 {
 LOG_TRACE(logger, "Skipped insert because the query is not expensive enough, query runtime: {} msec (minimum query runtime: {} msec), query: {}",
 query_runtime.count(), min_query_runtime.count(), doubleQuoteString(key.query_string));
 return;
 }

The second one is the classic “don’t cache the cheap queries” rule. Caching a 1 ms query costs more than recomputing it. The setting is query_cache_min_query_duration.

Partial chunks are squashed into blocks of max_block_size rows before being stored, so the cached result looks like a freshly produced one:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.cpp:889
 if (squash_partial_results)
 {
 /// Squash partial result chunks to chunks of size 'max_block_size' each. This costs some performance but provides a more natural
 /// compression of neither too small nor big blocks. Also, it will look like 'max_block_size' is respected when the query result is
 /// served later on from the query result cache.

And the entries are compressed, at the cost of a decompression on read:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.cpp:969
 if (key.is_compressed)
 {
 /// Compress result chunks. Reduces the space consumption of the cache but means reading from it will be slower due to decompression.

 Chunks compressed_chunks;

 for (const auto & chunk : query_result->chunks)
 {
 const Columns & columns = chunk.getColumns();
 Columns compressed_columns;
 for (const auto & column : columns)
 {
 auto compressed_column = column->compress(/*force_compression=*/false);
 compressed_columns.push_back(compressed_column);
 }
 Chunk compressed_chunk(compressed_columns, chunk.getNumRows());
 compressed_chunks.push_back(std::move(compressed_chunk));
 }
 query_result->chunks = std::move(compressed_chunks);
 }

column->compress(force_compression=false) is the interesting bit: a column is compressed only if it is worth it. A tiny column of random UInt64s costs more CPU than it saves in RAM, so it is stored as-is.

Finally the size limits are checked against the compressed weight:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.cpp:992
 size_t new_entry_size_in_bytes = QueryResultCache::EntryWeight()(*query_result);
 size_t new_entry_size_in_rows = count_rows_in_chunks(*query_result);

 if ((new_entry_size_in_bytes > max_entry_size_in_bytes) || (new_entry_size_in_rows > max_entry_size_in_rows))
 {
 LOG_TRACE(logger, "Skipped insert because the query result is too big, query result size: {} (maximum size: {}), query result size in rows: {} (maximum size: {}), query: {}",
 formatReadableSizeWithBinarySuffix(new_entry_size_in_bytes, 0), formatReadableSizeWithBinarySuffix(max_entry_size_in_bytes, 0), new_entry_size_in_rows, max_entry_size_in_rows, doubleQuoteString(key.query_string));
 return;
 }

 cache.set(key, query_result);

Reading: access control

The reader looks the key up and then checks whether the caller may have it. The user id and the current roles live in the key but are not part of the equality check, so the same entry can be found by a different user - and then rejected:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.cpp:1067
 const auto & entry_key = entry->key;
 const auto & entry_mapped = entry->mapped;

 const bool is_same_user_id = ((!entry_key.user_id.has_value() && !key.user_id.has_value()) || (entry_key.user_id.has_value() && key.user_id.has_value() && *entry_key.user_id == *key.user_id));
 const bool is_same_current_user_roles = (entry_key.current_user_roles == key.current_user_roles);
 if (!entry_key.is_shared && (!is_same_user_id || !is_same_current_user_roles))
 {
 LOG_TRACE(logger, "Inaccessible query result found for query {}", doubleQuoteString(key.query_string));
 return;
 }

The rationale for checking the roles and not just the user is in the key’s comment:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.h:78
 /// The id and current roles of the user who executed the query.
 /// These members are necessary to ensure that a (non-shared, see below) entry can only be written and read by the same user with
 /// the same roles. Example attack scenarios:
 /// - after DROP USER, it must not be possible to create a new user with with the dropped user name and access the dropped user's
 /// query result cache entries
 /// - different roles of the same user may be tied to different row-level policies. It must not be possible to switch role and
 /// access another role's cache entries
 std::optional<UUID> user_id;
 std::vector<UUID> current_user_roles;

Read that as two attack scenarios. First: drop a user, recreate someone with the same name, and try to read the old user’s cached rows. Second: one user, two roles, different row-level policies - switch role, keep the rows.

Storing roles in the key but not in the equality check is the clever part. The entry stays shareable by identity, and access control happens on the way out.

A stale entry is also refused:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCache.cpp:1078
 if (QueryResultCache::IsStale()(entry_key))
 {
 LOG_TRACE(logger, "Stale query result found for query {}", doubleQuoteString(key.query_string));
 return;
 }

And the chunks are cloned (uncompressed case) or decompressed (compressed case) before being handed to a SourceFromChunks processor, which becomes the new head of the query pipeline.

The on-disk backend

The in-memory cache is bounded by RAM. The on-disk backend stores entries in a filesystem cache - the same infrastructure used for remote table data - which means the entries can be much larger, survive restarts, and (with a distributed filesystem cache) be shared between servers.

 cpp
 
 
// src/Interpreters/Cache/QueryResultCacheOnDisk.h:14
/// Stores query result cache entries in a preconfigured filesystem cache (an entry of the `filesystem_caches` section of the server
/// configuration), so that cached query results get more space than in memory, survive server restarts, and (with a distributed
/// filesystem cache) can be shared between servers. The filesystem cache is selected per query with setting
/// `query_cache_on_disk_cache_name`.
///
/// The entries are ordinary filesystem cache entries, indistinguishable from other data in the same filesystem cache: they are not
/// held from deletion, they are evicted by the same rules, and there are no specific limits on their total size or number other than
/// the limits of the filesystem cache itself. The keys are hashed with a salt so that they cannot intersect with other keys in the
/// filesystem cache. All metadata needed to validate an entry (TTL, access control) is serialized into the entry itself; no in-memory
/// state is kept.

Reusing the filesystem cache is a lovely bit of leverage. You inherit its eviction, its checksumming, its remote-storage support, and its cluster plumbing, instead of inventing a parallel universe.

The key

The on-disk key is a salted hash of the AST hash, plus the access context for non-shared entries:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCacheOnDisk.cpp:136
FileCacheKey makeFileCacheKey(const QueryResultCache::Key & key, bool is_shared)
{
 /// Salt the hash so that keys of the on-disk query result cache cannot intersect with other keys in the same filesystem cache
 /// (those are typically derived from storage paths).
 SipHash hash;
 hash.update(std::string_view("QueryResultCacheOnDisk"));
 hash.update(key.ast_hash.low64);
 hash.update(key.ast_hash.high64);
 hash.update(key.is_subquery);
 hash.update(is_shared);
 if (!is_shared)
 {
 hash.update(key.user_id.has_value());
 if (key.user_id)
 hash.update(key.user_id->toUnderType());
 /// The roles are compared as an ordered sequence, same as in the in-memory query result cache.
 hash.update(key.current_user_roles.size());
 for (const auto & role : key.current_user_roles)
 hash.update(role.toUnderType());
 }

Note that unlike the in-memory cache, the on-disk key does include the user. The filesystem cache is shared storage, so one user’s entry must never shadow another’s - there is no “check on read” step in shared storage, so identity has to be baked into the key itself.

A marker in the middle of the key lets the cache find its own entries without reading anything from disk:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCacheOnDisk.cpp:103
/// Bits 64..95 of every key of the on-disk query result cache hold this marker ("QRCC"), so that the entries can be told apart from
/// the other keys of the filesystem cache by the key alone, without reading anything from disk (see `clear`). The marker sits in the
/// middle of the key on purpose: the filesystem cache derives the directory of a key from its topmost bits and the metadata bucket
/// from its lowest bits, both of which must keep varying. The remaining 96 bits of hash are plenty to keep the entries apart. A key
/// of other data carries the marker by chance with probability 2^-32; such a key is still recognized as foreign by its content.
constexpr UInt32 KEY_MARKER = 0x51524343;

That comment is a small masterpiece of constraint juggling. The marker cannot sit at the top (the directory is derived from the top bits) and cannot sit at the bottom (the metadata bucket is derived from the lowest bits), so it goes in the middle - and it admits the 2^-32 collision chance right there.

The entry format

The on-disk entry has a fixed-size header, then uncompressed access metadata, then the compressed payload:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCacheOnDisk.cpp:63
/// On-disk entry layout, version 6:
///
/// Fixed header (FIXED_HEADER_SIZE bytes):
/// char[8] magic "QRCache1"
/// UInt32 format version
/// UInt32 TCP protocol revision the Native blocks are serialized with
/// UInt64 total entry size in bytes, including the fixed header
/// UInt64 created_at, seconds since epoch
/// UInt64 expires_at, seconds since epoch
/// UInt64 fingerprint of the server build which wrote the entry (see `getServerBuildFingerprint`)
/// UInt128 SipHash-128 of the preceding fixed header bytes and of everything after the fixed header. The freshness
/// fields are authenticated as well: a corruption of `expires_at` or `total_size` alone would otherwise
/// silently change how long the entry is served, without ever failing the integrity check.
///
/// Access metadata (uncompressed):
/// UInt8 is_shared
/// UInt8 has_user_id, [UInt128 user_id]
/// varUInt number of user roles, [UInt128 role]...
/// String tag (setting `query_cache_tag`), so that `SYSTEM DROP QUERY CACHE TAG` can find the entry
///
/// Result payload (compressed with the codec from setting `query_cache_on_disk_codec`; the compression frames are
/// self-describing, so reading does not depend on the setting):
/// varUInt number of result chunks
/// Native header block (zero rows)
/// Chunk one per result chunk
/// UInt8 has_totals, [Chunk]
/// UInt8 has_extremes, [Chunk]

Two details are worth dwelling on.

The build fingerprint. An entry is only valid for the server build that wrote it, because a new build may compute a different answer for the same query:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCacheOnDisk.cpp:110
/// The entries survive restarts and can be shared between servers, but a result is only valid for the server build which computed
/// it: a newer or older build may compute a different result for the same query (fixes of functions or of the planner, changed
/// defaults), even when neither the TCP protocol revision nor the entry format changes. So every entry records the build which wrote
/// it, and an entry of another build is treated like an entry of an incompatible format: it is never served, and it is overwritten
/// on the next write.

The checksum covers the freshness fields. Otherwise a corrupted expires_at would silently change how long the entry lives - and a bit flip in the wrong byte would be invisible.

The header is patched in place after the payload is serialised, and the checksum is computed over the header and the body:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCacheOnDisk.cpp:514
 unalignedStoreLittleEndian<UInt64>(data.data() + TOTAL_SIZE_OFFSET_IN_FIXED_HEADER, data.size());

 SipHash hash;
 hash.update(data.data(), CHECKSUM_OFFSET_IN_FIXED_HEADER);
 hash.update(data.data() + FIXED_HEADER_SIZE, data.size() - FIXED_HEADER_SIZE);
 UInt128 checksum = hash.get128();
 transformEndianness<std::endian::little>(checksum);
 memcpy(data.data() + CHECKSUM_OFFSET_IN_FIXED_HEADER, &checksum, sizeof(checksum));

Probing and writing

Writing is best-effort and never throws. Before writing, the existing entry is probed to see whether it is fresh, being written concurrently, or garbage:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCacheOnDisk.cpp:365
QueryResultCacheOnDisk::ProbeResult QueryResultCacheOnDisk::probeExistingEntry(const FileCacheKey & cache_key) const
{
 const auto & user_id = FileCache::getCommonOrigin().user_id;

 auto holder = file_cache->getDownloadedContiguousOrEmpty(cache_key, 0, FIXED_HEADER_SIZE, user_id);
 for (size_t attempt = 0; holder->empty(); ++attempt)
 {
 /// No readable header: either there is no entry, or another query is writing one (its segments are held and not
 /// downloaded yet), or only the tail of a partially evicted entry is left. The tail must be removed, otherwise no
 /// entry could be created for the key until it is evicted too.
 const auto segments = file_cache->tryGetFileSegmentInfos(cache_key, user_id);
 if (segments.empty())
 return ProbeResult::None;
 for (const auto & segment : segments)
 {
 if (segment.state != FileSegment::State::DOWNLOADED || segment.references > 1)
 return ProbeResult::InProgress;
 }

The write itself reserves the space for all the segments of the entry before writing any of them, so an entry is either complete or absent:

 cpp
 
 
// src/Interpreters/Cache/QueryResultCacheOnDisk.cpp:529
 /// Create all file segments of the entry at once. This fails gracefully if another query created an entry for the same key in
 /// the meantime (then we simply skip the insert), and guarantees that we exclusively own all segments of the key while writing.
 /// A reader sees the incomplete entry as a miss because not all of its bytes are downloaded yet.
 auto holder = file_cache->trySet(cache_key, 0, data.size(), CreateFileSegmentSettings(FileSegmentKind::Regular), origin);
 if (!holder)
 {
 LOG_TRACE(logger, "Skipped insert into the on-disk query result cache because of a concurrent insert for query {}",
 doubleQuoteString(key.query_string));
 return;
 }

Two concurrent writers, one winner, no corruption. The loser just skips the insert. That is a much nicer failure mode than the usual write-write race.

The reader side is symmetric: it downloads the whole entry, verifies the checksum, and only then decompresses it.

Using it

The cache is off by default; you turn it on per query or per session:

 xml
 
 
<!-- Server configuration: a 1 GiB in-memory query result cache. -->
<query_cache>
 <max_size_in_bytes>1073741824</max_size_in_bytes>
 <max_entries>1024</max_entries>
 <max_entry_size_in_bytes>1048576</max_entry_size_in_bytes>
 <max_entry_size_in_rows>30000000</max_entry_size_in_rows>
</query_cache>

 sql
 
 
SELECT count() FROM hits WHERE UserID = 42 SETTINGS use_query_cache = true;
-- the second execution is served from the cache

The per-user quota is a setting, not a config element, so it can differ per profile: query_cache_max_size_in_bytes and query_cache_max_entries.

The observable state lives in system tables:

 sql
 
 
SELECT query_id, length, hits, QueryCacheHits, QueryCacheMisses FROM system.query_log LIMIT 10;
SELECT query, result_size, tag, stale, shared, compressed, expires_at FROM system.query_result_cache LIMIT 10;

SYSTEM CLEAR QUERY CACHE clears everything, SYSTEM CLEAR QUERY CACHE TAG '<tag>' clears one tag’s worth.

Trade-offs

What it buys: a dashboard that runs the same heavy aggregate every 10 seconds stops paying for the aggregate, and the server’s CPU goes to the queries that are actually different. If you have ever watched a Grafana dashboard redraw in lockstep with 40 open tabs asking for the same number, this is the fix.

What it costs:

Staleness is unbounded up to the TTL. The cache is not invalidated on INSERT. A TTL of 1 hour means an hour-old answer. This is the documented contract, not a bug, but it is the reason the cache is opt-in.
The key is a hash, so it inherits hash-collision risk. Two different queries with the same 128-bit AST hash would share an entry. In practice this does not happen; there is no secondary check of the query text.
Memory is the scarce resource. The in-memory cache holds result data, not plans, and the results are held compressed. A server with a 1 GiB cache can easily be asked for 10 GiB of results; the size limits (max_entry_size_in_bytes, max_entry_size_in_rows) exist to keep one huge result from evicting everything else.
Compression is a trade, not a win. The default query_cache_compress_entries makes reads slower and saves RAM; on a server that is memory-bound it is right, on one that is CPU-bound it is wrong.
The on-disk backend has its own failure modes: partially evicted entries, entries written by a different build, a filesystem cache that is not yet initialised. All of them are handled by treating the entry as a miss, and the probe-then-write dance means two concurrent writers cannot corrupt each other - one of them simply loses.

Wrapping up

The one thing to remember: the cache’s hardest problem - the key - is solved by ClickHouse’s parser rather than by the cache. Hashing the AST instead of the text means select and SELECT share an entry, and the planner’s internal alias noise never leaks into the key.

Worth internalizing: this is a cache that is allowed to be wrong, on purpose. TTLs instead of invalidation is a choice, and the price is an answer that can be up to a TTL old. Pick the TTL like you mean it.

What to go do about it: if you have a dashboard, an ORM that generates the same SQL every 30 seconds, or a report job that hammers the same aggregate - turn on use_query_cache for exactly those queries, set a short TTL, and check system.query_result_cache to see whether the hit rate justifies the memory.

ClickHouse's Query Condition Cache: Skip Granules You Don't Need to Read

Jay Hubbert — Wed, 21 Oct 2026 09:00:00 +0000

TL;DR: ClickHouse caches, per (table, part, predicate), a bitmap of granules that a filter proved empty. Repeated queries skip those granules entirely — no index analysis, no reading, no decompression. The cache only records negative results (“this granule matched nothing”), never positive ones, and it salts the key with settings, time zones, and skip-index profiles so a wrong verdict can never leak between queries.

Index analysis is not free. Every time a query runs, ClickHouse has to figure out which granules of which parts could possibly contain a matching row. That means evaluating the predicate against the primary key index, the minmax indexes, the skip indexes, and — in the hard cases — a recursive exclusion search over the marks.

Now think about a real workload: a monitoring dashboard that runs the same query every 30 seconds, a service filtering on tenant_id = 42 over and over, a batch job re-reading yesterday’s data hourly. The predicate is the same every time. The data isn’t — but the data is also mostly not matching.

That’s a textbook case for memoization, and ClickHouse implements it as the QueryConditionCache: a global LRU that remembers, for each (table UUID, part name, predicate hash) triple, a bitmap of the granules the predicate emptied during the last scan.

What the cache actually stores

The class doc is unusually explicit:

 cpp
 
 
// src/Interpreters/Cache/QueryConditionCache.h:26
/// An implementation of predicate caching a la https://doi.org/10.1145/3626246.3653395
///
/// Given the table, part name and a hash of a predicate as key, caches which marks definitely don't match the predicate and which marks may
/// match the predicate. This allows to skip the scan if the same predicate is evaluated on the same data again. Note that this doesn't work
/// the other way round: we can't tell if _all_ rows in the mark match the predicate.
class QueryConditionCache
{
public:
 /// False means none of the rows in the mark match the predicate. We can skip such marks.
 /// True means at least one row in the mark matches the predicate. We need to read such marks.
 using MatchingMarks = std::vector<bool>;

Two things to internalize:

It’s one-directional. The cache records “this granule matched nothing.” It never records “this granule matched everything” — because a scan can’t establish that. If a granule produced rows, the cache can’t tell whether all of them matched.

It’s allowed to be imprecise — in one direction only. The bitmap’s true means “may match.” A granule that matched one row in a million is marked true — the whole granule has to be read. The cache never produces a false negative, which is the only thing that matters for correctness.

MatchingMarks is a std::vector<bool> — a bit-packed boolean array, one bit per granule. A part with 100,000 granules costs 12.5 KB per predicate.

The whole mechanism is controlled by use_query_condition_cache, which defaults to true.

The key: three components, hashed

 cpp
 
 
// src/Interpreters/Cache/QueryConditionCache.h:45
private:
 /// A hash of the table id, part name and condition id.
 using Key = UInt128;

 cpp
 
 
// src/Interpreters/Cache/QueryConditionCache.cpp:237
QueryConditionCache::Key QueryConditionCache::makeKey(const UUID & table_id, const String & part_name, UInt64 condition_hash)
{
 SipHash hash;
 hash.update(table_id);
 hash.update(part_name);
 hash.update(condition_hash);
 return hash.get128();
}

The key is the part, so a cached verdict about one part never leaks into another. The part name is qualified by the table UUID, so two tables with the same part name (very common in MergeTree — part names come from block ranges and partition values) don’t collide.

There’s a wrinkle for file-backed engines, where “part” is a file:

 cpp
 
 
// src/Interpreters/Cache/QueryConditionCache.h:93
 static String makeFilePartName(const String & path, std::string_view version_token);

This folds in a content-version token (ETag for remote objects, mtime+inode+size for local files) so an in-place rewrite of the file yields a different key rather than a stale hit. For a file-backed table, the “part” can change under you, and a stale “this file matches nothing” verdict would be a correctness bug.

The safety property: everything starts as “may match”

This is the detail that makes the whole thing safe. When an entry is created, every granule is marked true — “may match” — so a fresh entry skips nothing:

 cpp
 
 
// src/Interpreters/Cache/QueryConditionCache.cpp:396
QueryConditionCache::Entry::Entry(size_t mark_count)
 : matching_marks(mark_count, true)
{
}

The header explains why that default is a correctness requirement, not a performance one: if a query is cancelled mid-scan and the cache had been updated optimistically (“these granules match nothing”), future scans would skip granules the predicate would in fact have matched — wrong results, silently, forever.

By initializing everything to “may match” and only ever clearing bits after the scan has proven the granule empty, a crash can only lose information (the cache knows less than it could), never gain it.

Writing: only clear bits, never set them

 cpp
 
 
// src/Interpreters/Cache/QueryConditionCache.cpp:272
void QueryConditionCache::write(
 const UUID & table_id, const String & part_name, UInt64 condition_hash, const String & condition,
 const MarkRanges & mark_ranges, size_t marks_count, bool has_final_mark)
{
 if (table_id == UUIDHelpers::Nil)
 return;

 Key key = makeKey(table_id, part_name, condition_hash);

 auto load_func = [&](){ return std::make_shared<Entry>(marks_count); };

 auto [entry, inserted] = cache.getOrSet(key, load_func);

getOrSet is atomic: two concurrent scans of the same part with the same predicate can’t create two entries; they share one.

Then the update — note the direction:

 cpp
 
 
// src/Interpreters/Cache/QueryConditionCache.cpp:311
 {
 std::lock_guard lock(entry->mutex);

 for (const auto & mark_range : mark_ranges)
 std::fill(entry->matching_marks.begin() + mark_range.begin, entry->matching_marks.begin() + mark_range.end, false);

 if (has_final_mark)
 entry->matching_marks[marks_count - 1] = false;
 }

std::fill(..., false) — the entry is only ever narrowed. The mark ranges passed in are the ones the scan proved empty. Nothing is ever set back to true, because “this granule matched something” isn’t a fact the cache can rely on: a later scan of the same part with the same predicate might read a different set of marks (another query’s cached verdict pruned some!), and those un-read marks must stay “may match.”

That last point is subtle and important: the cache is a cache of negative results only, and the negative results are monotone. Once a granule is known empty for a predicate, it stays known empty for as long as the entry lives.

There’s also a fast path that avoids taking the exclusive lock when there’s nothing to do — most writes are no-ops because the same query run repeatedly finds the same granules empty and the bits are already clear.

Why the entry has its own mutex

The CacheBase lock protects the map — the mapping from key to entry. It does not protect the contents of the entry. And the contents are mutated concurrently: a query with 16 streams reads 16 disjoint mark ranges of the same part simultaneously, and each writes back the ranges it proved empty.

Without a per-entry lock, two threads could be doing std::fill(begin, mid, false) and std::fill(mid, end, false) simultaneously on the same std::vector<bool>. std::vector<bool> packs eight booleans into a byte, so the two fills could land in the same byte and lose one another’s writes — a lost update, which means a granule proven empty stays “may match.” Not a correctness bug (only a lost optimization), but a real one.

The SharedMutex lets the many readers of a cached verdict proceed in parallel while the rare writer excludes them.

Reading: turning a bitmap back into mark ranges

The consult side is in MergeTreeDataSelectExecutor::filterPartsByQueryConditionCache. After the cache lookup, the bitmap is converted back into MarkRanges — the surviving granules:

 cpp
 
 
// src/Storages/MergeTree/MergeTreeDataSelectExecutor.cpp:1944
 for (const auto & mark_range : part_with_ranges.ranges)
 {
 size_t begin = mark_range.begin;
 for (size_t mark_it = begin; mark_it < mark_range.end;)
 {
 if (!matching_marks[mark_it])
 {
 // ... collapse consecutive zeros into skip ranges ...
 }
 else
 ++mark_it;
 }
 }

0 means “skip this granule,” 1 means “must read it.” Leading zeros are skipped. A gap of zeros between two ones is dropped — unless the gap is smaller than min_marks_for_seek, in which case reading through it is cheaper than seeking past it.

And if every granule of the part was eliminated, the part is dropped from the query entirely:

 cpp
 
 
// src/Storages/MergeTree/MergeTreeDataSelectExecutor.cpp:1994
 if (ranges.empty())
 it = parts_with_ranges.erase(it);

A part the cached verdict proves empty is not opened at all. No marks read, no decompression, no filters evaluated.

The predicate hash is not just the predicate

The most delicate part of the design is the key. If two different predicates hashed to the same value, one query’s verdict would be applied to another query’s data — silently returning wrong results.

The base hash is the ActionsDAG hash of the filter expression, covering function names, result types, children, and constant values. But that’s not enough:

 sql
 
SELECT * FROM t WHERE ts >= now() - INTERVAL 10 DAY;

The DAG hash changes every time the query runs (the constant changes), so this predicate never gets a cache hit. Fine — but there’s a subtler problem in the other direction: a setting can change a function’s result without changing the DAG. formatDateTime with different flags produces different strings from the same DAG. least/greatest propagate NULLs differently. h3ToGeo swaps its arguments.

So the cache key includes a salt computed from every setting a function might capture at build time — settings like session_timezone, formatdatetime_f_prints_single_zero, least_greatest_legacy_null_behavior, h3togeo_lon_lat_result_order, and dozens more.

Two sessions in different time zones produce the same DAG for toDateTime(s), but parse s differently. Without the salt, one session’s verdict would be served to the other. This is the kind of bug that’s nearly impossible to find by testing and completely obvious once you’ve read the rule.

The time-condition trick

now() in a predicate is a special case, handled with a derived condition rather than a salt.

The problem: WHERE ts >= now() - INTERVAL 10 DAY has a different DAG hash every second, so it never caches. But it’s a very common predicate.

The solution: round the time constant onto a grid. On the write side, the condition is strengthened; on the read side, it’s weakened:

 cpp
 
 
// src/Processors/QueryPlan/Optimizations/updateQueryConditionCache.cpp:107
 /// Non-deterministic conditions must not be cached under their own hash.
 /// For conditions non-deterministic only because of folded current-time constants,
 /// a deterministic condition can be derived by rounding the constants onto a time grid.

Read the logic carefully, because the asymmetry is the whole trick:

Write side (strengthen): the actual filter used now() - 10 days. The derived condition is a rounded version, e.g. rounded up to the next grid point — a narrower condition. If the narrow condition matched no rows in this granule, the wider (actual) condition certainly matched no rows either. So the entry (written under the derived hash) is sound.
Read side (weaken): the query probes with the rounded-down version, which is wider. “The wider condition matched no rows” implies “the narrower condition matched no rows” — so skipping is sound.

The two coincide for grid-aligned constants and are one grid cell apart otherwise. The grid factor is a setting (query_condition_cache_time_condition_grid_factor).

This is genuinely elegant reasoning: it takes a predicate that’s not cacheable (its value changes every second) and makes it cacheable by proving that a slightly different, grid-aligned predicate implies the right thing in both directions.

The skip-index profile: another salt

Some cached verdicts come from skip index analysis — “the minmax index on this column says no row in this granule can match.” But skip index analysis depends on which indexes exist and are enabled. If a query runs with use_skip_indexes = 0 and another runs with them on, the verdicts differ.

So skip-index verdicts are stored under a profiled key — the condition hash salted with the profile of the index set that produced the verdict:

 cpp
 
 
// src/Storages/MergeTree/MergeTreeDataSelectExecutor.cpp:1771
 /// Each condition is looked up under two keys:
 /// * the bare condition hash, holding row-level exclusions (always sound);
 /// * a hash salted with the effective skip-index profile (skip-index exclusions).

A mark may be skipped iff either verdict says it doesn’t match — the merge is an AND of the two “may match” bitmaps:

 cpp
 
 
// src/Storages/MergeTree/MergeTreeDataSelectExecutor.cpp:1881
 matching_marks[i] = matching_marks[i] && (*marks_opt)[i];

AND of the “may match” bits: a granule is skipped only if both verdicts agree it cannot match. Conservative in the right direction.

Where the “empty granule” fact comes from

The write side is the read pipeline itself. When the PREWHERE filter processes a granule and the filter removes every row of it, the read task records the granule as “unmatched”:

 cpp
 
 
// src/Storages/MergeTree/MergeTreeReadTask.cpp:590
void MergeTreeReadTask::addPrewhereUnmatchedMarks(const MarkRanges & mark_ranges_)
{
 prewhere_unmatched_marks.insert(prewhere_unmatched_marks.end(), mark_ranges_.begin(), mark_ranges_.end());
}

And the write happens when the task is finished:

 cpp
 
 
// src/Storages/MergeTree/MergeTreeSelectProcessor.cpp:617
 if (reader_settings.use_query_condition_cache && task && prewhere_info
 && !task->readersChainCanSkipMarksBeforePrewhere(prewhere_filters_by_top_k_threshold)
 && !task->appliesMutationsBeforePrewhere()
 && !row_level_filter
 && task->getInfo().data_part_info->getDataPart())

Every one of those four extra conditions is a soundness condition:

!task->readersChainCanSkipMarksBeforePrewhere(...) — if a skip index upstream of PREWHERE could have filtered marks before PREWHERE saw them, attributing them to the PREWHERE predicate would be a lie.
!task->appliesMutationsBeforePrewhere() — on-the-fly mutations filter rows ahead of PREWHERE, for the same reason.
!row_level_filter — a row-level security filter is prepended before PREWHERE, but the cache key covers only the query’s PREWHERE hash. A mark hidden by a row policy must not be attributed to the PREWHERE predicate.

That last one is a beautiful example of a cache whose key doesn’t cover everything that influenced the result — the fix is to not write in that case, rather than to make the key bigger.

The whole flow

 text
 
 
 query with predicate Q
 │
 ▼
 hash(Q) + settings salt + [skip-index profile]
 │
 ├──► QueryConditionCache::read(table_uuid, part, hash)
 │ │
 │ └──► bitmap of "may match" granules
 │ │
 │ ▼
 │ surviving MarkRanges per part
 │ (parts with no surviving ranges are dropped entirely)
 │
 ▼
 index analysis (primary key, minmax, skip indexes)
 │
 ▼
 scan the surviving granules
 │
 ├── granules where the filter removed everything ──► cache.write(cleared bits)
 │
 └── rows ──► result

What this buys you, and what it costs

It buys you the elimination of repeated index analysis. The expensive part of “which granules can match” isn’t the bitmap lookup — it’s the KeyCondition evaluation and the exclusion search. On a warm cache, that work is replaced by a hash lookup and a bit scan.

It buys you the elimination of reading granules that match nothing. The index analysis can only prove a granule is empty using the index; a predicate on a non-key column can’t be resolved from the index at all. But once a scan has observed that a granule contains no matching rows, that fact is cached, and the next run doesn’t read it.

It costs you memory. One bit per granule per (table, part, predicate). The cache is a CacheBase LRU with a max_size_bytes.

It costs you correctness vigilance. Everything in this design is about not serving a verdict computed under different circumstances: a different predicate, a different set of skip indexes, a different time zone, a different row-level policy. The salt functions, the profiles, the derived time conditions, and the !row_level_filter guard are all the same idea applied four times.

It gives up on one direction. The cache can’t record “this granule matches everything,” so a highly selective predicate matching a few rows in every granule buys nothing. The cache is for predicates that are granule-level selective — which is most of them, since a granule is 10 MB of data.

Seeing it in action

 sql
 
 
SELECT
 event,
 value
FROM system.events
WHERE event IN ('QueryConditionCacheHits', 'QueryConditionCacheMisses');

A high, stable hit/miss ratio is the signature of a workload with repeated predicates over stable data. A ratio near zero means the predicates are always new — dashboards with per-request filters, for instance — and the cache is pure overhead.

The cache is also inspectable:

 sql
 
 
SELECT *
FROM system.query_condition_cache
LIMIT 10;

And to see it working, run the same query twice and compare the SelectedMarks and SelectedRanges counters in system.query_log:

 sql
 
 
SELECT
 query_id,
 ProfileEvents['SelectedMarks'] AS marks,
 ProfileEvents['SelectedRanges'] AS ranges,
 ProfileEvents['QueryConditionCacheHits'] AS qcc_hits
FROM system.query_log
WHERE query LIKE '%tenant_id = 42%'
ORDER BY event_time;

The second run should show dramatically fewer selected marks — and, if the predicate empties whole granules, the same query won’t even open the part.