Skip to main content

​
Overview

The ReadOptions structure provides fine-grained control over read operations including point lookups (Get, MultiGet) and scans (iterators). It allows you to configure snapshots, caching behavior, iteration bounds, and performance optimizations.

​
Constructor

ReadOptions()
ReadOptions(bool verify_checksums, bool fill_cache)
explicit ReadOptions(Env::IOActivity io_activity)

​
Common Options (Point Lookups & Scans)

​
snapshot
const Snapshot*
default:"nullptr"
Read as of the supplied snapshot (which must belong to the DB and not have been released). If nullptr, uses an implicit snapshot of the state at the beginning of the read operation.
​
timestamp
const Slice*
default:"nullptr"
Timestamp of operation. Read returns the latest data visible to the specified timestamp. For iterators, iter_start_ts is the lower bound (older) and timestamp serves as the upper bound.
​
iter_start_ts
const Slice*
default:"nullptr"
Lower bound timestamp for iterator. Versions of the same record that fall in the timestamp range will be returned. If nullptr, only the most recent version visible to timestamp is returned.
​
deadline
std::chrono::microseconds
default:"0"
Deadline for completing an API call (Get/MultiGet/Seek/Next) in microseconds since epoch (e.g., env->NowMicros() + timeout). Best efforts - the call may exceed the deadline if there is I/O involved.
​
io_timeout
std::chrono::microseconds
default:"0"
Timeout for each individual file read request. Unlike deadline, each read in a MultiGet/Scan can last up to io_timeout microseconds.
​
read_tier
ReadTier
default:"kReadAllTier"
Specify which cache tier to read from:
  • kReadAllTier: Read from memtable, block cache, OS cache, or storage
  • kBlockCacheTier: Read only from memtable or block cache
  • kPersistedTier: Read only persisted data (skips memtable when WAL disabled)
  • kMemtableTier: Read only from memtable (for memtable-only iterators)
​
verify_checksums
bool
default:"true"
If true, all data read from underlying storage will be verified against corresponding checksums.
​
fill_cache
bool
default:"true"
Should data blocks read for this operation be placed in block cache? Set to false for bulk scans to avoid evicting cached data.
​
rate_limiter_priority
Env::IOPriority
default:"Env::IO_TOTAL"
Charge the rate limiter at the specified priority. Special value Env::IO_TOTAL disables rate limiting. The bytes charged may not exactly match file read bytes.
​
value_size_soft_limit
uint64_t
default:"max"
Limits the maximum cumulative value size while reading through MultiGet. Once exceeded, remaining keys return with status Aborted.
​
merge_operand_count_threshold
std::optional<size_t>
default:"nullopt"
When the number of merge operands applied exceeds this threshold during a query, returns OK with subcode kMergeOperandThresholdExceeded. Currently only applies to point lookups.

​
Iterator-Specific Options

​
readahead_size
size_t
default:"0"
RocksDB auto-readahead starts at 8KB and doubles up to 256KB. Use this option for large range scans that need more aggressive readahead. Values > 2MB typically improve performance on spinning disks.
​
max_skippable_internal_keys
uint64_t
default:"0"
Threshold for keys that can be skipped before failing an iterator seek as incomplete. Default of 0 means never fail.
​
iterate_lower_bound
const Slice*
default:"nullptr"
Smallest key at which the backward iterator can return an entry (inclusive). Once passed, Valid() returns false. Must have the same prefix as seek target if prefix_extractor is set.
​
iterate_upper_bound
const Slice*
default:"nullptr"
Extent up to which the forward iterator can return entries (exclusive). Once reached, Valid() returns false. If not nullptr, SeekToLast() positions at the first key smaller than this bound.
​
tailing
bool
default:"false"
Create a tailing iterator with a view of the complete database, optimized for sequential reads. Can read newly added data after iterator creation.
​
total_order_seek
bool
default:"false"
Enable total order seek regardless of index format (e.g., hash index). When calling Get(), also skips prefix bloom.
​
auto_prefix_mode
bool
default:"false"
When true, uses total_order_seek = true by default, and RocksDB selectively enables prefix seek mode when it won’t generate different results.
​
prefix_same_as_start
bool
default:"false"
Enforce that the iterator only iterates over the same prefix as the seek key. Enables prefix filtering optimizations for both Seek and SeekForPrev.
​
pin_data
bool
default:"false"
Keep blocks loaded by the iterator pinned in memory as long as the iterator is not deleted. When enabled with use_delta_encoding = false, the property rocksdb.iterator.is-key-pinned returns 1.
​
adaptive_readahead
bool
default:"false"
Enable enhancements for prefetching data during sequential reads.
​
auto_readahead_size
bool
default:"true"
Auto-tune the readahead size during scans based on block cache data and iteration bounds. Requires block cache enabled and either iterate_upper_bound != nullptr or prefix_same_as_start == true.
​
async_io
bool
default:"false"
If enabled, RocksDB prefetches data asynchronously for sequential reads.
​
optimize_multiget_for_io
bool
default:"true"
When async_io is set, controls whether to read SST files in multiple levels asynchronously. Helps reduce MultiGet latency by maximizing parallel SST reads.
​
background_purge_on_iterator_cleanup
bool
default:"false"
Schedule deletion of obsolete files in background when PurgeObsoleteFile is called in CleanupIteratorState.
​
ignore_range_deletions
bool
default:"false"
DEPRECATED: Skip range tombstone handling in key lookup paths. Only use if the DB never calls DeleteRange(). Setting to true with DeleteRange in use may serve stale keys.
​
table_filter
std::function<bool(const TableProperties&)>
default:"empty"
Callback to determine whether relevant keys exist in a table based on table properties. If returns false, the table is not scanned. Only affects iterators.
​
allow_unprepared_value
bool
default:"false"
Iterator may defer loading/preparing values when moving to a different entry. Call PrepareValue() before accessing values. Only applies to BlobDB large values and multi-CF iterators.
​
auto_refresh_iterator_with_snapshot
bool
default:"false"
EXPERIMENTAL: Long-running iterators release resources as they make progress. Requires non-nullptr snapshot. Not recommended with user-defined timestamps.

​
Examples

ReadOptions options;
options.verify_checksums = true;
options.fill_cache = true;

std::string value;
Status s = db->Get(options, "key1", &value);
assert(s.ok());

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us