ReadOptions

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)

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.

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.

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.

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.

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.

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)

bool

default:"true"

If true, all data read from underlying storage will be verified against corresponding checksums.

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.

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.

uint64_t

default:"max"

Limits the maximum cumulative value size while reading through MultiGet. Once exceeded, remaining keys return with status Aborted.

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

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.

uint64_t

default:"0"

Threshold for keys that can be skipped before failing an iterator seek as incomplete. Default of 0 means never fail.

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.

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.

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.

bool

default:"false"

Enable total order seek regardless of index format (e.g., hash index). When calling Get(), also skips prefix bloom.

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.

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.

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.

bool

default:"false"

Enable enhancements for prefetching data during sequential reads.

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.

bool

default:"false"

If enabled, RocksDB prefetches data asynchronously for sequential reads.

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.

bool

default:"false"

Schedule deletion of obsolete files in background when PurgeObsoleteFile is called in CleanupIteratorState.

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.

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.

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.

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

// Create a snapshot
const Snapshot* snapshot = db->GetSnapshot();

ReadOptions options;
options.snapshot = snapshot;

std::string value;
db->Get(options, "key1", &value);

// Release snapshot when done
db->ReleaseSnapshot(snapshot);

ReadOptions options;
Slice lower_bound = "key000";
Slice upper_bound = "key999";
options.iterate_lower_bound = &lower_bound;
options.iterate_upper_bound = &upper_bound;

Iterator* it = db->NewIterator(options);
for (it->SeekToFirst(); it->Valid(); it->Next()) {
  // Process keys in [key000, key999)
  std::cout << it->key().ToString() << ": " << it->value().ToString() << std::endl;
}
delete it;

ReadOptions options;
options.fill_cache = false;  // Don't pollute cache
options.readahead_size = 2 * 1024 * 1024;  // 2MB readahead

Iterator* it = db->NewIterator(options);
for (it->SeekToFirst(); it->Valid(); it->Next()) {
  // Process all keys
}
delete it;

Database

Read & Write

Transactions

Storage

Utilities

Overview

Constructor

Common Options (Point Lookups & Scans)

Iterator-Specific Options

Examples

See Also

​Overview

​Constructor

​Common Options (Point Lookups & Scans)

​Iterator-Specific Options

​Examples

​See Also

Overview

Constructor

Common Options (Point Lookups & Scans)

Iterator-Specific Options

Examples

See Also