Condition Cache
Starting from Core 26.1.1, Condition Cache is a query acceleration mechanism in VeloDB Cloud designed for repeated condition queries. It caches the result of a specific filter condition on a given Segment as a compressed bit vector. When a subsequent query hits the cache, the result can be reused directly, avoiding repeated scans and filtering. This reduces CPU and IO overhead and shortens query latency.
In large-scale analytical scenarios, queries often contain repeated filter conditions, for example:
SELECT * FROM orders WHERE region = 'ASIA';
SELECT count(*) FROM orders WHERE region = 'ASIA';
Such queries repeatedly execute the same filter logic on the same data shards (Segments), causing redundant CPU and IO overhead. Condition Cache reuses filter results to reduce unnecessary scans and filtering, significantly lowering query latency.
Working principle
The core idea of Condition Cache is: the same filter condition on the same data shard produces the same result.
- VeloDB Cloud generates a 64-bit digest from "filter expression + Key Range" as the unique identifier for the cache.
- Each Segment can use this digest to look up an existing filter result in the cache.
- The cached result is stored as a compressed bit vector (
std::vector<bool>).
The semantics of the bit vector are as follows:
| Bit value | Meaning |
|---|---|
0 | The row range does not satisfy the condition and can be skipped |
1 | The range may contain rows that satisfy the condition and needs further scanning |
In this way, VeloDB Cloud can quickly eliminate invalid data blocks at a coarse granularity and apply precise filtering only when necessary.
Applicable scenarios
Recommended scenarios
Condition Cache is most effective in the following scenarios:
| Scenario | Description |
|---|---|
| Repeated conditions | The same or similar filter conditions are used frequently |
| Relatively stable data | Data inside a Segment is generally immutable (INSERT/Compaction generates new Segments, and old caches are naturally evicted) |
| High selectivity | The condition retains only a few rows after filtering, which maximizes scan reduction |
Scenarios where condition cache does not apply
Condition Cache does not take effect in the following scenarios:
- The scan has delete predicates. The storage reader disables condition-cache reuse for that rowset.
- A TopN Runtime Filter generated at runtime (not yet supported).
Configuration and management
Enable or disable Condition Cache
-
Purpose: Enable Condition Cache at the session level.
-
Command:
set enable_condition_cache = true; -
Description: This parameter controls whether the current session uses Condition Cache. Its Core 26.1.3 reference default is
true. Check the effective value withSHOW VARIABLES. When investigating repeated executions, temporarily disable the separate SQL Cache in the same session so it does not bypass the scan, then restore the original setting.
Memory management
The memory usage of Condition Cache follows these rules:
| Item | Description |
|---|---|
| Eviction policy | LRU (Least Recently Used), evicts the least recently used entries automatically once the capacity limit is exceeded |
| Capacity parameter | condition_cache_limit, in MB, Core 26.1.3 reference default 512 |
| Configuration owner | Managed by VeloDB Cloud |
| Natural expiration | After a Segment goes through Compaction, old cache entries are naturally evicted by LRU |
The capacity is a managed backend setting. Contact VeloDB Cloud support to review it. The reference default is not a measurement of the effective capacity in your warehouse.
Cache statistics and monitoring
VeloDB Cloud provides rich statistical metrics for observing the effectiveness of Condition Cache. You can use these metrics to evaluate cache benefits and hit rates.
Profile metrics
The following metrics are visible in the query execution plan (Profile):
| Metric name | Meaning |
|---|---|
ConditionCacheSegmentHit | Number of Segments that hit the cache |
ConditionCacheFilteredRows | Number of rows directly filtered out by the cache |
System metrics
These are backend metric names. Use exposed warehouse monitoring metrics where available, or ask VeloDB Cloud support to collect them:
| Metric name | Meaning |
|---|---|
condition_cache_search_count | Number of cache lookups |
condition_cache_hit_count | Number of cache hits |
Usage example
Typical scenario
Suppose you have the following query:
SELECT order_id, amount
FROM orders
WHERE region = 'ASIA' AND order_date >= '2023-01-01';
Execution flow:
- First execution: The eligible scan evaluates the filter, subject to other pruning and indexes. Condition Cache stores the result in the LRU cache.
- Subsequent identical queries: The cache is used directly to skip most invalid row ranges, scanning only the parts that may satisfy the condition.
When multiple queries share the same filter condition (for example, region = 'ASIA' AND order_date >= '2023-01-01'), they can also reuse Condition Cache among each other, reducing overall overhead.
Notes
- The cache is not persisted: Condition Cache is cleared after VeloDB Cloud restarts.
- Delete predicates can disable reuse: The storage reader disables the condition-cache digest when delete-predicate columns are present. This is not a statement that every DELETE permanently disables the feature.
FAQ
Q1: What is the difference between Condition Cache and Query Cache?
Condition Cache caches "the hit status of a filter condition on a Segment" (a bit vector). Its granularity is finer and it can be reused across different queries. It is an optimization mechanism at the query execution layer.
Q2: Why is the query not faster after enabling Condition Cache?
You can investigate from the following angles:
- The scan has delete predicates or depends on a TopN Runtime Filter, so the cache does not take effect.
- Data is written frequently. After Compaction, old Segments are replaced by new ones, and the cache is evicted.
- The condition has low selectivity, and many rows are still retained after filtering, so the benefit is limited.
- Use
condition_cache_hit_count/condition_cache_search_countto check whether the hit rate is low.
Q3: How can I confirm whether a query hits Condition Cache?
Check the ConditionCacheSegmentHit and ConditionCacheFilteredRows metrics in the Profile. ConditionCacheSegmentHit > 0 shows a hit. ConditionCacheFilteredRows > 0 shows that cached information skipped rows. A hit alone does not prove a latency improvement.
Q4: Do I need to restart after adjusting condition_cache_limit?
VeloDB Cloud manages backend configuration and restarts. Contact VeloDB Cloud support to review a capacity change and its operational impact.
Summary
Condition Cache is an optimization mechanism in VeloDB Cloud for repeated condition queries. Its advantages are:
- It avoids redundant computation and reduces CPU/IO consumption.
- Once enabled, cache lookups and eviction occur automatically for eligible scans.
- Memory use is bounded by the managed capacity. A hit is useful only when it skips enough work to offset cache overhead.
By making good use of Condition Cache, you can achieve faster response times in high-frequency OLAP query scenarios.