Cache

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;

BlockCache stores uncompressed data blocks from SST files. RowCache stores entire key-value pairs for faster point lookups.

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;
};

size_t

Total capacity of the cache in bytes.

int

Cache is sharded into 2^num_shard_bits shards by hash of key. If negative, a good default is chosen automatically.

bool

If true, Insert() fails when there is not enough capacity. If false, Insert() never fails.

double

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;

Creates an LRU cache with the configured options.

std::shared_ptr<Cache>

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;
};

size_t

Estimated average charge per entry. 0 uses a dynamic-growing table variant. Non-zero uses the most efficient fixed-size variant.

int

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
);

Deprecated wrapper function. Use LRUCacheOptions::MakeSharedCache() instead.

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};
};

CompressionType

Compression method for secondary cache entries.

CacheEntryRoleSet

Types of entries that should not be compressed. Filter blocks are non-compressible by default.

MakeSharedSecondaryCache

std::shared_ptr<SecondaryCache> MakeSharedSecondaryCache() const;

Creates a compressed secondary cache with the configured options.

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;
};

size_t

Total memory budget divided between primary and compressed secondary cache.

double

Ratio of total capacity allocated to compressed secondary cache (0.0 to 1.0).

NewTieredCache

std::shared_ptr<Cache> NewTieredCache(
  const TieredCacheOptions& cache_opts
);

Creates a 2-tier cache with primary uncompressed and secondary compressed tiers.

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
);

Dynamically updates tiered cache parameters.

Cache Entry Roles

enum class CacheEntryRole {
  kDataBlock,
  kFilterBlock,
  kFilterMetaBlock,
  kIndexBlock,
  kOtherBlock,
  kWriteBuffer,
  kCompressionDictionaryBuildingBuffer,
  kFilterConstruction,
  kBlockBasedTableReader,
  kFileMetadata,
  kBlobValue,
  kBlobCache,
  kMisc
};

Classifications of cache entries for monitoring and policy decisions.

Cache Metadata Charging

enum CacheMetadataChargePolicy {
  kDontChargeCacheMetadata,
  kFullChargeCacheMetadata
};

CacheMetadataChargePolicy

Only entry data counts against capacity.

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();

Database

Read & Write

Transactions

Storage

Utilities

Cache Types

BlockCache vs RowCache

Creating a Cache

LRUCacheOptions

MakeSharedCache

HyperClockCacheOptions

Legacy Cache Creation Functions

NewLRUCache

Secondary Cache

CompressedSecondaryCacheOptions

MakeSharedSecondaryCache

Tiered Cache

TieredCacheOptions

NewTieredCache

UpdateTieredCache

Cache Entry Roles

Cache Metadata Charging

Example: LRU Cache

Example: HyperClockCache

Example: Tiered Cache

Cache Statistics

See Also

​Cache Types

​BlockCache vs RowCache

​Creating a Cache

​LRUCacheOptions

​MakeSharedCache

​HyperClockCacheOptions

​Legacy Cache Creation Functions

​NewLRUCache

​Secondary Cache

​CompressedSecondaryCacheOptions

​MakeSharedSecondaryCache

​Tiered Cache

​TieredCacheOptions

​NewTieredCache

​UpdateTieredCache

​Cache Entry Roles

​Cache Metadata Charging

​Example: LRU Cache

​Example: HyperClockCache

​Example: Tiered Cache

​Cache Statistics

​See Also

Cache Types

BlockCache vs RowCache

Creating a Cache

LRUCacheOptions

MakeSharedCache

HyperClockCacheOptions

Legacy Cache Creation Functions

NewLRUCache

Secondary Cache

CompressedSecondaryCacheOptions

MakeSharedSecondaryCache

Tiered Cache

TieredCacheOptions

NewTieredCache

UpdateTieredCache

Cache Entry Roles

Cache Metadata Charging

Example: LRU Cache

Example: HyperClockCache

Example: Tiered Cache

Cache Statistics

See Also