Skip to main content
VeloDB Cloud 26.x is based on Apache Doris 4.x. See Version Mapping.

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.

  1. VeloDB Cloud generates a 64-bit digest from "filter expression + Key Range" as the unique identifier for the cache.
  2. Each Segment can use this digest to look up an existing filter result in the cache.
  3. The cached result is stored as a compressed bit vector (std::vector<bool>).

The semantics of the bit vector are as follows:

Bit valueMeaning
0The row range does not satisfy the condition and can be skipped
1The 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​

Condition Cache is most effective in the following scenarios:

ScenarioDescription
Repeated conditionsThe same or similar filter conditions are used frequently
Relatively stable dataData inside a Segment is generally immutable (INSERT/Compaction generates new Segments, and old caches are naturally evicted)
High selectivityThe 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 with SHOW 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:

ItemDescription
Eviction policyLRU (Least Recently Used), evicts the least recently used entries automatically once the capacity limit is exceeded
Capacity parametercondition_cache_limit, in MB, Core 26.1.3 reference default 512
Configuration ownerManaged by VeloDB Cloud
Natural expirationAfter 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 nameMeaning
ConditionCacheSegmentHitNumber of Segments that hit the cache
ConditionCacheFilteredRowsNumber 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 nameMeaning
condition_cache_search_countNumber of cache lookups
condition_cache_hit_countNumber 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:

  1. First execution: The eligible scan evaluates the filter, subject to other pruning and indexes. Condition Cache stores the result in the LRU cache.
  2. 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_count to 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.