Class MergeOperator

Namespace

RocksDbNet

Assembly

RocksDb.Net.dll

User-defined merge operator that enables read-modify-write semantics on values stored in RocksDb. Override FullMerge (and optionally PartialMerge) to implement custom merge logic, in either the array form or the span form, which reads the operands in place through MergeOperands and merges without allocating.

public abstract class MergeOperator : RocksDbHandle, IDisposable

Inheritance

object

RocksDbHandle

MergeOperator

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

A merge operator is used with Merge(string, string, WriteOptions?) and similar overloads to combine new values with existing ones without a separate read step. Common use cases include counters, lists, and append-only logs.

Register a merge operator via MergeOperator or use SetUInt64AddMergeOperator() for the built-in 64-bit addition operator.

Constructors

MergeOperator(string)

Creates a merge operator with the given name.

protected MergeOperator(string name)

Parameters

name string

Identifies this operator in RocksDb's logs and options output. Unlike a comparator name it is not enforced on reopen, so a mismatch will not be caught for you: opening a database with a different merge operator than the one that wrote its operands silently produces wrong merges.

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

FullMerge(ReadOnlySpan<byte>, bool, ReadOnlySpan<byte>, MergeOperands, IBufferWriter<byte>)

Merges all accumulated operands with the existing value for a key, without copying either.

public virtual bool FullMerge(ReadOnlySpan<byte> key, bool hasExistingValue, ReadOnlySpan<byte> existingValue, MergeOperands operands, IBufferWriter<byte> newValue)

Parameters

key ReadOnlySpan<byte>

The key being merged. Valid for the duration of the call.

hasExistingValue bool

true if the key has a pre-existing value.

existingValue ReadOnlySpan<byte>

The current value, valid only when hasExistingValue is true.

operands MergeOperands

The operands, oldest first, read in place. See MergeOperands.

newValue IBufferWriter<byte>

Where to write the result. Valid only for the duration of the call: do not keep it.

Returns

bool

true if the merge succeeded; false to signal failure.

Remarks

The default copies the operands into arrays and calls the array form, then writes its result. Override this instead to merge without allocating.

FullMerge(ReadOnlySpan<byte>, bool, ReadOnlySpan<byte>, IReadOnlyList<byte[]>, out byte[]?)

Called to merge all accumulated operands with the existing value for a key.

public virtual bool FullMerge(ReadOnlySpan<byte> key, bool hasExistingValue, ReadOnlySpan<byte> existingValue, IReadOnlyList<byte[]> operands, out byte[]? newValue)

Parameters

key ReadOnlySpan<byte>

The key being merged.

hasExistingValue bool

true if the key has a pre-existing value.

existingValue ReadOnlySpan<byte>

The current value (valid only when hasExistingValue is true).

operands IReadOnlyList<byte[]>

The operands to merge, in chronological order. Managed copies, so they may be kept beyond the call.

newValue byte[]

Output: the result of the merge.

Returns

bool

true if the merge succeeded; false to signal failure.

Exceptions

NotSupportedException

Neither form of FullMerge is overridden. Reported through UnhandledException, and the merge fails.

PartialMerge(ReadOnlySpan<byte>, MergeOperands, IBufferWriter<byte>)

Optional partial merge, without copying the operands or the result.

public virtual bool PartialMerge(ReadOnlySpan<byte> key, MergeOperands operands, IBufferWriter<byte> newValue)

Parameters

key ReadOnlySpan<byte>

The key being merged. Valid for the duration of the call.

operands MergeOperands

The operands to combine, oldest first, read in place.

newValue IBufferWriter<byte>

Where to write the combined operand. Valid only for the duration of the call.

Returns

bool

true if the operands were combined; false to leave it to FullMerge.

Remarks

The default calls the array form, as for FullMerge.

PartialMerge(ReadOnlySpan<byte>, IReadOnlyList<byte[]>, out byte[]?)

Optional partial merge: combines a subset of operands before a full merge. Return false to fall back to FullMerge.

public virtual bool PartialMerge(ReadOnlySpan<byte> key, IReadOnlyList<byte[]> operands, out byte[]? newValue)

Parameters

key ReadOnlySpan<byte>

The key being merged.

operands IReadOnlyList<byte[]>

The operands to combine, in chronological order. Managed copies, so they may be kept beyond the call.

newValue byte[]

Output: the combined operand.

Returns

bool

true if the operands were combined; false to leave it to FullMerge.