Struct BlockBasedOptions 

pub struct BlockBasedOptions { /* private fields */ }

For configuring block-based file storage.

Implementations

impl BlockBasedOptions

pub fn set_block_size(&mut self, size: usize)

Approximate size of user data packed per block. Note that the block size specified here corresponds to uncompressed data. The actual size of the unit read from disk may be smaller if compression is enabled. This parameter can be changed dynamically.

pub fn set_metadata_block_size(&mut self, size: usize)

Block size for partitioned metadata. Currently applied to indexes when kTwoLevelIndexSearch is used and to filters when partition_filters is used. Note: Since in the current implementation the filters and index partitions are aligned, an index/filter block is created when either index or filter block size reaches the specified limit.

Note: this limit is currently applied to only index blocks; a filter partition is cut right after an index block is cut.

pub fn set_partition_filters(&mut self, size: bool)

Note: currently this option requires kTwoLevelIndexSearch to be set as well.

Use partitioned full filters for each SST file. This option is incompatible with block-based filters.

pub fn set_block_cache(&mut self, cache: &Cache)

Sets global cache for blocks (user data is stored in a set of blocks, and a block is the unit of reading from disk).

If set, use the specified cache for blocks. By default, rocksdb will automatically create and use an 8MB internal cache.

pub fn disable_cache(&mut self)

Disable block cache

pub fn set_bloom_filter(&mut self, bits_per_key: c_double, block_based: bool)

Sets a Bloom filter policy to reduce disk reads.

Examples

use rust_rocksdb::BlockBasedOptions;

let mut opts = BlockBasedOptions::default();
opts.set_bloom_filter(10.0, true);

pub fn set_ribbon_filter(&mut self, bloom_equivalent_bits_per_key: c_double)

Sets a Ribbon filter policy to reduce disk reads.

Ribbon filters use less memory in exchange for slightly more CPU usage compared to an equivalent bloom filter.

Examples

use rust_rocksdb::BlockBasedOptions;

let mut opts = BlockBasedOptions::default();
opts.set_ribbon_filter(10.0);

pub fn set_hybrid_ribbon_filter( &mut self, bloom_equivalent_bits_per_key: c_double, bloom_before_level: c_int, )

Sets a hybrid Ribbon filter policy to reduce disk reads.

Uses Bloom filters before the given level, and Ribbon filters for all other levels. This combines the memory savings from Ribbon filters with the lower CPU usage of Bloom filters.

Examples

use rust_rocksdb::BlockBasedOptions;

let mut opts = BlockBasedOptions::default();
opts.set_hybrid_ribbon_filter(10.0, 2);

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

Whether to put index/filter blocks in the block cache. When false, each “table reader” object will pre-load index/filter blocks during table initialization. Index and filter partition blocks always use block cache regardless of this option.

Default: false

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

If cache_index_and_filter_blocks is enabled, cache index and filter blocks with high priority. Depending on the block cache implementation, index, filter, and other metadata blocks may be less likely to be evicted than data blocks when this is set to true.

Default: true.

pub fn set_index_type(&mut self, index_type: BlockBasedIndexType)

Defines the index type to be used for SS-table lookups.

Examples

use rust_rocksdb::{BlockBasedOptions, BlockBasedIndexType, Options};

let mut opts = Options::default();
let mut block_opts = BlockBasedOptions::default();
block_opts.set_index_type(BlockBasedIndexType::HashSearch);

pub fn set_index_block_search_type(&mut self, search_type: IndexBlockSearchType)

Selects the search algorithm used inside each index block at lookup time.

Use IndexBlockSearchType::Interpolation when keys in index blocks are known to be uniformly distributed and the byte-wise comparator is in use, or IndexBlockSearchType::Auto to let RocksDB choose per block. Auto requires the corresponding write-path threshold to be set via Self::set_uniform_cv_threshold; otherwise it falls back to binary search.

Default: IndexBlockSearchType::Binary

Examples

use rust_rocksdb::{BlockBasedOptions, IndexBlockSearchType};

let mut block_opts = BlockBasedOptions::default();
block_opts.set_index_block_search_type(IndexBlockSearchType::Auto);
block_opts.set_uniform_cv_threshold(0.2);

pub fn set_uniform_cv_threshold(&mut self, threshold: f64)

Coefficient of variation (CV) threshold used on the write path to decide whether an index block’s keys are “uniform” enough to benefit from interpolation search at read time. When the CV of key gaps within an index block is below this threshold, the per-block “is_uniform” footer bit is set, which IndexBlockSearchType::Auto consults at lookup time.

Any negative value disables the feature; the magnitude is ignored. With the default disabled value, IndexBlockSearchType::Auto degenerates to binary search at read time because the per-block “is_uniform” bit is never written. The recommended enabled range is 0.0..=1.0; a typical value is 0.2.

Note: currently only index blocks honour this; the value has no effect on data blocks today.

Default: -1.0 (disabled)

Examples

use rust_rocksdb::BlockBasedOptions;

let mut block_opts = BlockBasedOptions::default();
block_opts.set_uniform_cv_threshold(0.2);

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

If cache_index_and_filter_blocks is true and the below is true, then filter and index blocks are stored in the cache, but a reference is held in the “table reader” object so the blocks are pinned and only evicted from cache when the table reader is freed.

Default: false.

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

If cache_index_and_filter_blocks is true and the below is true, then the top-level index of partitioned filter and index blocks are stored in the cache, but a reference is held in the “table reader” object so the blocks are pinned and only evicted from cache when the table reader is freed. This is not limited to l0 in LSM tree.

Default: true.

pub fn set_format_version(&mut self, version: i32)

Format version, reserved for backward compatibility.

See full list of the supported versions.

Default: 6.

pub fn set_use_delta_encoding(&mut self, enable: bool)

Use delta encoding to compress keys in blocks. ReadOptions::pin_data requires this option to be disabled.

Default: true

pub fn set_block_restart_interval(&mut self, interval: i32)

Number of keys between restart points for delta encoding of keys. This parameter can be changed dynamically. Most clients should leave this parameter alone. The minimum value allowed is 1. Any smaller value will be silently overwritten with 1.

Default: 16.

pub fn set_index_block_restart_interval(&mut self, interval: i32)

Same as block_restart_interval but used for the index block. If you don’t plan to run RocksDB before version 5.16 and you are using index_block_restart_interval > 1, you should probably set the format_version to >= 4 as it would reduce the index size.

Default: 1.

pub fn set_data_block_index_type(&mut self, index_type: DataBlockIndexType)

Set the data block index type for point lookups: DataBlockIndexType::BinarySearch to use binary search within the data block. DataBlockIndexType::BinaryAndHash to use the data block hash index in combination with the normal binary search.

The hash table utilization ratio is adjustable using set_data_block_hash_ratio, which is valid only when using DataBlockIndexType::BinaryAndHash.

Default: BinarySearch

Examples

use rust_rocksdb::{BlockBasedOptions, DataBlockIndexType, Options};

let mut opts = Options::default();
let mut block_opts = BlockBasedOptions::default();
block_opts.set_data_block_index_type(DataBlockIndexType::BinaryAndHash);
block_opts.set_data_block_hash_ratio(0.85);

pub fn set_data_block_hash_ratio(&mut self, ratio: f64)

Set the data block hash index utilization ratio.

The smaller the utilization ratio, the less hash collisions happen, and so reduce the risk for a point lookup to fall back to binary search due to the collisions. A small ratio means faster lookup at the price of more space overhead.

Default: 0.75

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

If false, place only prefixes in the filter, not whole keys.

Defaults to true.

pub fn set_checksum_type(&mut self, checksum_type: ChecksumType)

Use the specified checksum type. Newly created table files will be protected with this checksum type. Old table files will still be readable, even though they have different checksum type.

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

If true, generate Bloom/Ribbon filters that minimize memory internal fragmentation. See official wiki for more information.

Default: true.

Examples

use rust_rocksdb::BlockBasedOptions;

let mut opts = BlockBasedOptions::default();
opts.set_bloom_filter(10.0, true);
opts.set_optimize_filters_for_memory(true);

pub fn set_top_level_index_pinning_tier(&mut self, tier: BlockBasedPinningTier)

The tier of block-based tables whose top-level index into metadata partitions will be pinned. Currently indexes and filters may be partitioned.

Note cache_index_and_filter_blocks must be true for this option to have any effect. Otherwise any top-level index into metadata partitions would be held in table reader memory, outside the block cache.

Default: BlockBasedPinningTier:Fallback

Example

use rust_rocksdb::{BlockBasedOptions, BlockBasedPinningTier, Options};

let mut opts = Options::default();
let mut block_opts = BlockBasedOptions::default();
block_opts.set_top_level_index_pinning_tier(BlockBasedPinningTier::FlushAndSimilar);

pub fn set_partition_pinning_tier(&mut self, tier: BlockBasedPinningTier)

The tier of block-based tables whose metadata partitions will be pinned. Currently indexes and filters may be partitioned.

Default: BlockBasedPinningTier:Fallback

Example

use rust_rocksdb::{BlockBasedOptions, BlockBasedPinningTier, Options};

let mut opts = Options::default();
let mut block_opts = BlockBasedOptions::default();
block_opts.set_partition_pinning_tier(BlockBasedPinningTier::FlushAndSimilar);

pub fn set_unpartitioned_pinning_tier(&mut self, tier: BlockBasedPinningTier)

The tier of block-based tables whose unpartitioned metadata blocks will be pinned.

Note cache_index_and_filter_blocks must be true for this option to have any effect. Otherwise the unpartitioned meta-blocks would be held in table reader memory, outside the block cache.

Default: BlockBasedPinningTier:Fallback

Example

use rust_rocksdb::{BlockBasedOptions, BlockBasedPinningTier, Options};

let mut opts = Options::default();
let mut block_opts = BlockBasedOptions::default();
block_opts.set_unpartitioned_pinning_tier(BlockBasedPinningTier::FlushAndSimilar);

Trait Implementations

impl Default for BlockBasedOptions

fn default() -> Self

Returns the “default value” for a type.

impl Drop for BlockBasedOptions

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Send for BlockBasedOptions

impl Sync for BlockBasedOptions