Class ReadOptions
- Namespace
- RocksDbNet
- Assembly
- RocksDb.Net.dll
Options that control read operations.
Maps to rocksdb_readoptions_t.
public sealed class ReadOptions : RocksDbHandle, IDisposable- Inheritance
-
ReadOptions
- Implements
- Inherited Members
Constructors
ReadOptions()
public ReadOptions()Properties
AdaptiveReadahead
If true, readahead size grows automatically as sequential reading continues, instead of staying at ReadaheadSize.
public bool AdaptiveReadahead { get; set; }Property Value
AllowUnpreparedValue
If true, an iterator may return an entry whose value has not been loaded yet, which avoids reading values the caller ends up skipping.
public bool AllowUnpreparedValue { get; set; }Property Value
Remarks
Applies to exactly two cases: large values held in blob files, and iterators spanning several column families. Everywhere else it has no effect at all, so setting it on an ordinary single-family iterator over non-blob data changes nothing.
AsyncIo
If true, enable asynchronous I/O during iteration.
public bool AsyncIo { get; set; }Property Value
AutoPrefixMode
If true, RocksDb infers from the iteration bounds whether a prefix seek is safe, allowing prefix optimisations without PrefixSameAsStart.
public bool AutoPrefixMode { get; set; }Property Value
AutoReadaheadSize
If true, RocksDb sizes iterator readahead itself based on the bounds of the scan.
public bool AutoReadaheadSize { get; set; }Property Value
AutoRefreshIteratorWithSnapshot
If true, a long-running iterator periodically releases obsolete memory and file resources while still showing the same point-in-time view. Experimental, and does nothing unless a snapshot is set.
public bool AutoRefreshIteratorWithSnapshot { get; set; }Property Value
Remarks
It does not let the iterator see later writes. The opposite: it preserves the snapshot view and refreshes only the underlying resources, so a long-lived iterator stops pinning files and memory it no longer needs. It requires SetSnapshot(Snapshot?) to have been given a snapshot, and only takes effect while the iterator keeps making progress.
Marked experimental by RocksDb, which expects to default it to true eventually. It has no effect on a transaction database using the write-prepared or write-unprepared policies, which are currently incompatible.
BackgroundPurgeOnIteratorCleanup
Whether obsolete files are deleted on a background thread when an iterator is cleaned up, rather than on the thread disposing it. Default is false.
public bool BackgroundPurgeOnIteratorCleanup { get; set; }Property Value
Remarks
Worth setting when iterators are disposed on threads that should not block on file deletion. The database-level AvoidUnnecessaryBlockingIo overrides this one when enabled, so setting that makes this redundant.
Deadline
public DateTimeOffset? Deadline { get; set; }Property Value
Remarks
This is an absolute time, not a duration. RocksDb takes microseconds since the Unix epoch, so the natural mistake is to set it to how long the read may take and get a deadline in 1970, which has already passed. Use SetDeadlineAfter(TimeSpan) to express it as a duration from now.
Best effort. A read can overrun the deadline when the file system does not support deadlines, and a batch read checks periodically rather than per key.
FillCache
If true, the returned data block is added to the block cache.
public bool FillCache { get; set; }Property Value
HasMergeOperandCountThreshold
Whether a merge operand count threshold has been set.
public bool HasMergeOperandCountThreshold { get; }Property Value
HasTableFilter
Whether a table filter is installed on these options.
public bool HasTableFilter { get; }Property Value
IgnoreRangeDeletions
If true, range deletion tombstones are ignored during reads.
public bool IgnoreRangeDeletions { get; set; }Property Value
IoActivity
Labels the I/O this read performs. Leave this alone unless you have a reason to override how RocksDb accounts for the operation.
public IoActivity IoActivity { get; set; }Property Value
IoTimeout
public TimeSpan IoTimeout { get; set; }Property Value
Remarks
A duration, unlike Deadline, and it applies per file read rather than to the operation as a whole. One get or seek can issue several reads, and each may take this long.
MaxSkippableInternalKeys
How many internal keys an iterator seek may skip before failing as incomplete. Zero, the default, means never fail.
public ulong MaxSkippableInternalKeys { get; set; }Property Value
Remarks
The defence against a pathological seek. A large deleted range leaves tombstones behind until it is compacted away, and a seek into it walks every one, so a single seek can turn into an unbounded scan. Setting a limit makes that fail fast instead.
MergeOperandCountThreshold
Number of merge operands above which RocksDb reports the read as needing
compaction. Reading this when
HasMergeOperandCountThreshold is false returns the
native default rather than throwing.
public ulong MergeOperandCountThreshold { get; set; }Property Value
OptimizeMultiGetForIo
If true, a multi-get reorders and batches its I/O for throughput rather than issuing reads in key order.
public bool OptimizeMultiGetForIo { get; set; }Property Value
PinData
If true, the key and value memory an iterator hands out stays valid until the iterator moves or is disposed, rather than only until the next call.
public bool PinData { get; set; }Property Value
Remarks
Nothing to do with PinnableSlice, which pins on its own without
this. This governs iterators, and the cost of it is that the blocks
behind those pointers cannot be evicted while they are held.
PrefixSameAsStart
If true, all returned keys must share the same prefix as the seek key.
public bool PrefixSameAsStart { get; set; }Property Value
RateLimiterPriority
Priority this read is given by the rate limiter, if one is configured.
public RateLimiterPriority RateLimiterPriority { get; set; }Property Value
ReadTier
Which tiers of storage the read is allowed to reach into. A read that cannot be answered from the permitted tiers returns no value rather than falling through to a slower one.
public ReadTier ReadTier { get; set; }Property Value
ReadaheadSize
Readahead size in bytes for iteration and scans. Zero leaves RocksDb's automatic readahead in charge.
public ulong ReadaheadSize { get; set; }Property Value
Remarks
This applies to iterators, not to compaction. Compaction readahead is CompactionReadaheadSize. By default RocksDb already ramps readahead up on its own once it notices more than two reads of a table file, starting at 8 KB and doubling to 256 KB, so setting this only helps when scans are consistently larger than that. Values above 2 MB mainly pay off for forward iteration on spinning disks.
RequestId
An opaque identifier RocksDb attaches to this read's tracing and logging,
for correlating a read with the rest of your system. null when none
is set.
public string? RequestId { get; set; }Property Value
Remarks
RocksDb copies the string, so nothing needs to stay alive on this side.
Assigning null is the same as calling ClearRequestId().
TableIndexFactoryName
Name of the user-defined index factory in use, or null when none is
configured.
public string? TableIndexFactoryName { get; }Property Value
Tailing
Specify to create a non-snapshot-based tailing iterator.
public bool Tailing { get; set; }Property Value
TotalOrderSeek
If true, bypass prefix-based iteration and use total order (sorted) iteration.
public bool TotalOrderSeek { get; set; }Property Value
ValueSizeSoftLimit
Soft limit in bytes on the cumulative value size a single multi-get buffers. The default is MaxValue, which is the effective "no limit".
public ulong ValueSizeSoftLimit { get; set; }Property Value
Remarks
Zero is not "no limit"; it is the smallest possible limit. The read always makes progress, so at least one key is returned even when its value alone exceeds the limit, and every key after the limit is crossed comes back with an aborted status for the caller to retry. Setting zero therefore reduces a multi-get to roughly one key per call.
VerifyChecksums
If true, all data read from underlying storage will be verified against checksums.
public bool VerifyChecksums { get; set; }Property Value
Methods
ClearMergeOperandCountThreshold()
Unsets the merge operand count threshold.
public ReadOptions ClearMergeOperandCountThreshold()Returns
ClearRequestId()
Removes any request identifier set on these options.
public ReadOptions ClearRequestId()Returns
ClearTableFilter()
Removes any table filter from these options.
public ReadOptions ClearTableFilter()Returns
ClearTableIndexFactory()
Removes any user-defined index factory from these options.
public ReadOptions ClearTableIndexFactory()Returns
DisposeHandle()
Releases the native handle. Called during disposal.
protected override void DisposeHandle()Remarks
Protected rather than public: it destroys the native object without marking this instance disposed or clearing the handle, so calling it from outside and then disposing normally would free the same pointer twice. It was the most Dispose-looking member on the type. Callers want Dispose().
DisposeUnmanagedResources()
Releases unmanaged resources used by the current instance.
protected override void DisposeUnmanagedResources()Remarks
Protected for the same reason as DisposeHandle().
SetDeadlineAfter(TimeSpan)
Sets Deadline to timeout from now.
public ReadOptions SetDeadlineAfter(TimeSpan timeout)Parameters
timeoutTimeSpanHow long the read may take. Zero or less clears the deadline rather than setting one in the past, because a deadline that has already passed is almost never what a caller means.
Returns
Remarks
The form callers actually want. It exists because Deadline is absolute and converting a timeout into an epoch offset by hand is easy to get wrong.
SetIterateLowerBound(ReadOnlySpan<byte>)
Sets the lower bound for iteration; the iterator will not return keys < this key.
public ReadOptions SetIterateLowerBound(ReadOnlySpan<byte> key)Parameters
keyReadOnlySpan<byte>
Returns
Remarks
The key is copied into unmanaged memory owned by this ReadOptions
instance, so the caller does not need to keep key alive or
pinned. The copy is released when the bound is replaced and when this instance
is disposed. Passing an empty span clears the bound.
SetIterateUpperBound(ReadOnlySpan<byte>)
Sets the upper bound for iteration; the iterator will not return keys >= this key.
public ReadOptions SetIterateUpperBound(ReadOnlySpan<byte> key)Parameters
keyReadOnlySpan<byte>
Returns
Remarks
The key is copied into unmanaged memory owned by this ReadOptions
instance, so the caller does not need to keep key alive or
pinned. The copy is released when the bound is replaced and when this instance
is disposed. Passing an empty span clears the bound.
SetSnapshot(Snapshot?)
Attaches a snapshot so reads reflect a consistent point-in-time view.
public ReadOptions SetSnapshot(Snapshot? snapshot)Parameters
snapshotSnapshot
Returns
SetTableFilter(Func<TablePropertiesView, bool>)
Installs a predicate that decides which SST files a read may look at.
Returning false skips the file entirely.
public ReadOptions SetTableFilter(Func<TablePropertiesView, bool> filter)Parameters
filterFunc<TablePropertiesView, bool>Called once per candidate SST file, on the thread performing the read, and concurrently when several reads are in flight, so it must be thread-safe and must not throw. An exception is caught and reported through UnhandledException, and the file is then included, since excluding it would silently hide data.
Returns
Remarks
The TablePropertiesView passed in is only valid for the duration of the call. Use ToSnapshot() to keep any of it.
SetTableIndexFactoryFromString(string)
Selects a user-defined index factory by its RocksDb configuration string.
public ReadOptions SetTableIndexFactoryFromString(string value)Parameters
valuestring
Returns
Exceptions
- RocksDbException
The string does not name a known factory.