Class BlockBasedTableOptions

Namespace

RocksDbNet

Assembly

RocksDb.Net.dll

Options for the block-based table format. Configure and then pass to BlockBasedTableFactory. Maps to rocksdb_block_based_table_options_t.

public sealed class BlockBasedTableOptions : RocksDbHandle, IDisposable

Inheritance

object

RocksDbHandle

BlockBasedTableOptions

Implements

IDisposable

Inherited Members

RocksDbHandle.Handle

RocksDbHandle.Owned

RocksDbHandle.IsDisposed

RocksDbHandle.ThrowIfDisposed()

RocksDbHandle.Dispose()

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

BlockBasedTableOptions()

public BlockBasedTableOptions()

Properties

BlockAlign

If true, data blocks are aligned to the block size, which lets the filesystem read one block without straddling a page boundary.

public bool BlockAlign { get; set; }

Property Value

bool

BlockRestartInterval

Number of keys between restart points in data blocks.

public int BlockRestartInterval { get; set; }

Property Value

int

BlockSize

Block size (in bytes). Defaults to 4 KB.

public ulong BlockSize { get; set; }

Property Value

ulong

BlockSizeDeviation

Block size deviation: block is closed once its size is this % smaller than target. Default: 10.

public int BlockSizeDeviation { get; set; }

Property Value

int

CacheIndexAndFilterBlocks

If true, index and filter blocks are stored in the block cache.

public bool CacheIndexAndFilterBlocks { get; set; }

Property Value

bool

CacheIndexAndFilterBlocksWithHighPriority

If true, index and filter blocks are given high priority in the block cache.

public bool CacheIndexAndFilterBlocksWithHighPriority { get; set; }

Property Value

bool

Checksum

Checksum algorithm used to protect each block.

public ChecksumType Checksum { get; set; }

Property Value

ChecksumType

Remarks

Defaults to Xxh3. This was an int, on the grounds that the C API does not publish the values. It does not, but the header does, and it rejects everything outside 0 to 4, which is the range the enum covers.

Exceptions

RocksDbException

The value is not one RocksDb recognises. It is reported when the database is opened rather than here, since that is when the table factory is validated.

DataBlockHashTableUtilRatio

Fraction of a data block's space given to its hash table, when DataBlockIndexType is BinarySearchAndHash. Higher values trade space for faster point lookups.

public double DataBlockHashTableUtilRatio { get; set; }

Property Value

double

DataBlockIndexType

Index type used inside a data block.

public DataBlockIndexType DataBlockIndexType { get; set; }

Property Value

DataBlockIndexType

DecouplePartitionedFilters

If true, partitioned filters are stored independently of the index, so a filter partition need not match an index partition.

public bool DecouplePartitionedFilters { get; set; }

Property Value

bool

DetectFilterConstructCorruption

If true, filters are checksummed as they are built, catching corruption that happens during filter construction.

public bool DetectFilterConstructCorruption { get; set; }

Property Value

bool

EnableIndexCompression

If true, index blocks are compressed.

public bool EnableIndexCompression { get; set; }

Property Value

bool

FailIfNoUdiOnOpen

If true, opening a file that has no user-defined index fails instead of falling back to the built-in index.

public bool FailIfNoUdiOnOpen { get; set; }

Property Value

bool

FormatVersion

Format version of the SST table. Higher versions offer more features.

public int FormatVersion { get; set; }

Property Value

int

IndexBlockRestartInterval

Number of keys between restart points in index blocks.

public int IndexBlockRestartInterval { get; set; }

Property Value

int

IndexBlockSearchType

Search algorithm used within an index block.

public IndexBlockSearchType IndexBlockSearchType { get; set; }

Property Value

IndexBlockSearchType

IndexShortening

How much of the index key RocksDb may discard to save space.

public IndexShortening IndexShortening { get; set; }

Property Value

IndexShortening

IndexType

Type of index used in the block-based table.

public BlockBasedTableIndexType IndexType { get; set; }

Property Value

BlockBasedTableIndexType

InitialAutoReadaheadSize

Readahead size in bytes an iterator starts with before adaptive readahead grows it. 0 lets RocksDb choose.

public ulong InitialAutoReadaheadSize { get; set; }

Property Value

ulong

MaxAutoReadaheadSize

Upper bound in bytes on how far adaptive readahead will grow.

public ulong MaxAutoReadaheadSize { get; set; }

Property Value

ulong

MetadataBlockSize

Target size of metadata blocks in bytes.

public ulong MetadataBlockSize { get; set; }

Property Value

ulong

NoBlockCache

Disables the block cache entirely.

public bool NoBlockCache { get; set; }

Property Value

bool

NumFileReadsForAutoReadahead

Number of sequential file reads before adaptive readahead kicks in.

public ulong NumFileReadsForAutoReadahead { get; set; }

Property Value

ulong

OptimizeFiltersForMemory

If true, filters are built to use memory in block-size units, which cuts the memory a bloom filter wastes at the cost of a slightly higher false positive rate.

public bool OptimizeFiltersForMemory { get; set; }

Property Value

bool

PartitionFilters

If true, use partitioned full filters (requires index type TwoLevelIndexSearch).

public bool PartitionFilters { get; set; }

Property Value

bool

PartitionPinningTier

Which partitioned index and filter blocks stay pinned.

public PinningTier PartitionPinningTier { set; }

Property Value

PinningTier

Remarks

Write-only: RocksDb exposes no getter. Default is Fallback, which defers to the older boolean pinning options.

PinL0FilterAndIndexBlocksInCache

If true, pin level-0 index and filter blocks in the block cache.

public bool PinL0FilterAndIndexBlocksInCache { get; set; }

Property Value

bool

PinTopLevelIndexAndFilter

If true, the top-level index of a partitioned index and filter is pinned in memory rather than left to be evicted from the block cache.

public bool PinTopLevelIndexAndFilter { get; set; }

Property Value

bool

Remarks

The C API models this as a flag, not as one of the pinning-tier values, so it is exposed as a bool.

PrepopulateBlockCache

Whether newly written blocks are inserted into the block cache eagerly.

public PrepopulateBlockCache PrepopulateBlockCache { get; set; }

Property Value

PrepopulateBlockCache

ReadAmpBytesPerBit

Bytes per bit of the read-amplification estimator. 0 disables it. Must be a power of two when set.

public uint ReadAmpBytesPerBit { get; set; }

Property Value

uint

SeparateKeyValueInDataBlock

If true, keys and values are stored in separate regions of a data block, which compresses better for workloads with similar keys.

public bool SeparateKeyValueInDataBlock { get; set; }

Property Value

bool

SuperBlockAlignmentSize

Alignment in bytes of the super block. 0 disables alignment.

public ulong SuperBlockAlignmentSize { get; set; }

Property Value

ulong

SuperBlockAlignmentSpaceOverheadRatio

Space overhead RocksDb will accept, as a ratio, in exchange for super block alignment.

public ulong SuperBlockAlignmentSpaceOverheadRatio { get; set; }

Property Value

ulong

TopLevelIndexPinningTier

Which top-level index blocks stay pinned in the block cache.

public PinningTier TopLevelIndexPinningTier { set; }

Property Value

PinningTier

Remarks

Write-only: RocksDb exposes no getter. Default is Fallback, which defers to the older boolean pinning options.

UniformCvThreshold

Threshold at which blocks of uniformly sized entries get the compact uniform encoding.

public double UniformCvThreshold { get; set; }

Property Value

double

UnpartitionedPinningTier

Which unpartitioned index and filter blocks stay pinned.

public PinningTier UnpartitionedPinningTier { set; }

Property Value

PinningTier

Remarks

Write-only: RocksDb exposes no getter. Default is Fallback, which defers to the older boolean pinning options.

UseDeltaEncoding

If true, delta encoding is used for index values to reduce index size.

public bool UseDeltaEncoding { get; set; }

Property Value

bool

UseUdiAsPrimaryIndex

If true, a configured user-defined index is used as the primary index rather than as an extra one.

public bool UseUdiAsPrimaryIndex { get; set; }

Property Value

bool

UserDefinedIndexFactoryName

Name of the user-defined index factory in use, or null when none is configured.

public string? UserDefinedIndexFactoryName { get; }

Property Value

string

VerifyCompression

If true, each compressed block is decompressed again and compared, so a broken compression library is caught at write time rather than at read time. Expensive.

public bool VerifyCompression { get; set; }

Property Value

bool

WholeKeyFiltering

If true, the entire key is used for filtering; otherwise only the prefix.

public bool WholeKeyFiltering { get; set; }

Property Value

bool

Methods

ClearUserDefinedIndexFactory()

Removes any user-defined index factory from these options.

public BlockBasedTableOptions ClearUserDefinedIndexFactory()

Returns

BlockBasedTableOptions

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

SetBlockCache(Cache?)

Sets the block cache to use for this table.

public BlockBasedTableOptions SetBlockCache(Cache? cache)

Parameters

cache Cache

Returns

BlockBasedTableOptions

Remarks

Passing null does nothing at all; it does not disable caching and it does not clear a cache set earlier, because the C API ignores a null argument here. To run without a block cache, leave this unset, or set NoBlockCache.

SetFilterPolicy(FilterPolicy?)

Attaches a filter policy (e.g. Bloom filter).

public BlockBasedTableOptions SetFilterPolicy(FilterPolicy? policy)

Parameters

policy FilterPolicy

Returns

BlockBasedTableOptions

SetUserDefinedIndexFactoryFromString(string)

Selects a user-defined index factory by its RocksDb configuration string.

public BlockBasedTableOptions SetUserDefinedIndexFactoryFromString(string value)

Parameters

value string

Returns

BlockBasedTableOptions

Exceptions

RocksDbException

The string does not name a known factory.