Table of Contents

Class RocksDb

Namespace
RocksDbNet
Assembly
RocksDb.Net.dll

A RocksDb embedded key-value database. Thread-safe: all operations may be called concurrently from multiple threads.

public sealed class RocksDb : RocksDbHandle, IDisposable
Inheritance
RocksDb
Implements
Inherited Members

Properties

ColumnFamilyNames

Names of the column families this database knows about.

public IReadOnlyCollection<string> ColumnFamilyNames { get; }

Property Value

IReadOnlyCollection<string>

Remarks

The default family is always in here, whether or not it was named when the database was opened. It used to drop out: the backing dictionary is empty for a database opened without an explicit family list, so the default name was reported only while the dictionary stayed empty, and creating a family afterwards replaced it in the listing rather than adding to it. The family still existed and GetColumnFamily(string) still resolved it, so the listing disagreed with the lookup — including in the "Known families" message that lookup throws.

IsEmpty

Returns true when RocksDb's estimated key count is zero. An estimate, and one that can read zero for a database that still holds keys.

public bool IsEmpty { get; }

Property Value

bool

Remarks

RocksDb computes the estimate as the entry count minus twice the deletion count, clamped at zero. The doubling is there because a deletion is itself an entry, so it usually cancels out and the estimate is close to right. It stops cancelling when keys are deleted that were never present: each such deletion subtracts two from the estimate while removing nothing, and enough of them drive it to zero while the real keys are all still there.

Measured, so it is not hypothetical: 100 keys written and flushed, then 100 deletions of keys that never existed, and this property reports empty while every one of the 100 keys still reads back. Treat it as a cheap hint and iterate when you need an answer you can rely on.

LatestSequenceNumber

Returns the latest sequence number (write counter) for the database.

public ulong LatestSequenceNumber { get; }

Property Value

ulong

Methods

ApproximateSizes(ColumnFamilyHandle, SizeApproximationOptions, IEnumerable<(string Start, string Limit)>)

Returns approximate size information for one or more key ranges in a specific column family, with control over what the estimate includes.

public ulong[] ApproximateSizes(ColumnFamilyHandle cf, SizeApproximationOptions options, IEnumerable<(string Start, string Limit)> ranges)

Parameters

cf ColumnFamilyHandle
options SizeApproximationOptions
ranges IEnumerable<(string Start, string Limit)>

Returns

ulong[]

ApproximateSizes(ColumnFamilyHandle, IEnumerable<(string Start, string Limit)>)

Returns approximate size information for one or more key ranges in a specific column family.

public ulong[] ApproximateSizes(ColumnFamilyHandle cf, IEnumerable<(string Start, string Limit)> ranges)

Parameters

cf ColumnFamilyHandle
ranges IEnumerable<(string Start, string Limit)>

Returns

ulong[]

ApproximateSizes(SizeApproximationOptions, IEnumerable<(string Start, string Limit)>)

Returns approximate size information for one or more key ranges, with control over what the estimate includes.

public ulong[] ApproximateSizes(SizeApproximationOptions options, IEnumerable<(string Start, string Limit)> ranges)

Parameters

options SizeApproximationOptions
ranges IEnumerable<(string Start, string Limit)>

Returns

ulong[]

ApproximateSizes(IEnumerable<(string Start, string Limit)>)

Returns approximate size information for one or more key ranges.

public ulong[] ApproximateSizes(IEnumerable<(string Start, string Limit)> ranges)

Parameters

ranges IEnumerable<(string Start, string Limit)>

Returns

ulong[]

CancelAllBackgroundWork(bool)

Stops the background flush and compaction threads.

public void CancelAllBackgroundWork(bool wait = false)

Parameters

wait bool

When true, blocks until the running jobs finish. When false, signals them to stop and returns.

Remarks

This is a one-way door, not a pause. It puts the database into the same state as the start of a close, so afterwards reads still work and SetOptions(IEnumerable<KeyValuePair<string, string>>) still works, but any operation needing background threads fails with "Shutdown in progress". Flush(FlushOptions?) is the one callers hit.

To suspend background work temporarily and resume it, use PauseBackgroundWork() and ContinueBackgroundWork() instead.

CompactFiles(ColumnFamilyHandle, CompactFilesOptions?, IReadOnlyList<string>, int, int)

Compacts an explicit list of files in a specific column family.

public string[] CompactFiles(ColumnFamilyHandle cf, CompactFilesOptions? options, IReadOnlyList<string> inputFileNames, int outputLevel, int outputPathId = 0)

Parameters

cf ColumnFamilyHandle
options CompactFilesOptions
inputFileNames IReadOnlyList<string>
outputLevel int
outputPathId int

Returns

string[]

CompactFiles(CompactFilesOptions?, IReadOnlyList<string>, int, out CompactionJobInfo?, int)

Compacts an explicit list of files and also reports what the compaction did, through jobInfo.

public string[] CompactFiles(CompactFilesOptions? options, IReadOnlyList<string> inputFileNames, int outputLevel, out CompactionJobInfo? jobInfo, int outputPathId = 0)

Parameters

options CompactFilesOptions
inputFileNames IReadOnlyList<string>
outputLevel int
jobInfo CompactionJobInfo
outputPathId int

Returns

string[]

Remarks

This is the only way to obtain a fully populated CompactionJobInfo synchronously. An EventListener gets the same information, but only when RocksDb happens to fire the event.

CompactFiles(CompactFilesOptions?, IReadOnlyList<string>, int, int)

Compacts an explicit list of files into outputLevel, and returns the names of the files produced.

public string[] CompactFiles(CompactFilesOptions? options, IReadOnlyList<string> inputFileNames, int outputLevel, int outputPathId = 0)

Parameters

options CompactFilesOptions

Compaction settings, or null for RocksDb's defaults.

inputFileNames IReadOnlyList<string>

File names as reported by GetLiveFiles(), or by the input and output lists on CompactionJobInfo.

outputLevel int

The level to write the results into.

outputPathId int

Index into the configured database paths, for a database spread over several. 0 for the usual single-path case.

Returns

string[]

Remarks

Unlike CompactRange(ReadOnlySpan<byte>, ReadOnlySpan<byte>) this names the files itself, so the caller controls exactly what gets rewritten. RocksDb rejects a set of files it cannot legally compact together.

CompactRange(ColumnFamilyHandle, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Triggers compaction on a specific column family.

public void CompactRange(ColumnFamilyHandle cf, ReadOnlySpan<byte> startKey = default, ReadOnlySpan<byte> limitKey = default)

Parameters

cf ColumnFamilyHandle
startKey ReadOnlySpan<byte>
limitKey ReadOnlySpan<byte>

CompactRange(CompactRangeOptions, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Triggers compaction on the key range [startKey, limitKey) using the given options.

public void CompactRange(CompactRangeOptions options, ReadOnlySpan<byte> startKey = default, ReadOnlySpan<byte> limitKey = default)

Parameters

options CompactRangeOptions
startKey ReadOnlySpan<byte>
limitKey ReadOnlySpan<byte>

Remarks

Omitting both bounds, or passing empty spans, compacts the whole key-space. An empty startKey means "from the first key" and an empty limitKey means "to the last".

CompactRange(ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Triggers compaction on the key range [startKey, limitKey).

public void CompactRange(ReadOnlySpan<byte> startKey = default, ReadOnlySpan<byte> limitKey = default)

Parameters

startKey ReadOnlySpan<byte>
limitKey ReadOnlySpan<byte>

ContinueBackgroundWork()

Undoes one PauseBackgroundWork(), letting flushes and compactions run again once every pause has been matched.

public void ContinueBackgroundWork()

CreateColumnFamilies(DbOptions, IReadOnlyList<string>)

Creates several column families in one call.

public IReadOnlyList<ColumnFamilyHandle> CreateColumnFamilies(DbOptions options, IReadOnlyList<string> names)

Parameters

options DbOptions

Options applied to every family created here.

names IReadOnlyList<string>

Names for the new families. None may already exist.

Returns

IReadOnlyList<ColumnFamilyHandle>

The handles, in the same order as names.

Remarks

Cheaper than a call each, because RocksDb writes one manifest record rather than one per family. The handles are registered like any other, so GetColumnFamily(string) finds them and the database disposes them.

CreateColumnFamily(DbOptions, string)

Creates a new column family and returns a handle to it.

public ColumnFamilyHandle CreateColumnFamily(DbOptions options, string name)

Parameters

options DbOptions
name string

Returns

ColumnFamilyHandle

CreateColumnFamilyWithImport(string, DbOptions, ExportImportFilesMetadata, ImportColumnFamilyOptions?)

Creates a column family from files previously exported with ExportColumnFamily(ColumnFamilyHandle, string).

public ColumnFamilyHandle CreateColumnFamilyWithImport(string name, DbOptions options, ExportImportFilesMetadata metadata, ImportColumnFamilyOptions? importOptions = null)

Parameters

name string

Name for the new column family. It must not already exist.

options DbOptions

Options for the new column family.

metadata ExportImportFilesMetadata

Metadata returned by the export.

importOptions ImportColumnFamilyOptions

How the files are taken from the export directory, or null to copy them.

Returns

ColumnFamilyHandle

Remarks

The receiving column family must use the same comparator the export was written with, since the files are ordered by it, and the files must still be where the metadata says they are.

The returned handle is registered like any other, so GetColumnFamily(string) finds it and the database disposes it.

CreateColumnFamilyWithTtl(DbOptions, string, int)

Creates a new column family with TTL.

public ColumnFamilyHandle CreateColumnFamilyWithTtl(DbOptions options, string name, int ttlSeconds)

Parameters

options DbOptions
name string
ttlSeconds int

Returns

ColumnFamilyHandle

Delete(ReadOnlySpan<byte>, ColumnFamilyHandle, WriteOptions?)

Deletes the entry for key from cf.

public void Delete(ReadOnlySpan<byte> key, ColumnFamilyHandle cf, WriteOptions? options = null)

Parameters

key ReadOnlySpan<byte>
cf ColumnFamilyHandle
options WriteOptions

Delete(ReadOnlySpan<byte>, WriteOptions?)

Deletes the entry for key from the default column family.

public void Delete(ReadOnlySpan<byte> key, WriteOptions? options = null)

Parameters

key ReadOnlySpan<byte>
options WriteOptions

Delete(string, ColumnFamilyHandle, WriteOptions?)

Convenience overload using a UTF-8 string key in a column family.

public void Delete(string key, ColumnFamilyHandle cf, WriteOptions? options = null)

Parameters

key string
cf ColumnFamilyHandle
options WriteOptions

Delete(string, WriteOptions?)

Convenience overload using a UTF-8 string key.

public void Delete(string key, WriteOptions? options = null)

Parameters

key string
options WriteOptions

DeleteFilesInRange(ColumnFamilyHandle, string, string)

Deletes whole SST files that lie entirely within the given key range, in the given column family.

public void DeleteFilesInRange(ColumnFamilyHandle cf, string startKey, string limitKey)

Parameters

cf ColumnFamilyHandle
startKey string
limitKey string

Remarks

Carries the same caveats as DeleteFilesInRange(string, string): keys in deleted files are lost outright, partially covered files are left alone, and level 0 is never touched.

DeleteFilesInRange(string, string)

Deletes whole SST files that lie entirely within the given key range, in the default column family.

public void DeleteFilesInRange(string startKey, string limitKey)

Parameters

startKey string
limitKey string

Remarks

This deletes files, not keys, and it is not a substitute for deleting keys. Two consequences follow, and both tend to surprise callers.

Keys inside a deleted file are gone, with no tombstone and no way to recover them. Keys inside the range that happen to live in a file which also extends outside the range stay, because that file is not fully contained and so is left alone.

Level 0 files are never deleted, whatever the range. Data still in level 0 therefore survives this call; run CompactRange(ReadOnlySpan<byte>, ReadOnlySpan<byte>) first if it needs to be considered.

Snapshots taken before this call may not see the deleted data.

DeleteRange(ReadOnlySpan<byte>, ReadOnlySpan<byte>, ColumnFamilyHandle, WriteOptions?)

Deletes all keys in the range [startKey, endKey) from cf.

public void DeleteRange(ReadOnlySpan<byte> startKey, ReadOnlySpan<byte> endKey, ColumnFamilyHandle cf, WriteOptions? options = null)

Parameters

startKey ReadOnlySpan<byte>
endKey ReadOnlySpan<byte>
cf ColumnFamilyHandle
options WriteOptions

DeleteRange(ReadOnlySpan<byte>, ReadOnlySpan<byte>, WriteOptions?)

Deletes all keys in the range [startKey, endKey) from the default column family.

public void DeleteRange(ReadOnlySpan<byte> startKey, ReadOnlySpan<byte> endKey, WriteOptions? options = null)

Parameters

startKey ReadOnlySpan<byte>
endKey ReadOnlySpan<byte>
options WriteOptions

Remarks

The DeleteRange API is more efficient than issuing individual deletes for each key in the range, but it does not immediately remove the keys from storage. Instead, it adds a range tombstone that marks the keys as deleted. The actual removal of the keys happens during compaction, so the space is not reclaimed until then. Also, range tombstones can affect read performance for keys in the deleted range until compaction occurs. Use DeleteRange when you need to delete large contiguous ranges of keys and can tolerate the delayed cleanup and potential read performance impact.

Destroy(DbOptions, string)

Destroys the database files at path. Irreversible.

public static void Destroy(DbOptions options, string path)

Parameters

options DbOptions
path string

DisableFileDeletions()

Stops RocksDb from deleting obsolete files, so that a consistent set of files stays on disk while something outside the database copies them.

public void DisableFileDeletions()

Remarks

This is the primitive behind external backup tools. Compactions and flushes carry on and keep producing new files; what stops is the cleanup of the files they supersede, so disk usage grows until deletions are enabled again.

Always pair this with EnableFileDeletions(), which performs the deferred cleanup. A database left with deletions disabled never reclaims space.

DisableManualCompaction()

Stops manual compactions from running, and cancels any in progress.

public void DisableManualCompaction()

Remarks

Narrower than PauseBackgroundWork(), which stops automatic work too. This leaves automatic compaction alone and only refuses the explicit kind, which is useful while something else needs the disk.

Reversible, unlike CancelAllBackgroundWork(bool): call EnableManualCompaction() to allow them again.

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

DisposeUnmanagedResources()

Releases unmanaged resources used by the current instance.

protected override void DisposeUnmanagedResources()

Remarks

Protected for the same reason as DisposeHandle().

DropColumnFamily(ColumnFamilyHandle)

Drops cf from the database. The handle is invalidated after this call.

public void DropColumnFamily(ColumnFamilyHandle cf)

Parameters

cf ColumnFamilyHandle

EnableFileDeletions()

Re-enables file deletions after DisableFileDeletions(), and deletes the obsolete files that accumulated in the meantime.

public void EnableFileDeletions()

EnableManualCompaction()

Allows manual compactions again after DisableManualCompaction().

public void EnableManualCompaction()

Flush(ColumnFamilyHandle, FlushOptions?)

Flushes the specified column family.

public void Flush(ColumnFamilyHandle cf, FlushOptions? options = null)

Parameters

cf ColumnFamilyHandle
options FlushOptions

Flush(FlushOptions?)

Flushes the memtable of the "default" column family to storage.

public void Flush(FlushOptions? options = null)

Parameters

options FlushOptions

Remarks

The default family only, despite taking no column family argument. The native call this maps to targets the default family, so other families keep their unflushed memtables. To flush several, pass them to Flush(IReadOnlyList<ColumnFamilyHandle>, FlushOptions?).

Flush(IReadOnlyList<ColumnFamilyHandle>, FlushOptions?)

Flushes the specified column families.

public void Flush(IReadOnlyList<ColumnFamilyHandle> columnFamilies, FlushOptions? options = null)

Parameters

columnFamilies IReadOnlyList<ColumnFamilyHandle>
options FlushOptions

Remarks

An empty list flushes nothing, which is what RocksDb does with an empty list of handles. This used to fall through to flushing the "default" family instead, so a caller filtering a list down to nothing flushed a family they had not asked for.

FlushWal(FlushWalOptions)

Flushes the WAL buffer to disk, with control over the rate limiter priority as well as syncing.

public void FlushWal(FlushWalOptions options)

Parameters

options FlushWalOptions

FlushWal(bool)

Flushes the WAL buffer to disk.

public void FlushWal(bool sync)

Parameters

sync bool

Whether to fsync the file as well. Flushing without syncing hands the buffer to the operating system and nothing more, so it survives the process dying but not the machine.

Remarks

There is no default. There used to be one on each of the two databases and they disagreed: RocksDb defaulted to false and FlushWal(bool) to true, so the same call spelled the same way meant different durability depending on the type it was made on. Rather than pick a winner and silently change what one set of callers gets, both now require the argument.

Get(ReadOnlySpan<byte>, ColumnFamilyHandle, ReadOptions?)

Returns the value for key in cf, or null.

public byte[]? Get(ReadOnlySpan<byte> key, ColumnFamilyHandle cf, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>
cf ColumnFamilyHandle
options ReadOptions

Returns

byte[]

Get(ReadOnlySpan<byte>, ReadOptions?)

Returns the value associated with key in the default column family, or null if the key does not exist.

public byte[]? Get(ReadOnlySpan<byte> key, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>
options ReadOptions

Returns

byte[]

Get(string, ReadOptions?)

Returns the value for a string key, or null if not found.

public byte[]? Get(string key, ReadOptions? options = null)

Parameters

key string
options ReadOptions

Returns

byte[]

GetAggregatedPropertyInt(string)

Returns an integer property summed over every column family, rather than the default family's value alone.

public ulong? GetAggregatedPropertyInt(string propName)

Parameters

propName string

Returns

ulong?

Remarks

GetPropertyInt(string) reads the default column family, so it describes the whole database only when the database has one family. On a database with several, asking for the estimated key count that way reports the keys in default and silently omits the rest.

This is RocksDb's GetAggregatedIntProperty, which its header describes as "same as GetIntProperty(), but this one returns the aggregated int property from all column families". The C API does not export it, so the sum is done here, over ColumnFamilyNames — which covers families created since the database was opened as well as those opened with it.

Null when any family has no value for the property, which is the answer GetPropertyInt(string) gives for a property that is not an integer property. A partial sum is not returned: a total missing one of its terms is not a total, and returning one would be indistinguishable from a database that genuinely held that much.

Only meaningful for a property that is itself a total. Summing rocksdb.estimate-num-keys over the families gives the database's estimated key count; summing rocksdb.actual-delayed-write-rate gives a number that is not a rate anything has. RocksDb does not distinguish the two either, so neither does this.

GetColumnFamily(string)

Returns the handle for the column family called name.

public ColumnFamilyHandle GetColumnFamily(string name)

Parameters

name string

Returns

ColumnFamilyHandle

Remarks

Covers families opened with the database and families created since, through CreateColumnFamily(DbOptions, string) or CreateColumnFamilyWithTtl(DbOptions, string, int).

Exceptions

KeyNotFoundException

No column family of that name is known to this database. Previously this returned null from a non-nullable signature, so the mistake surfaced as a NullReferenceException somewhere else. Use TryGetColumnFamily(string, out ColumnFamilyHandle?) when absence is expected.

GetColumnFamilyMetadata()

Returns metadata for the default column family.

public ColumnFamilyMetadata? GetColumnFamilyMetadata()

Returns

ColumnFamilyMetadata

GetColumnFamilyMetadata(ColumnFamilyHandle)

Returns metadata for cf.

public ColumnFamilyMetadata? GetColumnFamilyMetadata(ColumnFamilyHandle cf)

Parameters

cf ColumnFamilyHandle

Returns

ColumnFamilyMetadata

GetColumnFamilyMetadata(ColumnFamilyHandle, ColumnFamilyMetadataOptions)

Returns metadata for cf, restricted to the level and key range in options.

public ColumnFamilyMetadata? GetColumnFamilyMetadata(ColumnFamilyHandle cf, ColumnFamilyMetadataOptions options)

Parameters

cf ColumnFamilyHandle
options ColumnFamilyMetadataOptions

Returns

ColumnFamilyMetadata

GetColumnFamilyMetadata(ColumnFamilyMetadataOptions)

Returns metadata for the default column family, restricted to the level and key range in options.

public ColumnFamilyMetadata? GetColumnFamilyMetadata(ColumnFamilyMetadataOptions options)

Parameters

options ColumnFamilyMetadataOptions

Returns

ColumnFamilyMetadata

GetCurrentWalFile()

Returns the write-ahead log file currently being written to.

public WalFile? GetCurrentWalFile()

Returns

WalFile

GetDbIdentity()

Returns the unique identity of this database instance.

public string GetDbIdentity()

Returns

string

GetDefaultColumnFamily()

Returns a non-owning wrapper around the default column family handle. Do not call Dispose on the returned handle — its lifetime is managed by the database.

public ColumnFamilyHandle GetDefaultColumnFamily()

Returns

ColumnFamilyHandle

GetLiveFiles()

Returns metadata about the currently live SST files in the database.

public IReadOnlyList<LiveFileMetadata> GetLiveFiles()

Returns

IReadOnlyList<LiveFileMetadata>

Remarks

Read in full before returning, so the result needs no disposal and stays valid for as long as you hold it. It used to hand back a disposable container whose elements read through it on every property access, which meant they were only valid while it was alive.

GetLiveFilesStorageInfo(LiveFilesStorageInfoOptions?)

Returns a consistent snapshot of every live file, described in enough detail to copy the database elsewhere.

public IReadOnlyList<LiveFileStorageInfo> GetLiveFilesStorageInfo(LiveFilesStorageInfoOptions? options = null)

Parameters

options LiveFilesStorageInfoOptions

Settings for the call, or null for RocksDb's defaults.

Returns

IReadOnlyList<LiveFileStorageInfo>

Remarks

More useful than GetLiveFiles() for building a backup by hand: each entry carries the target filename, the live byte count, the storage temperature, optionally a checksum, and for small metadata files the content to write rather than copy.

This flushes memtables by default, because WalSizeForFlush defaults to 0, meaning "always flush". Raise it to avoid that.

GetPinned(ReadOnlySpan<byte>, ColumnFamilyHandle, ReadOptions?)

Reads the value for key without copying it into managed memory, or returns null if the key is absent.

public PinnableSlice? GetPinned(ReadOnlySpan<byte> key, ColumnFamilyHandle cf, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>
cf ColumnFamilyHandle
options ReadOptions

Returns

PinnableSlice

Remarks

Dispose the result promptly: it pins the block the value came from, which cannot be evicted from the block cache while it lives. See PinnableSlice.

GetPinned(ReadOnlySpan<byte>, ReadOptions?)

Reads the value for key without copying it into managed memory, or returns null if the key is absent.

public PinnableSlice? GetPinned(ReadOnlySpan<byte> key, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>
options ReadOptions

Returns

PinnableSlice

Remarks

Dispose the result promptly: it pins the block the value came from, which cannot be evicted from the block cache while it lives. See PinnableSlice.

GetProperty(string)

Returns the value of an internal property (e.g. "rocksdb.stats"), or null if the property is unknown.

public string? GetProperty(string propName)

Parameters

propName string

Returns

string

GetProperty(string, ColumnFamilyHandle)

Returns a string property for a specific column family.

public string? GetProperty(string propName, ColumnFamilyHandle cf)

Parameters

propName string
cf ColumnFamilyHandle

Returns

string

GetPropertyInt(string)

Returns an integer property value, or null if unavailable.

public ulong? GetPropertyInt(string propName)

Parameters

propName string

Returns

ulong?

GetPropertyInt(string, ColumnFamilyHandle)

Returns an integer property for a specific column family.

public ulong? GetPropertyInt(string propName, ColumnFamilyHandle cf)

Parameters

propName string
cf ColumnFamilyHandle

Returns

ulong?

GetSortedWalFiles()

Returns every write-ahead log file RocksDb still retains, oldest first.

public IReadOnlyList<WalFile> GetSortedWalFiles()

Returns

IReadOnlyList<WalFile>

Remarks

Includes both archived logs and the live one. The values are copied out, so nothing here has to be disposed and the result outlives the call.

GetString(string, ColumnFamilyHandle, ReadOptions?)

Convenience overload using a UTF-8 string key in a column family.

public string? GetString(string key, ColumnFamilyHandle cf, ReadOptions? options = null)

Parameters

key string
cf ColumnFamilyHandle
options ReadOptions

Returns

string

GetString(string, ReadOptions?)

Convenience overload using a UTF-8 string key; returns the value as a string or null.

public string? GetString(string key, ReadOptions? options = null)

Parameters

key string
options ReadOptions

Returns

string

GetUpdatesSince(ulong, WalReadOptions?)

Returns an iterator over write-ahead log records written at or after sequenceNumber.

public WalIterator GetUpdatesSince(ulong sequenceNumber, WalReadOptions? options = null)

Parameters

sequenceNumber ulong

Where to start. Inclusive: the batch containing this sequence number is returned, so passing LatestSequenceNumber replays the most recent write again. To resume after a known point, pass one more than the last sequence number already consumed. Zero means the oldest record still retained.

options WalReadOptions

Read options for the log, or null for the defaults.

Returns

WalIterator

Remarks

The basis for replication and change-data-capture: each step yields the batch that was written and the sequence number it started at. Read what is inside a batch with Entries().

Only records still in the write-ahead log are visible, so a sequence number older than the oldest retained log fails rather than returning nothing.

Exceptions

RocksDbException

The requested sequence number is no longer available, or reading the log failed.

IngestExternalFile(IReadOnlyList<string>, ColumnFamilyHandle, IngestExternalFileOptions)

Ingests a list of pre-built SST files into cf.

public void IngestExternalFile(IReadOnlyList<string> filePaths, ColumnFamilyHandle cf, IngestExternalFileOptions options)

Parameters

filePaths IReadOnlyList<string>
cf ColumnFamilyHandle
options IngestExternalFileOptions

IngestExternalFile(IReadOnlyList<string>, IngestExternalFileOptions)

Ingests a list of pre-built SST files into the default column family.

public void IngestExternalFile(IReadOnlyList<string> filePaths, IngestExternalFileOptions options)

Parameters

filePaths IReadOnlyList<string>
options IngestExternalFileOptions

KeyMayExist(ReadOnlySpan<byte>, ColumnFamilyHandle, ReadOptions?)

Returns true if the key may exist in cf (Bloom-filter optimized). A false result guarantees the key is absent; a true result requires a real Get to confirm existence.

public bool KeyMayExist(ReadOnlySpan<byte> key, ColumnFamilyHandle cf, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>
cf ColumnFamilyHandle
options ReadOptions

Returns

bool

KeyMayExist(ReadOnlySpan<byte>, ReadOptions?)

Returns true if the key may exist (Bloom-filter optimized). A false result guarantees the key is absent; a true result requires a real Get to confirm existence.

public bool KeyMayExist(ReadOnlySpan<byte> key, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>
options ReadOptions

Returns

bool

KeyMayExist(string, ColumnFamilyHandle, ReadOptions?)

Returns true if the UTF-8 encoded key may exist in cf.

public bool KeyMayExist(string key, ColumnFamilyHandle cf, ReadOptions? options = null)

Parameters

key string
cf ColumnFamilyHandle
options ReadOptions

Returns

bool

KeyMayExist(string, ReadOptions?)

Returns true if the UTF-8 encoded key may exist.

public bool KeyMayExist(string key, ReadOptions? options = null)

Parameters

key string
options ReadOptions

Returns

bool

ListColumnFamilies(DbOptions, string)

Lists the column family names present in the database at path.

public static IReadOnlyList<string> ListColumnFamilies(DbOptions options, string path)

Parameters

options DbOptions
path string

Returns

IReadOnlyList<string>

Merge(ReadOnlySpan<byte>, ReadOnlySpan<byte>, ColumnFamilyHandle, WriteOptions?)

Applies a merge operation to key in cf.

public void Merge(ReadOnlySpan<byte> key, ReadOnlySpan<byte> value, ColumnFamilyHandle cf, WriteOptions? options = null)

Parameters

key ReadOnlySpan<byte>
value ReadOnlySpan<byte>
cf ColumnFamilyHandle
options WriteOptions

Merge(ReadOnlySpan<byte>, ReadOnlySpan<byte>, WriteOptions?)

Applies a merge operation to key in the default column family.

public void Merge(ReadOnlySpan<byte> key, ReadOnlySpan<byte> value, WriteOptions? options = null)

Parameters

key ReadOnlySpan<byte>
value ReadOnlySpan<byte>
options WriteOptions

Merge(string, string, ColumnFamilyHandle, WriteOptions?)

Applies a merge operation to key in cf.

public void Merge(string key, string value, ColumnFamilyHandle cf, WriteOptions? options = null)

Parameters

key string
value string
cf ColumnFamilyHandle
options WriteOptions

Merge(string, string, WriteOptions?)

Applies a merge operation to key in the default column family.

public void Merge(string key, string value, WriteOptions? options = null)

Parameters

key string
value string
options WriteOptions

MultiGet(IReadOnlyList<byte[]>, ColumnFamilyHandle, ReadOptions?)

Reads several keys from cf in one call.

public byte[]?[] MultiGet(IReadOnlyList<byte[]> keys, ColumnFamilyHandle cf, ReadOptions? options = null)

Parameters

keys IReadOnlyList<byte[]>
cf ColumnFamilyHandle
options ReadOptions

Returns

byte[][]

Remarks

A missing key yields null in the corresponding position, so the result always has one entry per key.

MultiGet(IReadOnlyList<byte[]>, ReadOptions?)

Reads several keys from the default column family in one call.

public byte[]?[] MultiGet(IReadOnlyList<byte[]> keys, ReadOptions? options = null)

Parameters

keys IReadOnlyList<byte[]>
options ReadOptions

Returns

byte[][]

Remarks

A missing key yields null in the corresponding position, so the result always has one entry per key.

MultiGet(IReadOnlyList<byte[]>, IReadOnlyList<ColumnFamilyHandle>, ReadOptions?)

Reads several keys in one call, each from the column family at the same position in columnFamilies.

public byte[]?[] MultiGet(IReadOnlyList<byte[]> keys, IReadOnlyList<ColumnFamilyHandle> columnFamilies, ReadOptions? options = null)

Parameters

keys IReadOnlyList<byte[]>
columnFamilies IReadOnlyList<ColumnFamilyHandle>
options ReadOptions

Returns

byte[][]

Remarks

The reason this overload exists: RocksDb takes one column family per key, so a caller can fetch across several families in a single round trip. Restricting the API to one family per call would throw that away.

Two parallel lists rather than a list of pairs, because a second list-shaped overload would make MultiGet([]) ambiguous at the call site for every existing caller.

A missing key yields null in the corresponding position.

Exceptions

ArgumentException

The two lists are of different lengths.

MultiGetPinned(IReadOnlyList<byte[]>, ColumnFamilyHandle, bool, ReadOptions?)

Reads several keys from cf in one call, without copying the values into managed memory.

public PinnableSlice?[] MultiGetPinned(IReadOnlyList<byte[]> keys, ColumnFamilyHandle cf, bool sortedInput = false, ReadOptions? options = null)

Parameters

keys IReadOnlyList<byte[]>

The keys to read.

cf ColumnFamilyHandle

The column family to read from.

sortedInput bool

Set this when keys is already in the database's sort order, which lets RocksDb skip sorting them. Passing true for unsorted keys gives wrong results, so leave it alone unless the order is guaranteed.

options ReadOptions

Read options, or null for the defaults.

Returns

PinnableSlice[]

One entry per key, null where the key was absent. Every non-null entry must be disposed; see PinnableSlice.

Remarks

The batched counterpart to GetPinned(ReadOnlySpan<byte>, ColumnFamilyHandle, ReadOptions?). It avoids a copy per key, which is what makes it worth the disposal burden on a large batch. RocksDb offers this only per column family, so there is no cross-family or default-family overload.

NewIterator(ColumnFamilyHandle, ReadOptions?)

Creates a new iterator over cf.

public Iterator NewIterator(ColumnFamilyHandle cf, ReadOptions? options = null)

Parameters

cf ColumnFamilyHandle
options ReadOptions

Returns

Iterator

NewIterator(ReadOptions?)

Creates a new iterator over the default column family.

public Iterator NewIterator(ReadOptions? options = null)

Parameters

options ReadOptions

Returns

Iterator

NewIterators(IReadOnlyList<ColumnFamilyHandle>, ReadOptions?)

Creates one iterator per column family, all sharing a single consistent view of the database.

public IReadOnlyList<Iterator> NewIterators(IReadOnlyList<ColumnFamilyHandle> columnFamilies, ReadOptions? options = null)

Parameters

columnFamilies IReadOnlyList<ColumnFamilyHandle>

The families to iterate.

options ReadOptions

Read options, or null for the defaults.

Returns

IReadOnlyList<Iterator>

The iterators, in the same order as columnFamilies.

Remarks

This is the difference that matters: opening iterators one at a time gives no guarantee they see the same state, so a write landing between two calls is visible to one iterator and not the other. Created together, they all see the same point in time.

Dispose every returned iterator. If the call fails, none are created.

NewSnapshot()

Creates an immutable snapshot of the current DB state. The snapshot must be disposed before the database is closed.

public Snapshot NewSnapshot()

Returns

Snapshot

Open(DbOptions, string)

Opens (or creates) a database at path.

public static RocksDb Open(DbOptions options, string path)

Parameters

options DbOptions
path string

Returns

RocksDb

Remarks

The returned database takes ownership of options and disposes it when the database is disposed. Do not dispose it yourself and do not reuse it for a second open.

Open(DbOptions, string, IReadOnlyList<ColumnFamilyDescriptor>)

Opens the database with an explicit set of column families. The "default" column family must always be included.

public static RocksDb Open(DbOptions options, string path, IReadOnlyList<ColumnFamilyDescriptor> columnFamilies)

Parameters

options DbOptions
path string
columnFamilies IReadOnlyList<ColumnFamilyDescriptor>

Returns

RocksDb

Remarks

Returns the database only. The handles are registered internally rather than returned, so reach them with GetColumnFamily(string); the database disposes them for you.

The returned database takes ownership of options and disposes it when the database is disposed.

OpenAsSecondary(DbOptions, string, string)

Opens the database as a secondary instance that can catch up to the primary.

public static RocksDb OpenAsSecondary(DbOptions options, string path, string secondaryPath)

Parameters

options DbOptions
path string
secondaryPath string

Returns

RocksDb

OpenReadOnly(DbOptions, string, bool)

Opens an existing database in read-only mode.

public static RocksDb OpenReadOnly(DbOptions options, string path, bool errorIfWalExists = false)

Parameters

options DbOptions
path string
errorIfWalExists bool

Returns

RocksDb

Remarks

The returned database takes ownership of options and disposes it when the database is disposed.

OpenReadOnly(DbOptions, string, IReadOnlyList<ColumnFamilyDescriptor>, bool)

Opens an existing database in read-only mode with an explicit set of column families. The "default" column family must always be included.

public static RocksDb OpenReadOnly(DbOptions options, string path, IReadOnlyList<ColumnFamilyDescriptor> columnFamilies, bool errorIfWalExists = false)

Parameters

options DbOptions
path string
columnFamilies IReadOnlyList<ColumnFamilyDescriptor>
errorIfWalExists bool

Returns

RocksDb

Remarks

Returns the database only; reach the handles with GetColumnFamily(string). The returned database takes ownership of options and disposes it.

OpenWithTtl(DbOptions, string, int)

Opens the database with a TTL (time-to-live) compaction filter.

public static RocksDb OpenWithTtl(DbOptions options, string path, int ttlSeconds)

Parameters

options DbOptions
path string
ttlSeconds int

Returns

RocksDb

PauseBackgroundWork()

Stops RocksDb starting new flushes and compactions, and waits for the ones already running to finish.

public void PauseBackgroundWork()

Remarks

Writes continue to be accepted, so pausing for long enough will build up memtables and eventually stall the writer. Calls nest: each PauseBackgroundWork() needs a matching ContinueBackgroundWork() before work resumes.

Put(ReadOnlySpan<byte>, ReadOnlySpan<byte>, ColumnFamilyHandle, WriteOptions?)

Stores value under key in cf.

public void Put(ReadOnlySpan<byte> key, ReadOnlySpan<byte> value, ColumnFamilyHandle cf, WriteOptions? options = null)

Parameters

key ReadOnlySpan<byte>
value ReadOnlySpan<byte>
cf ColumnFamilyHandle
options WriteOptions

Put(ReadOnlySpan<byte>, ReadOnlySpan<byte>, WriteOptions?)

Stores value under key in the default column family.

public void Put(ReadOnlySpan<byte> key, ReadOnlySpan<byte> value, WriteOptions? options = null)

Parameters

key ReadOnlySpan<byte>
value ReadOnlySpan<byte>
options WriteOptions

Put(string, string, ColumnFamilyHandle, WriteOptions?)

Convenience overload using UTF-8 string key and value in a column family.

public void Put(string key, string value, ColumnFamilyHandle cf, WriteOptions? options = null)

Parameters

key string
value string
cf ColumnFamilyHandle
options WriteOptions

Put(string, string, WriteOptions?)

Convenience overload using UTF-8 string key and value.

public void Put(string key, string value, WriteOptions? options = null)

Parameters

key string
value string
options WriteOptions

Repair(DbOptions, string)

Attempts to repair a damaged database at path.

public static void Repair(DbOptions options, string path)

Parameters

options DbOptions
path string

SetDbOptions(IEnumerable<KeyValuePair<string, string>>)

Applies one or more database-wide runtime options.

public void SetDbOptions(IEnumerable<KeyValuePair<string, string>> options)

Parameters

options IEnumerable<KeyValuePair<string, string>>

Remarks

This is the counterpart to SetOptions(IEnumerable<KeyValuePair<string, string>>) for options that live on the database rather than on a column family, and it is the only way to change them after the database is open. Most DbOptions values are read once at open time and ignored afterwards.

SetOptions(ColumnFamilyHandle, IEnumerable<KeyValuePair<string, string>>)

Applies one or more runtime options to a specific column family.

public void SetOptions(ColumnFamilyHandle cf, IEnumerable<KeyValuePair<string, string>> options)

Parameters

cf ColumnFamilyHandle
options IEnumerable<KeyValuePair<string, string>>

SetOptions(IEnumerable<KeyValuePair<string, string>>)

Applies one or more runtime options to the default column family.

public void SetOptions(IEnumerable<KeyValuePair<string, string>> options)

Parameters

options IEnumerable<KeyValuePair<string, string>>

Remarks

Column-family options, not database-wide ones, despite taking no column family: it is the overload below with the default family filled in. Use SetDbOptions(IEnumerable<KeyValuePair<string, string>>) for settings that belong to the database.

SingleDelete(ReadOnlySpan<byte>, ColumnFamilyHandle, WriteOptions?)

Deletes a key that was written exactly once and never updated.

public void SingleDelete(ReadOnlySpan<byte> key, ColumnFamilyHandle cf, WriteOptions? options = null)

Parameters

key ReadOnlySpan<byte>
cf ColumnFamilyHandle
options WriteOptions

Remarks

Cheaper than Delete(ReadOnlySpan<byte>, WriteOptions?), because RocksDb may drop the tombstone and the value together as soon as it meets them, rather than carrying the tombstone down through every level.

Only valid for a key written once. If the key was ever overwritten, merged into, or deleted and rewritten, the result is undefined: an older version may reappear. RocksDb does not detect the misuse, so use ordinary Delete(ReadOnlySpan<byte>, WriteOptions?) unless the write-once property is guaranteed by the application.

SingleDelete(ReadOnlySpan<byte>, WriteOptions?)

Deletes a key that was written exactly once and never updated.

public void SingleDelete(ReadOnlySpan<byte> key, WriteOptions? options = null)

Parameters

key ReadOnlySpan<byte>
options WriteOptions

Remarks

Cheaper than Delete(ReadOnlySpan<byte>, WriteOptions?), because RocksDb may drop the tombstone and the value together as soon as it meets them, rather than carrying the tombstone down through every level.

Only valid for a key written once. If the key was ever overwritten, merged into, or deleted and rewritten, the result is undefined: an older version may reappear. RocksDb does not detect the misuse, so use ordinary Delete(ReadOnlySpan<byte>, WriteOptions?) unless the write-once property is guaranteed by the application.

SingleDelete(string, WriteOptions?)

Deletes a key that was written exactly once and never updated.

public void SingleDelete(string key, WriteOptions? options = null)

Parameters

key string
options WriteOptions

Remarks

Cheaper than Delete(ReadOnlySpan<byte>, WriteOptions?), because RocksDb may drop the tombstone and the value together as soon as it meets them, rather than carrying the tombstone down through every level.

Only valid for a key written once. If the key was ever overwritten, merged into, or deleted and rewritten, the result is undefined: an older version may reappear. RocksDb does not detect the misuse, so use ordinary Delete(ReadOnlySpan<byte>, WriteOptions?) unless the write-once property is guaranteed by the application.

SuggestCompactRange(ColumnFamilyHandle, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Marks the files overlapping the given key range for compaction in the given column family, and asks RocksDb to schedule one.

public void SuggestCompactRange(ColumnFamilyHandle cf, ReadOnlySpan<byte> startKey, ReadOnlySpan<byte> limitKey)

Parameters

cf ColumnFamilyHandle
startKey ReadOnlySpan<byte>
limitKey ReadOnlySpan<byte>

Remarks

Carries the same conditions as SuggestCompactRange(ReadOnlySpan<byte>, ReadOnlySpan<byte>).

SuggestCompactRange(ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Marks the files overlapping the given key range for compaction, and asks RocksDb to schedule one.

public void SuggestCompactRange(ReadOnlySpan<byte> startKey, ReadOnlySpan<byte> limitKey)

Parameters

startKey ReadOnlySpan<byte>
limitKey ReadOnlySpan<byte>

Remarks

A suggestion, not a command. Unlike CompactRange(ReadOnlySpan<byte>, ReadOnlySpan<byte>) this returns immediately and the compaction happens on a background thread, or not at all.

Two conditions have to hold for anything to happen. Auto compactions must be enabled, since a marked file is still only a reason for the automatic picker to act. And only levels below the highest non-empty level are marked, so a database whose data is all in level 0 has nothing to mark.

TryCatchUpWithPrimary()

For secondary instances: catches up with the primary by reading from the WAL.

public void TryCatchUpWithPrimary()

TryGet(ReadOnlySpan<byte>, out byte[]?, ReadOptions?)

Tries to retrieve key. Returns true and sets value if the key exists; otherwise returns false.

public bool TryGet(ReadOnlySpan<byte> key, out byte[]? value, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>
value byte[]
options ReadOptions

Returns

bool

TryGetColumnFamily(string, out ColumnFamilyHandle?)

Looks up the handle for the column family called name, returning false rather than throwing when there is none.

public bool TryGetColumnFamily(string name, out ColumnFamilyHandle? columnFamily)

Parameters

name string
columnFamily ColumnFamilyHandle

Returns

bool

TryGetInto(ReadOnlySpan<byte>, ColumnFamilyHandle, Span<byte>, out int, ReadOptions?)

Reads the value for key into a caller-owned buffer, allocating nothing.

public bool TryGetInto(ReadOnlySpan<byte> key, ColumnFamilyHandle cf, Span<byte> destination, out int valueLength, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>

The key to read.

cf ColumnFamilyHandle
destination Span<byte>

Buffer to copy the value into.

valueLength int

The value's full length when the key was found, whether or not it fitted, so a caller given false can size a buffer and retry. Zero when the key was absent.

options ReadOptions

Read options, or null for the defaults.

Returns

bool

true only when the key was found and the value fitted. false means either the key was absent, which leaves valueLength zero, or the buffer was too small, which sets it to the length required.

Remarks

The counterpart to GetPinned(ReadOnlySpan<byte>, ReadOptions?): this copies once into memory you already own and pins nothing, so there is no lifetime to manage. Prefer it when the values are small or a buffer can be reused across reads.

TryGetInto(ReadOnlySpan<byte>, Span<byte>, out int, ReadOptions?)

Reads the value for key into a caller-owned buffer, allocating nothing.

public bool TryGetInto(ReadOnlySpan<byte> key, Span<byte> destination, out int valueLength, ReadOptions? options = null)

Parameters

key ReadOnlySpan<byte>

The key to read.

destination Span<byte>

Buffer to copy the value into.

valueLength int

The value's full length when the key was found, whether or not it fitted, so a caller given false can size a buffer and retry. Zero when the key was absent.

options ReadOptions

Read options, or null for the defaults.

Returns

bool

true only when the key was found and the value fitted. false means either the key was absent, which leaves valueLength zero, or the buffer was too small, which sets it to the length required.

Remarks

The counterpart to GetPinned(ReadOnlySpan<byte>, ReadOptions?): this copies once into memory you already own and pins nothing, so there is no lifetime to manage. Prefer it when the values are small or a buffer can be reused across reads.

VerifyChecksum()

Reads every live SST and blob file and verifies its block checksums.

public void VerifyChecksum()

Remarks

This reads the whole database, so it is a maintenance operation rather than something to run on a request path. Use VerifyFileChecksums() for the cheaper whole-file check.

Exceptions

RocksDbException

A checksum did not match.

VerifyChecksum(ReadOptions)

Verifies block checksums, using options for the reads it performs.

public void VerifyChecksum(ReadOptions options)

Parameters

options ReadOptions

Exceptions

RocksDbException

A checksum did not match.

VerifyFileChecksums()

Verifies each file's whole-file checksum against the checksum recorded for it in the manifest.

public void VerifyFileChecksums()

Remarks

Cheaper than VerifyChecksum(), but it requires a file checksum generator to have been configured through SetFileChecksumGenFactory(FileChecksumGenFactory). Without one RocksDb has recorded nothing to compare against and fails the call rather than reporting success, so this is not a drop-in substitute.

Exceptions

RocksDbException

A checksum did not match, or no file checksum generator was configured.

VerifyFileChecksums(ReadOptions)

Verifies whole-file checksums, using options for the reads it performs.

public void VerifyFileChecksums(ReadOptions options)

Parameters

options ReadOptions

Exceptions

RocksDbException

A checksum did not match.

WaitForCompact(WaitForCompactOptions?)

Waits for pending compaction work, optionally using custom options.

public void WaitForCompact(WaitForCompactOptions? options = null)

Parameters

options WaitForCompactOptions

Write(WriteBatch, WriteOptions?)

Atomically applies all operations in batch.

public void Write(WriteBatch batch, WriteOptions? options = null)

Parameters

batch WriteBatch
options WriteOptions

Write(WriteBatchWithIndex, WriteOptions?)

Atomically applies all operations in an indexed batch.

public void Write(WriteBatchWithIndex batch, WriteOptions? options = null)

Parameters

batch WriteBatchWithIndex
options WriteOptions

Remarks

Until this existed, a WriteBatchWithIndex could be built and inspected but never applied, which made the type unusable for its purpose. Applying it does not clear it; the batch may be reused or applied again.

Edit this page