[KV] Support partitioned metadata with HyperClockCache #4607

Search before asking

• I searched the existing issues and pull requests. This extends [KV] Add RocksDB Block Cache Configuration Options for Index and Filter Blocks #2393 / Add RocksDB block cache configuration options for index and filter blocks #2394 and builds on the shared AutoHCC support in [kv] Use HyperClockCache for the shared RocksDB block cache #4611.

Motivation

Unpartitioned RocksDB index/filter blocks can be large. When metadata competes with data for limited block cache capacity, misses repeatedly incur reads, checksum verification, decompression, and parsing. Partitioned metadata reduces the cost of a miss. HyperClockCache (HCC) reduces cache synchronization overhead and supports entry priorities and pinning.

Solution

Use AutoHCC for shared and per-DB block caches and expose partitioned indexes/full filters. Follow the RocksDB 11.8.1 cache guidance while preserving every existing Fluss option default.

Configuration contract

Add kv.rocksdb.block.partitioned-index-filters as a boolean with a fixed default of false. Enable partitioning only when explicitly set to true, independently of kv.rocksdb.block.cache-index-and-filter-blocks.

• Enable IndexType.kTwoLevelIndexSearch when partitioning is enabled.
• Enable partitioned full filters only when Bloom filters are enabled. Do not enable Bloom filters implicitly.
• Reject block-based Bloom filter mode and non-positive metadata block size when incompatible with partitioning, before allocating DB resources.
• Keep metadata caching, metadata priority, top-level pinning, and L0 pinning defaults at false. Keep metadata block size and Bloom settings unchanged.
• Preserve explicit priority and pinning settings. Warn about L0 pinning with non-LEVEL compaction.

HCC honors entry priorities through eviction scoring and access history. It does not reserve a fixed fraction of capacity for high-priority metadata. High priority is not pinning and does not prevent eviction; long scans can dilute infrequently accessed metadata.

Cache creation and ownership

• Preserve the shared AutoHCC implementation from [kv] Use HyperClockCache for the shared RocksDB block cache #4611.
• Use HyperClockCache(capacity, 0, -1, false) for per-DB block caches: automatic entry-table sizing and shard selection, existing capacity and non-strict capacity policy.
• Keep the WriteBufferManager accounting cache unchanged.
• Keep shared-cache ownership in KvManager. Closing one DB must not close its shared cache.
• Use the current JNI dependency and existing Cache abstraction.

Compatibility and memory

These are initialization settings, not live reconfiguration. Existing defaults remain unchanged. Partitioning defaults to false, including when metadata caching is enabled. Per-DB cache eviction changes to HCC.

Existing SSTs retain their format until rewritten. Ordinary and partitioned SSTs must coexist and remain readable after enabling or disabling partitioning, including through iterator reads and checkpoint restoration. Do not trigger manual compaction or migration automatically.

Partition blocks use block cache even when metadata caching is disabled; in that case the switch controls top-level placement. Budget for the metadata working set. Pinned blocks reduce reclaimable space and can exceed nominal capacity under the non-strict policy. Cache capacity does not bound total RocksDB or process memory.

Validation

• Cover partitioning default resolution and explicit overrides, existing priority/pinning defaults and explicit settings, incompatible filter mode, positive partition size, and Bloom-disabled index partitioning.
• Verify actual SST partition properties, mixed-format Get and iterator reads, reopening, and checkpoint restoration with partitioning disabled.
• Exercise shared and per-DB HCC paths and shared-cache lifetime.
• Run controlled performance experiments with fixed data, request distribution, memory budget, and warm-up. Include metadata-constrained and metadata-fits-in-memory workloads, range scans, and pinned-memory pressure. Measure interval Get distributions, metadata/data misses, bytes read, checksum/decompression CPU, cache occupancy, and pinned usage. Avoid latency thresholds in unit tests.

Anything else?

Implementation: #4612.

References:

• RocksDB HCC guidance
• Partitioned index/filter guidance
• HCC eviction algorithm

Willingness to contribute

• I'm willing to submit a PR!