Does Apache Phoenix automatically invalidate its client-side query result cache when an HBase region split occurs?

Automatic Invalidation Behavior

No, Apache Phoenix does not automatically invalidate its optional client-side query result cache when an HBase region split, flush, or compaction occurs. There is no built-in hook or event listener that triggers a cache purge based on HBase region server topology changes.

Technical Explanation

The client-side query result cache is keyed by the SQL statement and its bound parameters. Because the Phoenix client does not register as a listener for HBase region events, it remains unaware of backend structural changes. While a region split does not inherently change the data's visibility within HBase, the cached result set on the client remains static. This means the client will continue to serve the cached data until one of the following occurs:

• The entry is evicted by the Least Recently Used (LRU) algorithm.
• The entry exceeds its configured Time-to-Live (TTL).
• The cache is explicitly flushed via the PhoenixConnection API.

Consistency Strategies

To balance performance (cache hit rates) with data freshness (consistency), developers should implement the following practices based on their requirements:

Requirement	Recommended Approach	Trade-off
Strong Consistency	Disable client-side caching or use a very short TTL.	Increased latency and HBase load.
Eventual Consistency	Set a moderate TTL (e.g., minutes) and rely on LRU eviction.	Risk of stale reads during the TTL window.
Write-Through Freshness	Manually trigger a cache flush via the API following a significant write operation.	Increased application complexity.

Verification and Diagnostics

To verify if your current configuration is susceptible to stale reads during region splits, you can perform the following test in a staging environment:

1. Enable the query result cache and execute a query to populate it.
2. Manually trigger a region split using the HBase shell: split 'table_name', 'split_row_key'.
3. Execute the same query immediately; if the result is returned instantly without a server trip (observable via profiling or logs), the cache is persisting despite the split.

Diagnostic Note: To provide a more specific recommendation on TTL values, please specify if your workload is read-heavy with rare updates or involves frequent concurrent writes to the same row keys.