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: 7, which needs RocksDB 10.4.0 or newer to read. Lower it if older readers have to open the files.

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

pub fn get_block_align(&self) -> bool

Align data blocks on lesser of page size and block size

pub fn get_block_restart_interval(&self) -> c_int

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.

pub fn get_block_size(&self) -> u64

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 get_block_size_deviation(&self) -> c_int

This is used to close a block before it reaches the configured ‘block_size’. If the percentage of free space in the current block is less than this specified number and adding a new record to the block will exceed the configured block size, then this block will be closed and the new record will be written to the next block.

pub fn get_cache_index_and_filter_blocks(&self) -> bool

TODO(kailiu) Temporarily disable this feature by making the default value to be false.

TODO(ajkr) we need to update names of variables controlling meta-block caching as they should now apply to range tombstone and compression dictionary meta-blocks, in addition to index and filter meta-blocks.

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.

pub fn get_cache_index_and_filter_blocks_with_high_priority(&self) -> bool

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

pub fn get_checksum(&self) -> c_int

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_data_block_hash_table_util_ratio(&mut self, val: f64)

#entries/#buckets. It is valid only when data_block_hash_index_type is kDataBlockBinaryAndHash.

pub fn get_data_block_hash_table_util_ratio(&self) -> f64

Returns the value of the data_block_hash_table_util_ratio option.

pub fn get_data_block_index_type(&self) -> c_int

Returns the value of the data_block_index_type option.

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

When both partitioned indexes and partitioned filters are enabled, this enables independent partitioning boundaries between the two. Most notably, this enables these metadata blocks to hit their target size much more accurately, as there is often a disparity between index sizes and filter sizes. This should reduce fragmentation and metadata overheads in the block cache, as well as treat blocks more fairly for cache eviction purposes.

There are no SST format compatibility issues with this option. (All versions of RocksDB able to read partitioned filters are able to read decoupled partitioned filters.)

decouple_partitioned_filters = true is the new default. This option is now DEPRECATED and might be ignored and/or removed in a future release.

NOTE: decouple_partitioned_filters = false with partition_filters = true disables parallel compression (CompressionOptions::parallel_threads sanitized to 1).

pub fn get_decouple_partitioned_filters(&self) -> bool

Returns the value of the decouple_partitioned_filters option.

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

If true, detect corruption during Bloom Filter (format_version >= 5) and Ribbon Filter construction.

This is an extra check that is only useful in detecting software bugs or CPU+memory malfunction. Turning on this feature increases filter construction time by 30%.

TODO: optimize this performance

pub fn get_detect_filter_construct_corruption(&self) -> bool

Returns the value of the detect_filter_construct_corruption option.

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

Store index blocks on disk in compressed format. Changing this option to false will avoid the overhead of decompression if index blocks are evicted and read back

pub fn get_enable_index_compression(&self) -> bool

Returns the value of the enable_index_compression option.

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

EXPERIMENTAL

Return an error Status if a user_defined_index_factory is configured, but there’s no corresponding UDI block in the SST file being opened. When use_udi_as_primary_index is true, this check is automatically enforced (a missing UDI block is always an error in primary mode).

pub fn get_fail_if_no_udi_on_open(&self) -> bool

Returns the value of the fail_if_no_udi_on_open option.

pub fn get_format_version(&self) -> u32

We currently have these format versions: 0 - 1 – No longer supported. Attempting to read files with these format versions will return an error. To upgrade, load the data with RocksDB >= 4.6.0 and < 11.0.0, then run a full compaction.

• Can be read by RocksDB’s versions since 3.10. Changes the way we encode compressed blocks with LZ4, BZip2 and Zlib compression. If you don’t plan to run RocksDB before version 3.10, you should probably use this.
• Can be read by RocksDB’s versions since 5.15. Changes the way we encode the keys in index blocks. If you don’t plan to run RocksDB before version 5.15, you should probably use this. This option only affects newly written tables. When reading existing tables, the information about version is read from the footer.
• Can be read by RocksDB’s versions since 5.16. Changes the way we encode the values in index blocks. If you don’t plan to run RocksDB before version 5.16 and you are using index_block_restart_interval > 1, you should probably use this as it would reduce the index size. This option only affects newly written tables. When reading existing tables, the information about version is read from the footer.
• Can be read by RocksDB’s versions since 6.6.0. Full and partitioned filters use a generally faster and more accurate Bloom filter implementation, with a different schema.
• Modified the file footer and checksum matching so that SST data misplaced within or between files is as likely to fail checksum verification as random corruption. Also checksum-protects SST footer. Can be read by RocksDB versions >= 8.6.0.
• Support for custom compression algorithms with a CompressionManager using a non-built-in CompatibilityName(). See compression_manager in ColumnFamilyOptions. Also changes the format of TableProperties field compression_name. Can be read by RocksDB versions >= 10.4.0.

Using the default setting of format_version is strongly recommended, so that available enhancements are adopted eventually and automatically. The default setting will only update to the latest after thorough production validation and sufficient time and number of releases have elapsed (6 months recommended) to ensure a clean downgrade/revert path for users who might only upgrade a few times per year.

pub fn get_index_block_restart_interval(&self) -> c_int

Same as block_restart_interval but used for the index block.

pub fn get_index_block_search_type(&self) -> c_int

Returns the value of the index_block_search_type option.

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

Sets the index_shortening option.

pub fn get_index_shortening(&self) -> c_int

Returns the value of the index_shortening option.

pub fn get_index_type(&self) -> c_int

Returns the value of the index_type option.

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

RocksDB does auto-readahead for iterators on noticing more than two reads for a table file if user doesn’t provide readahead_size. The readahead size starts at initial_auto_readahead_size and doubles on every additional read upto BlockBasedTableOptions.max_auto_readahead_size. max_auto_readahead_size can also be configured.

Scenarios:

• If initial_auto_readahead_size is set 0 then it will disabled the implicit auto prefetching irrespective of max_auto_readahead_size.
• If max_auto_readahead_size is set 0, it will disable the internal prefetching irrespective of initial_auto_readahead_size.
• If initial_auto_readahead_size > max_auto_readahead_size, then RocksDB will sanitize the value of initial_auto_readahead_size to max_auto_readahead_size and readahead_size will be max_auto_readahead_size.

Value should be provided along with KB i.e. 8 * 1024 as it will prefetch the blocks.

Default: 8 KB (8 * 1024).

pub fn get_initial_auto_readahead_size(&self) -> usize

Returns the value of the initial_auto_readahead_size option.

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

RocksDB does auto-readahead for iterators on noticing more than two reads for a table file if user doesn’t provide readahead_size. The readahead starts at BlockBasedTableOptions.initial_auto_readahead_size (default: 8KB) and doubles on every additional read upto max_auto_readahead_size and max_auto_readahead_size can be configured.

Special Value: 0 - If max_auto_readahead_size is set 0 then it will disable the implicit auto prefetching. If max_auto_readahead_size provided is less than initial_auto_readahead_size, then RocksDB will sanitize the initial_auto_readahead_size and set it to max_auto_readahead_size.

Value should be provided along with KB i.e. 256 * 1024 as it will prefetch the blocks.

Found that 256 KB readahead size provides the best performance, based on experiments, for auto readahead. Experiment data is in PR #3282.

Default: 256 KB (256 * 1024).

pub fn get_max_auto_readahead_size(&self) -> usize

Returns the value of the max_auto_readahead_size option.

pub fn get_metadata_block_size(&self) -> u64

Target block size for partitioned metadata. Currently applied to indexes when kTwoLevelIndexSearch is used and to filters when partition_filters is used. When decouple_partitioned_filters=false (original behavior), there is much more deviation from this target size. See the comment on decouple_partitioned_filters.

pub fn get_no_block_cache(&self) -> bool

Disable block cache. If this is set to true, then no block cache will be configured (block_cache reset to nullptr).

This option should not be used with SetOptions.

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

RocksDB does auto-readahead for iterators on noticing more than two reads for a table file if user doesn’t provide readahead_size and reads are sequential. num_file_reads_for_auto_readahead indicates after how many sequential reads internal auto prefetching should be start.

For example, if value is 2 then after reading 2 sequential data blocks on third data block prefetching will start. If set 0, it will start prefetching from the first read.

This parameter can be changed dynamically by DB::SetOptions({{“block_based_table_factory”, “{num_file_reads_for_auto_readahead=0;}”}}));

Changing the value dynamically will only affect files opened after the change.

Default: 2

pub fn get_num_file_reads_for_auto_readahead(&self) -> u64

Returns the value of the num_file_reads_for_auto_readahead option.

pub fn get_optimize_filters_for_memory(&self) -> bool

Option to generate Bloom/Ribbon filters that minimize memory internal fragmentation.

When false, malloc_usable_size is not available, or format_version < 5, filters are generated without regard to internal fragmentation when loaded into memory (historical behavior). When true (and malloc_usable_size is available and format_version >= 5), then filters are generated to “round up” and “round down” their sizes to minimize internal fragmentation when loaded into memory, assuming the reading DB has the same memory allocation characteristics as the generating DB. This option does not break forward or backward compatibility.

While individual filters will vary in bits/key and false positive rate when setting is true, the implementation attempts to maintain a weighted average FP rate for filters consistent with this option set to false.

With Jemalloc for example, this setting is expected to save about 10% of the memory footprint and block cache charge of filters, while increasing disk usage of filters by about 1-2% due to encoding efficiency losses with variance in bits/key.

NOTE: Because some memory counted by block cache might be unmapped pages within internal fragmentation, this option can increase observed RSS memory usage. With cache_index_and_filter_blocks=true, this option makes the block cache better at using space it is allowed. (These issues should not arise with partitioned filters.)

NOTE: Set to false if you do not trust malloc_usable_size. When set to true, RocksDB might access an allocated memory object beyond its original size if malloc_usable_size says it is safe to do so. While this can be considered bad practice, it should not produce undefined behavior unless malloc_usable_size is buggy or broken.

pub fn get_partition_filters(&self) -> bool

Note: currently this option requires kTwoLevelIndexSearch to be set as well. TODO(myabandeh): remove the note above once the limitation is lifted Use partitioned full filters for each SST file. This option is incompatible with block-based filters. Filter partition blocks use block cache even when cache_index_and_filter_blocks=false.

pub fn get_pin_l0_filter_and_index_blocks_in_cache(&self) -> bool

DEPRECATED: This option will be removed in a future version. For now, this option still takes effect by updating each of the following variables that has the default value, PinningTier::kFallback:

• MetadataCacheOptions::partition_pinning
• MetadataCacheOptions::unpartitioned_pinning

The updated value is chosen as follows:

• pin_l0_filter_and_index_blocks_in_cache == false -> PinningTier::kNone
• pin_l0_filter_and_index_blocks_in_cache == true -> PinningTier::kFlushedAndSimilar

To migrate away from this flag, explicitly configure MetadataCacheOptions as described above.

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.

pub fn get_pin_top_level_index_and_filter(&self) -> bool

DEPRECATED: This option will be removed in a future version. For now, this option still takes effect by updating MetadataCacheOptions::top_level_index_pinning when it has the default value, PinningTier::kFallback.

The updated value is chosen as follows:

• pin_top_level_index_and_filter == false -> PinningTier::kNone
• pin_top_level_index_and_filter == true -> PinningTier::kAll

To migrate away from this flag, explicitly configure MetadataCacheOptions as described above.

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.

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

Sets the prepopulate_block_cache option.

pub fn get_prepopulate_block_cache(&self) -> c_int

Returns the value of the prepopulate_block_cache option.

pub fn set_read_amp_bytes_per_bit(&mut self, val: u32)

If used, For every data block we load into memory, we will create a bitmap of size ((block_size / read_amp_bytes_per_bit) / 8) bytes. This bitmap will be used to figure out the percentage we actually read of the blocks.

When this feature is used Tickers::READ_AMP_ESTIMATE_USEFUL_BYTES and Tickers::READ_AMP_TOTAL_READ_BYTES can be used to calculate the read amplification using this formula (READ_AMP_TOTAL_READ_BYTES / READ_AMP_ESTIMATE_USEFUL_BYTES)

value => memory usage (percentage of loaded blocks memory) 1 => 12.50 % 2 => 06.25 % 4 => 03.12 % 8 => 01.56 % 16 => 00.78 %

Note: This number must be a power of 2, if not it will be sanitized to be the next lowest power of 2, for example a value of 7 will be treated as 4, a value of 19 will be treated as 16.

Default: 0 (disabled)

pub fn get_read_amp_bytes_per_bit(&self) -> u32

Returns the value of the read_amp_bytes_per_bit option.

pub fn get_separate_key_value_in_data_block(&self) -> bool

When true, data blocks store keys and values separately. Keys are stored at the beginning of the block, followed by values at the end. This can improve read performance at a cost of a varint per restart interval (~1 bit per key by default), in addition to improving compression. Small values or low block_restart_interval may prefer to set this as false.

Default: false

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

Align data blocks on super block alignment. Avoid a data block split across super block boundaries. Works with/without compression.

Here a “super block” refers to an aligned unit of underlying Filesystem storage for which there is an extra cost when a random read involves two such super blocks instead of just one. Configuring that size here suggests inserting padding in the SST file to avoid a single SST block splitting across two super blocks. Only power-of-two sizes are supported. See also super_block_alignment_space_overhead_ratio. Default to 0, which means super block alignment is disabled.

Super block alignment size. Default to 0, which means super block alignment is disabled. If it is enabled, it needs to be a power of 2 and higher than block size.

pub fn get_super_block_alignment_size(&self) -> usize

Returns the value of the super_block_alignment_size option.

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

This option constrols the storage space overhead of super block alignment. It is used to calculate the max padding size allowed for super block alignment. It is calculated in this way. If super_block_alignment_size is 2MB, and super_block_alignment_overhead_ratio is 128, then the max padding size allowed for super block alignment is 2MB / 128 = 16KB. Note that, when it is set to 0, super block alignment is disabled.

pub fn get_super_block_alignment_space_overhead_ratio(&self) -> usize

Returns the value of the super_block_alignment_space_overhead_ratio option.

pub fn get_uniform_cv_threshold(&self) -> f64

Coefficient of variation (CV) threshold used to determine if keys in an index block are uniformly distributed. Lower CV means more “uniform”, and the more likely interpolation search will outperform binary search.

On the write path, if the CV of key gaps in an index block is less than this threshold, the “is_uniform” hint is set in that block’s footer. To disable (i.e. always have “is_uniform=false”), set value to -1.

On the read path, if BlockSearchType::kAuto is set, then it will use the is_uniform hint to select an appropriate search algorithm for the block.

NOTE: Currently only supports index blocks. May update to include data blocks in the future.

pub fn get_use_delta_encoding(&self) -> bool

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

Default: true

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

EXPERIMENTAL

When true and user_defined_index_factory is set, the UDI becomes the primary index for reads. All reads (including internal operations like compaction and VerifyChecksum) automatically route through the UDI without needing ReadOptions::table_index_factory.

Both the standard binary search index and the UDI are always fully built. The standard index serves as a safety fallback (e.g., for backup/restore or rollback to a non-UDI configuration). A future refactor will extract the index abstraction to allow skipping the standard index build when the UDI is primary.

When the UDI is primary:

• All reads automatically use the UDI (ReadOptions::table_index_factory does not need to be set)
• Partitioned index (kTwoLevelIndexSearch) and partitioned filters are incompatible with this option
• fail_if_no_udi_on_open is automatically enforced to prevent silent data loss if these SSTs are opened without UDI support

Recommended migration path:

• Deploy with user_defined_index_factory set but use_udi_as_primary_index=false (secondary mode). New SSTs are written with both indexes. Reads use the standard index by default.

• Validate reads through the UDI by setting ReadOptions::table_index_factory on a subset of reads.

• Compact the entire DB to rewrite all pre-existing SSTs with both indexes. All SSTs must have a UDI block before proceeding.

• Enable use_udi_as_primary_index=true. All reads use the UDI.

Rollback: set use_udi_as_primary_index=false. Since the standard index is always fully populated, SSTs are immediately readable through the standard index. No compaction is required. All reads immediately revert to the standard index path.

Backup/restore: the user_defined_index_factory is a shared_ptr that cannot survive Options serialization (e.g., GetStringFromDBOptions). Since the standard index is always fully populated, a restored DB can be opened and read without the factory (reads fall back to the standard index). Set the factory when opening the restored DB to resume using the UDI.

Default: false (UDI is built alongside the standard index as a secondary)

pub fn get_use_udi_as_primary_index(&self) -> bool

Returns the value of the use_udi_as_primary_index option.

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

EXPERIMENTAL

Builds a user defined index into every new SST file, using the factory named by value.

value goes through the UserDefinedIndexFactory object registry, so it is either a registered id on its own or an id followed by that factory’s own settings, in the usual id=name; option=value; ... form. trie_index is the only factory RocksDB registers itself.

The factory replaces any set earlier. Reads still go through the standard index unless Self::set_use_udi_as_primary_index is on or ReadOptions::set_table_index_factory_from_string selects the UDI for that read.

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.

pub fn get_user_defined_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_user_defined_index_factory_from_string.

pub fn clear_user_defined_index_factory(&mut self)

Drops the user defined index factory, so new SST files carry only the standard index.

Files already written keep their UDI block, and stay readable through the standard index.

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

Verify that decompressing the compressed block gives back the input. This is a verification mode that we use to detect bugs in compression algorithms.

pub fn get_verify_compression(&self) -> bool

Returns the value of the verify_compression option.

pub fn get_whole_key_filtering(&self) -> bool

If true, place whole keys in the filter (not just prefixes). This must generally be true for gets to be efficient.

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

Align data blocks on lesser of page size and block size.

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

This is used to close a block before it reaches the configured ‘block_size’. If the percentage of free space in the current block is less than this specified number and adding a new record to the block will exceed the configured block size, then this block will be closed and the new record will be written to the next block.

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

When true, data blocks store keys and values separately. Keys are stored at the beginning of the block, followed by values at the end. This can improve read performance at a cost of a varint per restart interval (~1 bit per key by default), in addition to improving compression. Small values or low block_restart_interval may prefer to set this as false.

Default: false.

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