Class CompactionFilter

Namespace

RocksDbNet

Assembly

RocksDb.Net.dll

User-defined compaction filter. Override Filter to inspect or modify key-value pairs during table-file creation (compaction / flush).

public abstract class CompactionFilter : RocksDbHandle, IDisposable

Inheritance

object

RocksDbHandle

CompactionFilter

Implements

IDisposable

Inherited Members

RocksDbHandle.Handle

RocksDbHandle.Owned

RocksDbHandle.IsDisposed

RocksDbHandle.PinGarbageCollector(string)

RocksDbHandle.IsPinned

RocksDbHandle.GetPinnedIntPtr()

RocksDbHandle.GetPinnedNameIntPtr()

RocksDbHandle.UnpinGarbageCollector()

RocksDbHandle.GetSelfFromPinnedIntPtr<T>(nint)

RocksDbHandle.GetNameFromPinnedIntPtr(nint)

RocksDbHandle.ThrowIfDisposed()

RocksDbHandle.Dispose()

RocksDbHandle.Dispose(bool)

RocksDbHandle.DisposeUnmanagedResources()

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Lifetime: Dispose it whenever you like. Attaching it through CompactionFilter registers a hold, so disposing while the database is open defers the release instead of performing it. The usual using shape is safe.

Thread safety: When a single instance is registered and multi-threaded compaction is active, Filter may be called from multiple threads concurrently. Either make your override thread-safe or use CompactionFilterFactory to create a separate instance per compaction job.

Constructors

CompactionFilter(string)

Creates a compaction filter with the given name.

protected CompactionFilter(string name)

Parameters

name string

Identifies the filter in RocksDb's logs and options output. Not enforced on reopen.

Methods

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

Filter(int, ReadOnlySpan<byte>, ReadOnlySpan<byte>, IBufferWriter<byte>)

Called for each key-value pair during table-file creation, writing any replacement value into a buffer rather than returning an array.

protected virtual FilterDecision Filter(int level, ReadOnlySpan<byte> key, ReadOnlySpan<byte> existingValue, IBufferWriter<byte> newValue)

Parameters

level int

The SST level of the file being created.

key ReadOnlySpan<byte>

The key. Valid only for the duration of this call.

existingValue ReadOnlySpan<byte>

The current value. Valid only for the duration of this call.

newValue IBufferWriter<byte>

Where to write the replacement when returning ChangeValue; nothing written means an empty value. Ignored for other decisions. Valid only for the duration of this call: do not keep it.

Returns

FilterDecision

The decision for this entry.

Remarks

The default calls the array form and copies its replacement in, so a filter written against that form behaves as it always has. Override this one instead to replace values without allocating; override one form, not both.

For the array form, ChangeValue with a null replacement keeps the entry unchanged, as it always did.

Filter(int, ReadOnlySpan<byte>, ReadOnlySpan<byte>, out byte[]?)

Called for each key-value pair during table-file creation.

protected virtual FilterDecision Filter(int level, ReadOnlySpan<byte> key, ReadOnlySpan<byte> existingValue, out byte[]? newValue)

Parameters

level int

The SST level of the file being created.

key ReadOnlySpan<byte>

The key. The span is valid only for the duration of this call; copy the data if you need it beyond the call.

existingValue ReadOnlySpan<byte>

The current value. Valid only for the duration of this call.

newValue byte[]

Output: when returning ChangeValue, set this to the replacement value. Ignored for other decisions.

Returns

FilterDecision

Keep, Remove, or ChangeValue.

Exceptions

NotSupportedException

Neither form of Filter is overridden. Reported through UnhandledException, and the entry is kept.