Struct ReadOptions

Source

pub struct ReadOptions { /* private fields */ }

Implementations§

Source §

impl ReadOptions

Source

pub fn fill_cache(&mut self, v: bool)

Specify whether the “data block”/“index block”/“filter block” read for this iteration should be cached in memory? Callers may wish to set this field to false for bulk scans.

Default: true

Source

pub fn set_snapshot<D: DBAccess>( &mut self, snapshot: &SnapshotWithThreadMode<'_, D>, )

Sets the snapshot which should be used for the read. The snapshot must belong to the DB that is being read and must not have been released.

Source

pub fn set_iterate_lower_bound<K: Into<Vec<u8>>>(&mut self, key: K)

Sets the lower bound for an iterator.

Source

pub fn set_iterate_upper_bound<K: Into<Vec<u8>>>(&mut self, key: K)

Sets the upper bound for an iterator. The upper bound itself is not included on the iteration result.

Source

pub fn set_iterate_range(&mut self, range: impl IterateBounds)

Sets lower and upper bounds based on the provided range. This is similar to setting lower and upper bounds separately except that it also allows either bound to be reset.

The argument can be a regular Rust range, e.g. lower..upper. However, since RocksDB upper bound is always excluded (i.e. range can never be fully closed) inclusive ranges (lower..=upper and ..=upper) are not supported. For example:

let mut options = rust_rocksdb::ReadOptions::default();
options.set_iterate_range("xy".as_bytes().."xz".as_bytes());

In addition, crate::PrefixRange can be used to specify a range of keys with a given prefix. In particular, the above example is equivalent to:

let mut options = rust_rocksdb::ReadOptions::default();
options.set_iterate_range(rust_rocksdb::PrefixRange("xy".as_bytes()));

Note that setting range using this method is separate to using prefix iterators. Prefix iterators use prefix extractor configured for a column family. Setting bounds via crate::PrefixRange is more akin to using manual prefix.

Using this method clears any previously set bounds. In other words, the bounds can be reset by setting the range to .. as in:

let mut options = rust_rocksdb::ReadOptions::default();
options.set_iterate_range(..);

Source

pub fn set_read_tier(&mut self, tier: ReadTier)

Specify if this read request should process data that ALREADY resides on a particular cache. If the required data is not found at the specified cache, then Status::Incomplete is returned.

Default: ::All

Source

pub fn get_read_tier(&self) -> Option<ReadTier>

The tier set by Self::set_read_tier.

ReadTier covers every tier RocksDB defines today, so None only shows up if a future release adds one.

Source

pub fn set_prefix_same_as_start(&mut self, v: bool)

Enforce that the iterator only iterates over the same prefix as the seek. This option is effective only for prefix seeks, i.e. prefix_extractor is non-null for the column family and total_order_seek is false. Unlike iterate_upper_bound, prefix_same_as_start only works within a prefix but in both directions.

Default: false

Source

pub fn set_total_order_seek(&mut self, v: bool)

Enable a total order seek regardless of index format (e.g. hash index) used in the table. Some table format (e.g. plain table) may not support this option.

If true when calling Get(), we also skip prefix bloom when reading from block based table. It provides a way to read existing data after changing implementation of prefix extractor.

Source

pub fn set_max_skippable_internal_keys(&mut self, num: u64)

Sets a threshold for the number of keys that can be skipped before failing an iterator seek as incomplete. The default value of 0 should be used to never fail a request as incomplete, even on skipping too many keys.

Default: 0

Source

pub fn set_background_purge_on_iterator_cleanup(&mut self, v: bool)

If true, when PurgeObsoleteFile is called in CleanupIteratorState, we schedule a background job in the flush job queue and delete obsolete files in background.

Default: false

Source

pub fn set_ignore_range_deletions(&mut self, v: bool)

👎Deprecated:

deprecated in RocksDB 10.2.1: no performance impact if DeleteRange is not used

If true, keys deleted using the DeleteRange() API will be visible to readers until they are naturally deleted during compaction.

Default: false

Source

pub fn get_ignore_range_deletions(&self) -> bool

Returns the value of the ignore_range_deletions option.

Deprecated in RocksDB 10.2.1 along with its setter: there is no performance impact if DeleteRange is not used.

Source

pub fn set_verify_checksums(&mut self, v: bool)

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

Default: true

Source

pub fn set_readahead_size(&mut self, v: usize)

If non-zero, an iterator will create a new table reader which performs reads of the given size. Using a large size (> 2MB) can improve the performance of forward iteration on spinning disks. Default: 0

use rust_rocksdb::{ReadOptions};

let mut opts = ReadOptions::default();
opts.set_readahead_size(4_194_304); // 4mb

Source

pub fn set_auto_readahead_size(&mut self, v: bool)

If auto_readahead_size is set to true, it will auto tune the readahead_size during scans internally. For this feature to be enabled, iterate_upper_bound must also be specified.

NOTE: - Recommended for forward Scans only. - If there is a backward scans, this option will be disabled internally and won’t be enabled again if the forward scan is issued again.

Default: true

Source

pub fn set_tailing(&mut self, v: bool)

If true, create a tailing iterator. Note that tailing iterators only support moving in the forward direction. Iterating in reverse or seek_to_last are not supported.

Source

pub fn set_pin_data(&mut self, v: bool)

Specifies the value of “pin_data”. If true, it keeps the blocks loaded by the iterator pinned in memory as long as the iterator is not deleted, If used when reading from tables created with BlockBasedTableOptions::use_delta_encoding = false, Iterator’s property “rocksdb.iterator.is-key-pinned” is guaranteed to return 1.

Default: false

Source

pub fn set_async_io(&mut self, v: bool)

Asynchronously prefetch some data.

Used for sequential reads and internal automatic prefetching.

Default: false

Source

pub fn set_optimize_multiget_for_io(&mut self, v: bool)

Selects the multi-level vs single-level parallel MultiGet path when the library is built with USE_COROUTINES (the coroutines cargo feature) and set_async_io(true) has been called.

When true (the C++ default), MultiGet parallelises reads across LSM levels, giving the lowest latency at the cost of higher CPU and coroutine scheduling overhead. When false, parallelism is limited to within a single level, trading some latency for CPU savings.

Has no effect outside of USE_COROUTINES builds with async_io=true. With either condition unmet, both code paths in db/version_set.cc fall through to the synchronous per-file lookup regardless of this flag’s value.

See the RocksDB “Asynchronous IO in RocksDB” blog post for the qualitative tradeoff: optimize_multiget_for_io=true (multi-level) is the lowest-latency configuration but costs the most CPU; optimize_multiget_for_io=false (single-level, with async_io still on) retains most of the latency win at meaningfully lower CPU.

Default: true

Source

pub fn get_optimize_multiget_for_io(&self) -> bool

Returns the current value of Self::set_optimize_multiget_for_io.

Provided primarily for tests that want to confirm the setter is wired through to the underlying C++ ReadOptions. Reads through to the C API getter without exposing the underlying c_uchar representation.

Source

pub fn set_deadline(&mut self, microseconds: u64)

Deadline for completing an API call (Get/MultiGet/Seek/Next for now) in microseconds. It should be set to microseconds since epoch, i.e, gettimeofday or equivalent plus allowed duration in microseconds. This is best effort. The call may exceed the deadline if there is IO involved and the file system doesn’t support deadlines, or due to checking for deadline periodically rather than for every key if processing a batch

Source

pub fn set_io_timeout(&mut self, microseconds: u64)

A timeout in microseconds to be passed to the underlying FileSystem for reads. As opposed to deadline, this determines the timeout for each individual file read request. If a MultiGet/Get/Seek/Next etc call results in multiple reads, each read can last up to io_timeout us.

Source

pub fn set_timestamp<S: Into<Vec<u8>>>(&mut self, ts: S)

Timestamp of operation. Read should return the latest data visible to the specified timestamp. All timestamps of the same database must be of the same length and format. The user is responsible for providing a customized compare function via Comparator to order <key, timestamp> tuples. For iterator, iter_start_ts is the lower bound (older) and timestamp serves as the upper bound. Versions of the same record that fall in the timestamp range will be returned. If iter_start_ts is nullptr, only the most recent version visible to timestamp is returned. The user-specified timestamp feature is still under active development, and the API is subject to change.

Source

pub fn set_iter_start_ts<S: Into<Vec<u8>>>(&mut self, ts: S)

See set_timestamp

Source

pub fn set_adaptive_readahead(&mut self, val: bool)

For iterators, RocksDB does auto-readahead on noticing more than two sequential reads for a table file if user doesn’t provide readahead_size. The readahead starts at 8KB and doubles on every additional read upto max_auto_readahead_size only when reads are sequential. However at each level, if iterator moves over next file, readahead_size starts again from 8KB.

By enabling this option, RocksDB will do some enhancements for prefetching the data.

Source

pub fn get_adaptive_readahead(&self) -> bool

Returns the value of the adaptive_readahead option.

Source

pub fn set_allow_unprepared_value(&mut self, val: bool)

When set, the iterator may defer loading and/or preparing the value when moving to a different entry (i.e. during SeekToFirst/SeekToLast/Seek/ SeekForPrev/Next/Prev operations). This can be used to save on I/O and/or CPU when the values associated with certain keys may not be used by the application. See also IteratorBase::PrepareValue().

Note: this option currently only applies to 1) large values stored in blob files using BlobDB and 2) multi-column-family iterators (CoalescingIterator and AttributeGroupIterator). Otherwise, it has no effect.

Default: false

Source

pub fn get_allow_unprepared_value(&self) -> bool

Returns the value of the allow_unprepared_value option.

Source

pub fn set_auto_prefix_mode(&mut self, val: bool)

When true, by default use total_order_seek = true, and RocksDB can selectively enable prefix seek mode if won’t generate a different result from total_order_seek, based on seek key, and iterator upper bound. BUG: Using Comparator::IsSameLengthImmediateSuccessor and SliceTransform::FullLengthEnabled to enable prefix mode in cases where prefix of upper bound differs from prefix of seek key has a flaw. If present in the DB, “short keys” (shorter than “full length” prefix) can be omitted from auto_prefix_mode iteration when they would be present in total_order_seek iteration, regardless of whether the short keys are “in domain” of the prefix extractor. This is not an issue if no short keys are added to DB or are not expected to be returned by such iterators. (We are also assuming the new condition on IsSameLengthImmediateSuccessor is satisfied; see its BUG section). A bug example is in DBTest2::AutoPrefixMode1, search for “BUG”.

Source

pub fn get_auto_prefix_mode(&self) -> bool

Returns the value of the auto_prefix_mode option.

Source

pub fn get_auto_readahead_size(&self) -> bool

If auto_readahead_size is set to true, it will auto tune the readahead_size during scans internally based on block cache data when block cache is enabled, iteration upper bound when iterate_upper_bound != nullptr and prefix when prefix_same_as_start == true

Besides enabling block cache, it also requires iterate_upper_bound != nullptr or prefix_same_as_start == true for this option to take effect

To be specific, it does the following: (1) When iterate_upper_bound is specified, trim the readahead so the readahead does not exceed iteration upper bound (2) When prefix_same_as_start is set to true, trim the readahead so data blocks containing keys that are not in the same prefix as the seek key in Seek() are not prefetched

Limition: Seek(key) instead of SeekToFirst() needs to be called in order for this trimming to take effect

NOTE: - Used for forward Scans only.

If there is a backward scans, this option will be disabled internally and won’t be enabled again if the forward scan is issued again.

Default: true

Source

pub fn set_auto_refresh_iterator_with_snapshot(&mut self, val: bool)

EXPERIMENTAL

Long-running iterators are holding onto memory and storage resources long after they are obsolete. This setting (when enabled) will fix that problem for as long as iterator periodically makes some progress and its supplied read_options was configured with non-nullptr snapshot value. The feature is engineered so that the performance impact should be negligible. We expect the default value to be true some time in the future.

NOTE 1: Does not have effect on TransactionDB with WRITE_PREPARED or WRITE_UNPREPARED policies (currently incompatible).

NOTE 2: True is not recommended if using user-defined timestamp with persist_user_defined_timestamps=false and non-nullptr ReadOptions::timestamp or ReadOptions::iter_start_ts, because auto-refreshing iterator will not prevent user timestamp information from being dropped during iteration. Auto-refresh might be disabled for this combination in the future.

Default: false

Source

pub fn get_auto_refresh_iterator_with_snapshot(&self) -> bool

Returns the value of the auto_refresh_iterator_with_snapshot option.

Source

pub fn set_io_activity(&mut self, val: c_int)

EXPERIMENTAL

Source

pub fn get_io_activity(&self) -> c_int

Returns the value of the io_activity option.

Source

pub fn set_merge_operand_count_threshold(&mut self, val: usize)

When the number of merge operands applied exceeds this threshold during a successful query, the operation will return a special OK Status with subcode kMergeOperandThresholdExceeded. Currently only applies to point lookups and is disabled by default.

Source

pub fn get_merge_operand_count_threshold(&self) -> usize

Returns the value of the merge_operand_count_threshold option.

Source

pub fn set_rate_limiter_priority(&mut self, val: c_int)

For file reads associated with this option, charge the internal rate limiter (see DBOptions::rate_limiter) at the specified priority. The special value Env::IO_TOTAL disables charging the rate limiter.

The rate limiting is bypassed no matter this option’s value for file reads on plain tables (these can exist when ColumnFamilyOptions::table_factory is a PlainTableFactory) and cuckoo tables (these can exist when ColumnFamilyOptions::table_factory is a CuckooTableFactory).

The bytes charged to rate limiter may not exactly match the file read bytes since there are some seemingly insignificant reads, like for file headers/footers, that we currently do not charge to rate limiter.

Source

pub fn get_rate_limiter_priority(&self) -> c_int

Returns the value of the rate_limiter_priority option.

Source

pub fn set_request_id(&mut self, id: impl AsRef<str>)

Tags this read with an application chosen id, so filesystem metrics and logs can be lined up with RocksDB and application logs for the same request.

The id does not have to be unique per RocksDB call. It usually names an application level request that fans out into several of them.

The ReadOptions owns a copy, so id does not have to outlive this call. Passing an empty string sets an empty id rather than removing it, use Self::clear_request_id for that.

Source

pub fn get_request_id(&self) -> Option<String>

The id set by Self::set_request_id, or None when there is none.

Source

pub fn clear_request_id(&mut self)

Drops the request id, so this read is untagged again.

See Self::set_request_id.

Source

pub fn set_table_filter<F>(&mut self, filter: F)
where F: Fn(&TableProperties<'_>) -> bool + Send + Sync + 'static,

Skips whole SST files during iteration based on their properties.

filter runs once per table an iterator is about to open. Returning false skips the file, returning true scans it. This only affects iterators, point lookups ignore it.

Creating an iterator on a read-write DB fails with InvalidArgument when the target column family has a non-zero min_tombstones_for_range_conversion, because skipping a file that holds tombstones could make deletes reappear. Turning that option off does not undo range tombstones RocksDB has already written, so account for the ones already in the memtable and SST files before relying on a filter.

filter must be Send + Sync because RocksDB calls it from whichever thread drives the iterator. It replaces any filter set earlier. A panic inside it crosses a C frame, which aborts the process.

Source

pub fn clear_table_filter(&mut self)

Drops the table filter, so iteration scans every file again.

See Self::set_table_filter.

Source

pub fn has_table_filter(&self) -> bool

Whether a table filter is installed.

See Self::set_table_filter.

Source

pub fn set_table_index_factory_from_string( &mut self, value: impl AsRef<str>, ) -> Result<(), Error>

Reads through the user defined index named by value instead of the standard block-based index.

value goes through the UserDefinedIndexFactory object registry the same way BlockBasedOptions::set_user_defined_index_factory_from_string does, so it has to name the factory the SST files were written with. trie_index is the only factory RocksDB registers itself.

Only needed while the UDI is a secondary index. With BlockBasedOptions::set_use_udi_as_primary_index on, every read already goes through the UDI and the factory from the table options wins over this one.

§Errors

Returns an error if value names no registered factory, or carries settings that factory rejects. Either way the previously configured factory is cleared first.

Source

pub fn get_table_index_factory_name(&self) -> Option<String>

Name of the configured user defined index factory, or None when there is none.

This is the factory’s registered id, not the full string passed to Self::set_table_index_factory_from_string.

Source

pub fn clear_table_index_factory(&mut self)

Drops the user defined index factory, so reads go back to the standard index.

See Self::set_table_index_factory_from_string.

Source

pub fn set_value_size_soft_limit(&mut self, val: u64)

Soft limit on the cumulative value size read by a single MultiGet, to bound how much it buffers. It always makes progress: at least one key is read even if its value alone exceeds the limit. Once the returned size exceeds the limit, subsequent keys get status Aborted (so a caller can retry them, and cannot loop forever on a single value that by itself exceeds the limit).

Source