RocksDB uses caches to improve read performance by storing frequently accessed data blocks in memory. The Cache API provides several implementations including LRU and HyperClockCache.
Cache Types
BlockCache vs RowCache
using BlockCache = Cache;
using RowCache = Cache;
Creating a Cache
LRUCacheOptions
struct LRUCacheOptions : public ShardedCacheOptions {
size_t capacity = 0;
int num_shard_bits = -1;
bool strict_capacity_limit = false;
double high_pri_pool_ratio = 0.5;
double low_pri_pool_ratio = 0.0;
bool use_adaptive_mutex = kDefaultToAdaptiveMutex;
CacheMetadataChargePolicy metadata_charge_policy =
kDefaultCacheMetadataChargePolicy;
};
Total capacity of the cache in bytes.
Cache is sharded into 2^num_shard_bits shards by hash of key. If negative, a good default is chosen automatically.
If true, Insert() fails when there is not enough capacity. If false, Insert() never fails.
Ratio of cache reserved for high-priority entries (0 to 1). 0.5 means non-high-priority entries use midpoint insertion.
MakeSharedCache
std::shared_ptr<Cache> MakeSharedCache() const;
Returns a shared pointer to the created cache.
HyperClockCacheOptions
struct HyperClockCacheOptions : public ShardedCacheOptions {
size_t capacity = 0;
size_t estimated_entry_charge = 0;
int num_shard_bits = -1;
bool strict_capacity_limit = false;
size_t min_avg_entry_charge = 450;
int eviction_effort_cap = 30;
};
Estimated average charge per entry. 0 uses a dynamic-growing table variant. Non-zero uses the most efficient fixed-size variant.
Controls CPU vs memory tradeoff under stress. Higher values allow slightly more memory overhead to keep eviction performant.
Legacy Cache Creation Functions
NewLRUCache
std::shared_ptr<Cache> NewLRUCache(
size_t capacity,
int num_shard_bits = -1,
bool strict_capacity_limit = false,
double high_pri_pool_ratio = 0.5,
std::shared_ptr<MemoryAllocator> memory_allocator = nullptr,
bool use_adaptive_mutex = kDefaultToAdaptiveMutex,
CacheMetadataChargePolicy metadata_charge_policy =
kDefaultCacheMetadataChargePolicy,
double low_pri_pool_ratio = 0.0
);
Secondary Cache
CompressedSecondaryCacheOptions
struct CompressedSecondaryCacheOptions : LRUCacheOptions {
CompressionType compression_type = CompressionType::kLZ4Compression;
CompressionOptions compression_opts;
bool enable_custom_split_merge = false;
CacheEntryRoleSet do_not_compress_roles = {CacheEntryRole::kFilterBlock};
};
Compression method for secondary cache entries.
Types of entries that should not be compressed. Filter blocks are non-compressible by default.
MakeSharedSecondaryCache
std::shared_ptr<SecondaryCache> MakeSharedSecondaryCache() const;
Tiered Cache
TieredCacheOptions
struct TieredCacheOptions {
ShardedCacheOptions* cache_opts = nullptr;
PrimaryCacheType cache_type = PrimaryCacheType::kCacheTypeLRU;
TieredAdmissionPolicy adm_policy = TieredAdmissionPolicy::kAdmPolicyAuto;
CompressedSecondaryCacheOptions comp_cache_opts;
size_t total_capacity = 0;
double compressed_secondary_ratio = 0.0;
std::shared_ptr<SecondaryCache> nvm_sec_cache;
};
Total memory budget divided between primary and compressed secondary cache.
compressed_secondary_ratio
Ratio of total capacity allocated to compressed secondary cache (0.0 to 1.0).
NewTieredCache
std::shared_ptr<Cache> NewTieredCache(
const TieredCacheOptions& cache_opts
);
UpdateTieredCache
Status UpdateTieredCache(
const std::shared_ptr<Cache>& cache,
int64_t total_capacity = -1,
double compressed_secondary_ratio = std::numeric_limits<double>::max(),
TieredAdmissionPolicy adm_policy = TieredAdmissionPolicy::kAdmPolicyMax
);
Cache Entry Roles
enum class CacheEntryRole {
kDataBlock,
kFilterBlock,
kFilterMetaBlock,
kIndexBlock,
kOtherBlock,
kWriteBuffer,
kCompressionDictionaryBuildingBuffer,
kFilterConstruction,
kBlockBasedTableReader,
kFileMetadata,
kBlobValue,
kBlobCache,
kMisc
};
enum CacheMetadataChargePolicy {
kDontChargeCacheMetadata,
kFullChargeCacheMetadata
};
kDontChargeCacheMetadata
CacheMetadataChargePolicy
Only entry data counts against capacity.
kFullChargeCacheMetadata
CacheMetadataChargePolicy
Both entry data and cache overhead count against capacity. Default.
Example: LRU Cache
#include "rocksdb/cache.h"
#include "rocksdb/table.h"
using namespace ROCKSDB_NAMESPACE;
// Create LRU cache
LRUCacheOptions cache_opts;
cache_opts.capacity = 512 * 1024 * 1024; // 512MB
cache_opts.num_shard_bits = 6; // 64 shards
cache_opts.strict_capacity_limit = false;
cache_opts.high_pri_pool_ratio = 0.5;
std::shared_ptr<Cache> cache = cache_opts.MakeSharedCache();
// Use cache in block-based table
BlockBasedTableOptions table_options;
table_options.block_cache = cache;
Options options;
options.table_factory.reset(NewBlockBasedTableFactory(table_options));
Example: HyperClockCache
#include "rocksdb/cache.h"
using namespace ROCKSDB_NAMESPACE;
// Create HyperClockCache (recommended over LRU)
HyperClockCacheOptions hcc_opts(512 * 1024 * 1024); // 512MB
std::shared_ptr<Cache> cache = hcc_opts.MakeSharedCache();
// Use in table options
BlockBasedTableOptions table_options;
table_options.block_cache = cache;
Example: Tiered Cache
#include "rocksdb/cache.h"
using namespace ROCKSDB_NAMESPACE;
// Configure tiered cache
LRUCacheOptions primary_opts;
TieredCacheOptions tier_opts;
tier_opts.cache_opts = &primary_opts;
tier_opts.cache_type = PrimaryCacheType::kCacheTypeLRU;
tier_opts.total_capacity = 1024 * 1024 * 1024; // 1GB total
tier_opts.compressed_secondary_ratio = 0.5; // 512MB compressed
std::shared_ptr<Cache> cache = NewTieredCache(tier_opts);
// Use in options
BlockBasedTableOptions table_options;
table_options.block_cache = cache;
Cache Statistics
Get cache statistics using:
// Get cache usage
uint64_t usage = cache->GetUsage();
uint64_t capacity = cache->GetCapacity();
// Get cache ID
std::string cache_id = cache->GetCacheId();
See Also