Tier 3 API Reference

RocksDBDict{K,V}(path; compression=:zstd, create_if_missing=true, kwargs...)

An AbstractDict{K,V} backed by a RocksDB database. Keys/values that are AbstractString or byte vectors are stored as-is; anything else is (de)serialized with the Julia Serialization stdlib.

Unlike Base.Dict, iteration order is the sorted key order RocksDB stores keys in – a useful bonus, not just an implementation detail.

Keyword arguments accepted here on top of what Options takes: column_family (a String, default "default") and everything RocksDB.opendb/Options accepts (compression, block_cache_size, bloom_bits_per_key, max_open_files, max_background_jobs, env, ...).

Batches

RocksDB.batch(dict) do b
    b["k1"] = "v1"
    b["k2"] = "v2"
end

commits all writes atomically (and not at all if the block throws).

length(d::RocksDBDict)

Approximate key count, via RocksDB's O(1) "rocksdb.estimate-num-keys" property (it can undercount, e.g. for very recently written, not-yet- flushed data). For an exact count, count(Returns(true), d) (which actually iterates) is available like for any other AbstractDict.

batch(f, db::DB; options=db.default_write_options)

do-block convenience: create a WriteBatch, run f on it, and write! it to db – only if f returns normally. If f throws, the batch is discarded and nothing is written (same all-or-nothing guarantee as building a WriteBatch by hand). The RocksDBDict equivalent is RocksDB.batch(f, dict).

db = RocksDB.opendb("mydb")
RocksDB.batch(db) do wb
    put!(wb, "a", "1")
    put!(wb, "b", "2")
end
String(get(db, "a"))   # "1"
close(db)

batch(f, dict::RocksDBDict)

Run f with a batch-like handle supporting b[k] = v and delete!(b, k); all writes are committed atomically when f returns normally, and discarded if f throws.

ColumnFamilies{K,V}(path; column_families=["default"], kwargs...)

An AbstractDict{String,RocksDBDict{K,V}} where each value is a RocksDBDict scoped to one column family of the same underlying RocksDB database at path. All the column families listed in column_families are opened (and must already exist in the database, except "default", which is created automatically if missing).

store = RocksDB.ColumnFamilies("mydb"; column_families=["default", "users", "sessions"])
store["users"]["alice"] = "admin"
store[:sessions]["tok-1"] = "active"
close(store)   # closes the shared DB and every RocksDBDict handed out

Use create_column_family(store, name) to add a new column family (and its RocksDBDict) after construction. kwargs... are forwarded to Options (compression, block_cache_size, ...), applied to every column family opened here.

create_column_family(store::ColumnFamilies, name) -> RocksDBDict

Create a new column family on store's underlying database and return its (now registered) RocksDBDict.

RocksDBSnapshotView{K,V}

A read-only AbstractDict{K,V} view of a RocksDBDict's column family, pinned to a point-in-time Snapshot: writes made to the underlying dict after the view was created are invisible to it, both via indexing and iteration. Construct with snapshot; writing to a view (setindex!, delete!, empty!) throws.

length is not point-in-time consistent – RocksDB's "rocksdb.estimate-num-keys" property has no snapshot/ReadOptions parameter in the C API, so it always reflects the live database, unlike getindex/haskey/iteration on the same view.

close(view) releases only the snapshot (and its ReadOptions), not the shared underlying DB – that connection is owned by whichever RocksDBDict/ColumnFamilies it came from and keeps working after the view is closed.

snapshot(d::RocksDBDict) -> RocksDBSnapshotView
snapshot(f, d::RocksDBDict)

Create a RocksDBSnapshotView of d's column family as it is right now. The do-block form releases the snapshot automatically (even if f throws); otherwise release it with close(view) when done.

view = RocksDB.snapshot(d)
d["k"] = "changed after the snapshot"
view["k"]   # still the pre-snapshot value (or a KeyError if it didn't exist yet)
close(view)

length(v::RocksDBSnapshotView)

Not point-in-time consistent – see RocksDBSnapshotView.