SNKV API Reference

kvstore_open_v2

Open or create a database with full configuration control. Pass NULL for pConfig to use all defaults (WAL mode, NORMAL sync, 8 MB cache). Returns KVSTORE_AUTH_FAILED if the file is an encrypted store — use kvstore_open_encrypted instead.

/* default open */
KVStore *kv;
kvstore_open_v2("mydb.db", &kv, NULL);

/* fully configured */
KVStoreConfig cfg = {0};
cfg.journalMode = KVSTORE_JOURNAL_WAL;
cfg.syncLevel   = KVSTORE_SYNC_FULL;
cfg.cacheSize   = 4000;
cfg.busyTimeout = 5000;
kvstore_open_v2("mydb.db", &kv, &cfg);

/* read-only */
KVStoreConfig ro = {0};
ro.readOnly = 1;
kvstore_open_v2("mydb.db", &kv, &ro);

KVSTORE_OK on success, error code otherwise.

kvstore_open

Simplified open. Equivalent to kvstore_open_v2 with only journalMode set; all other fields use defaults. Returns KVSTORE_AUTH_FAILED if the file is an encrypted store.

KVStore *kv = NULL;
kvstore_open("mydata.db", &kv, KVSTORE_JOURNAL_WAL);

kvstore_close

Close the database and free all resources. Any uncommitted transaction is rolled back. Runs a WAL checkpoint before closing.

kvstore_put

Insert or update a key-value pair. If the key already exists, its value is replaced. Keys and values are binary-safe. Without an explicit transaction, each call auto-commits.

kvstore_get

Retrieve a value by key. The returned buffer is heap-allocated by SNKV. Caller must free with snkv_free().

void *value = NULL; int vlen = 0;
int rc = kvstore_get(kv, "user:1", 6, &value, &vlen);
if (rc == KVSTORE_OK) {
    printf("%.*s\n", vlen, (char*)value);
    snkv_free(value);
}

KVSTORE_OK if found · KVSTORE_NOTFOUND if key does not exist.

kvstore_delete

Delete a key. Returns KVSTORE_NOTFOUND if the key did not exist.

kvstore_exists

Check if a key exists without reading its value. More efficient than kvstore_get for existence checks. Sets *pExists to 1 if found, 0 otherwise.

kvstore_cf_create

Create a new column family. zName max 255 characters, must be unique and must not start with __ or _snkv_. *ppCF receives the handle. Passing "default" returns the default CF.

KVSTORE_OK · KVSTORE_ERROR if the name is invalid or reserved, the CF already exists, or 63 named CFs already exist · KVSTORE_NOMEM if the handle cannot be allocated (the CF may already be created — open it with kvstore_cf_open).

kvstore_cf_open

Open an existing column family. Returns KVSTORE_NOTFOUND if it does not exist, KVSTORE_ERROR for a reserved name, KVSTORE_NOMEM if the handle cannot be allocated. Each call returns a new, independent handle; close every handle with kvstore_cf_close.

kvstore_cf_get_default

Get a handle to the default column family. Always exists; created automatically on open.

kvstore_cf_drop

Delete a column family and all its data permanently. The default column family cannot be dropped. Also removes any hidden TTL index CFs. Other open CF handles stay valid (the file may move another table's root page; open handles follow it). The drop is all-or-nothing: on any error nothing is changed (inside your own transaction, roll it back).

KVSTORE_OK · KVSTORE_NOTFOUND if it does not exist · KVSTORE_ERROR for "default" or a reserved name · KVSTORE_BUSY if a handle to this CF is still open, or if any iterator is open on the store — close them first.

kvstore_cf_list

List the named column families (the default CF is not included). Internal CFs (names starting with __ or _snkv_) are not listed. Caller must free each name and the array with snkv_free().

char **names = NULL; int count = 0;
kvstore_cf_list(kv, &names, &count);
for (int i = 0; i < count; i++) {
    printf("%s\n", names[i]);
    snkv_free(names[i]);
}
snkv_free(names);

kvstore_cf_close

Release the column family handle. Does not delete data.

CF Key-Value Operations

Identical to the default-CF variants but take a KVColumnFamily* handle.

kvstore_iterator_create / kvstore_cf_iterator_create

Create a forward iterator for the default or a specific column family.

kvstore_iterator_first / next / eof

Position at first entry, advance to next, or test for end-of-sequence.

kvstore_iterator_key / value

Read the current key or value. Pointers are owned by the iterator — do not free them. Valid until the next next() or close() call.

KVIterator *it = NULL;
kvstore_iterator_create(kv, &it);
kvstore_iterator_first(it);
while (!kvstore_iterator_eof(it)) {
    void *key, *val; int klen, vlen;
    kvstore_iterator_key(it, &key, &klen);
    kvstore_iterator_value(it, &val, &vlen);
    printf("%.*s\n", klen, (char*)key);
    kvstore_iterator_next(it);
}
kvstore_iterator_close(it);

kvstore_iterator_close

Release the iterator and its cursor. Always call this when done.

KVIterator *it = NULL;
kvstore_prefix_iterator_create(kv, "user:", 5, &it);
/* already at first match — do NOT call first() */
while (!kvstore_iterator_eof(it)) {
    void *key; int klen;
    kvstore_iterator_key(it, &key, &klen);
    kvstore_iterator_next(it);
}
kvstore_iterator_close(it);

/* Full reverse scan */
KVIterator *it = NULL;
kvstore_reverse_iterator_create(kv, &it);
kvstore_iterator_last(it);
while (!kvstore_iterator_eof(it)) {
    void *key; int klen;
    kvstore_iterator_key(it, &key, &klen);
    kvstore_iterator_prev(it);
}
kvstore_iterator_close(it);

/* Reverse prefix — do NOT call last(), already positioned */
kvstore_reverse_prefix_iterator_create(kv, "user:", 5, &it);
while (!kvstore_iterator_eof(it)) {
    kvstore_iterator_prev(it);
}
kvstore_iterator_close(it);

kvstore_iterator_seek

Reposition the iterator without closing and reopening it.

• Forward iterator — seek to the first key >= (pKey, nKey).
• Reverse iterator — seek to the last key <= (pKey, nKey).

If the seek lands outside a prefix iterator’s prefix, the iterator immediately enters the eof state. Call kvstore_iterator_key / kvstore_iterator_next as usual after a successful seek.

/* forward: scan from "m" onwards */
KVIterator *it = NULL;
kvstore_iterator_create(kv, &it);
kvstore_iterator_seek(it, "m", 1);
while (!kvstore_iterator_eof(it)) {
    void *key; int klen;
    kvstore_iterator_key(it, &key, &klen);
    kvstore_iterator_next(it);
}
kvstore_iterator_close(it);

/* reverse: scan from "m" backwards */
kvstore_reverse_iterator_create(kv, &it);
kvstore_iterator_seek(it, "m", 1);
while (!kvstore_iterator_eof(it)) {
    kvstore_iterator_prev(it);
}
kvstore_iterator_close(it);

Explicit ACID transactions for batching operations atomically. Without an explicit transaction, each put/delete auto-commits. Wrapping bulk writes in a single transaction is significantly faster.

kvstore_begin(kv, 1);
kvstore_put(kv, "key1", 4, "val1", 4);
kvstore_put(kv, "key2", 4, "val2", 4);
kvstore_commit(kv);   /* both writes are atomic */

kvstore_put_ttl / kvstore_get_ttl

/* write key that expires in 30 minutes */
int64_t exp = kvstore_now_ms() + 30 * 60 * 1000;
kvstore_put_ttl(kv, "sess:abc", 8, token, tlen, exp);

/* read with lazy expiry */
void *val = NULL; int nVal = 0; int64_t rem = 0;
int rc = kvstore_get_ttl(kv, "sess:abc", 8, &val, &nVal, &rem);
if (rc == KVSTORE_OK) { /* rem = ms remaining */ snkv_free(val); }

kvstore_ttl_remaining

kvstore_purge_expired

Delete all expired keys, oldest expiry first. O(expired keys) — the expiry index is sorted by time, so it stops at the first key that has not expired. Works in batches of up to 256 keys per write transaction (build-time setting KVSTORE_PURGE_BATCH), releasing the lock between batches; memory use is one key at a time. If you have a write transaction open, it works inside it instead: the deletes commit or roll back with your transaction.

kvstore_cf_put_ttl / kvstore_cf_get_ttl

CF-level equivalents of kvstore_put_ttl / kvstore_get_ttl. Semantics are identical; the TTL indexes are created lazily per CF and are fully independent.

kvstore_cf_ttl_remaining

Return remaining TTL for a key in this column family without fetching the value. Return codes and *pnRemaining semantics are identical to kvstore_ttl_remaining.

kvstore_cf_purge_expired

Delete all expired keys in this column family only. O(expired keys). Same batching and transaction behaviour as kvstore_purge_expired. Purging CF A never affects other column families.

kvstore_put_if_absent / kvstore_cf_put_if_absent

The existence check and the write are performed inside a single write transaction, so no other writer can insert the same key concurrently.

int inserted = 0;
kvstore_put_if_absent(kv, "lock", 4, "owner", 5, 0, &inserted);
if (inserted) {
    puts("acquired lock");
} else {
    puts("lock already held");
}

/* with TTL: session token that expires in 1 hour */
int64_t exp = kvstore_now_ms() + 3600 * 1000;
kvstore_put_if_absent(kv, session_id, sid_len, token, tok_len, exp, NULL);

kvstore_clear / kvstore_cf_clear

Truncates the column family’s B-tree in O(pages) time using SQLite’s BtreeClearTable — the B-tree structure (root page) is preserved so future inserts work immediately without re-opening.

/* flush a rate-limit namespace at midnight */
kvstore_cf_clear(rate_limit_cf);

/* wipe everything in the default CF */
kvstore_clear(kv);

kvstore_count / kvstore_cf_count

Counts only the main data B-tree of the column family. TTL index CFs are separate B-trees and are not included. Expired-but-not-yet-purged keys are included in the count — call kvstore_purge_expired first for an exact live count.

int64_t n;
kvstore_count(kv, &n);
printf("default CF has %lld entries\n", (long long)n);

kvstore_purge_expired(kv, NULL);
kvstore_count(kv, &n);
printf("live entries after purge: %lld\n", (long long)n);

kvstore_errmsg

Return the last error message string. Do not free. Valid until the next operation on the same handle. When several threads share one handle, use kvstore_errmsg_copy instead.

kvstore_libversion / kvstore_libversion_number

Version of the library actually linked. The header defines the same values as macros for compile-time checks: KVSTORE_VERSION ("0.9.0"), KVSTORE_VERSION_MAJOR / _MINOR / _PATCH, and KVSTORE_VERSION_NUMBER = MAJOR×1000000 + MINOR×1000 + PATCH. Comparing kvstore_libversion_number() with KVSTORE_VERSION_NUMBER detects a header/library mismatch when SNKV is used as a shared library.

kvstore_errmsg_copy

Copy the last error message into zBuf (always NUL-terminated, truncated to fit). The copy is taken under the handle mutex, so it is safe when threads share a handle. Returns KVSTORE_ERROR if zBuf is NULL or nBuf <= 0.

kvstore_stats / kvstore_stats_reset

kvstore_stats fills the KVStoreStats struct. All counters are cumulative from open (or last reset). kvstore_stats_reset zeros them; nDbPages is a live gauge and is never zeroed.

kvstore_integrity_check

Walk the entire B-tree and verify structural integrity. Returns KVSTORE_OK or KVSTORE_CORRUPT with details in *pzErrMsg. Caller must free *pzErrMsg with snkv_free().

kvstore_sync

Make every committed transaction durable: fsyncs the WAL file (or rollback journal) and the database file (fsync on Linux/macOS, FlushFileBuffers on Windows). Useful with KVSTORE_SYNC_OFF or NORMAL, where commits do not fsync: commit cheaply, then call kvstore_sync at points that must survive a power loss. It does not checkpoint — use kvstore_checkpoint for that.

KVSTORE_OK · KVSTORE_ERROR while an explicit write transaction is open (commit or roll back first) · an I/O error code if the disk sync fails.

kvstore_incremental_vacuum

Reclaim unused pages and shrink the database file. Pass 0 to free all unused pages, or a positive nPage to limit work per call (good for latency-sensitive apps). Safe while iterators are open: they continue from their current key. Runs in its own write transaction, or inside yours if one is open.

kvstore_incremental_vacuum(kv, 0);    /* free all */
kvstore_incremental_vacuum(kv, 50);   /* incremental: 50 pages */

kvstore_checkpoint

Copy WAL frames back into the main database file. pnLog and pnCkpt may be NULL. Requires no active write transaction. Non-WAL databases: no-op returning KVSTORE_OK.

int nLog = 0, nCkpt = 0;
kvstore_checkpoint(kv, KVSTORE_CHECKPOINT_PASSIVE, &nLog, &nCkpt);
printf("%d frames total, %d checkpointed\n", nLog, nCkpt);

/* reclaim WAL disk space */
kvstore_checkpoint(kv, KVSTORE_CHECKPOINT_TRUNCATE, NULL, NULL);

kvstore_open_encrypted

Open or create an encrypted store. On a fresh file a new Argon2id-derived key is generated from the password. On an existing encrypted file the password is verified before access is granted. If the file is a plain (non-encrypted) store with existing data, all values are encrypted in-place using the supplied password — the store becomes fully encrypted transparently. Returns KVSTORE_AUTH_FAILED if the password is wrong on an already-encrypted file, KVSTORE_CORRUPT if the key-derivation parameters stored in the file are out of range (corrupt or crafted file — rejected before anything is allocated), and KVSTORE_NOMEM if the key-derivation memory cannot be allocated. *ppKV is set to NULL on any error — no resource leak.

/* Create / open encrypted */
KVStore *kv = NULL;
int rc = kvstore_open_encrypted("mydb.db", "hunter2", 7, &kv, NULL);
if (rc == KVSTORE_AUTH_FAILED) { puts("wrong password"); }

/* All standard operations work transparently */
kvstore_put(kv, "key", 3, "secret", 6);
kvstore_close(kv);

kvstore_is_encrypted

Returns 1 if the store was opened with kvstore_open_encrypted, 0 otherwise.

kvstore_reencrypt

Change the encryption password in-place. Derives a new key from the new password, re-encrypts every value in every column family, and updates the authentication metadata — all in a single atomic transaction. On success the old password is invalid immediately. On any failure (including a failed commit) nothing is changed and the old password stays valid. Returns KVSTORE_ERROR if the store is not encrypted or an explicit transaction is open (commit or roll back first).

kvstore_reencrypt(kv, "new-pass", 8);
/* kv is still open and usable with the new password */

kvstore_remove_encryption

Decrypt all values in-place and remove the authentication metadata. After this call the store is a plain (non-encrypted) SNKV database and can be opened with kvstore_open or kvstore_open_v2. Runs in one transaction: on any failure nothing is changed and the store stays encrypted. Returns KVSTORE_ERROR if the store is not encrypted or an explicit transaction is open.

kvstore_remove_encryption(kv);
kvstore_close(kv);

/* Now opens without a password */
KVStore *plain = NULL;
kvstore_open("mydb.db", &plain, KVSTORE_JOURNAL_WAL);

kvstore_now_ms

Current time in milliseconds since the Unix epoch. Useful for computing absolute TTL expiry timestamps: kvstore_now_ms() + delta_ms.

kvstore_vec_open

Open or create a vector store. dim, space, and dtype are immutable after the first open — passing different values on a subsequent open returns the corresponding mismatch error. Pass pPassword/nPassword for an encrypted store; sidecar persistence is disabled for encrypted stores. *ppVS is NULL on any error.

KVVecStore *vs = NULL;
int rc = kvstore_vec_open(
    "store.db", 128, KVVEC_SPACE_COSINE,
    0, 0, 0,            /* defaults */
    KVVEC_DTYPE_F32,
    NULL, 0,              /* plain (unencrypted) */
    &vs
);
if (rc == KVVEC_DIM_MISMATCH) puts("wrong dim for existing store");

kvstore_vec_close

Close the store and free all resources. For unencrypted file-backed stores, saves the HNSW graph to {path}.usearch and the next-id stamp to {path}.usearch.nid so the next open can skip the O(n·dim) rebuild. Safe to call with NULL.

kvstore_vec_put

Insert or update a key/value pair and add its vector to the HNSW index. The KVStore write (all 5 internal CFs) is one atomic transaction; the usearch index update happens after commit. If the key already exists, the old usearch label is removed before the new one is added (count stays constant on overwrite).

float vec[128] = { /* ... */ };
kvstore_vec_put(vs, "doc:1", 5, "hello", 5,
                vec,
                0,                     /* no TTL */
                "{\"tag\":\"ai\"}", 12);  /* metadata */

kvstore_vec_put_batch

Insert or update nItems records in one atomic transaction. Last-write-wins for duplicate keys within the batch — only the last vector for a repeated key enters the index. All usearch insertions happen after the commit.

KVVecItem items[3] = {
    { "k1", 2, "val1", 4, vec1, NULL, 0 },
    { "k2", 2, "val2", 4, vec2, NULL, 0 },
    { "k3", 2, "val3", 4, vec3, meta, nMeta },
};
kvstore_vec_put_batch(vs, items, 3, 0);

kvstore_vec_kv_put

Plain KV write — does not update the vector index. Useful for storing non-vector data (config, counters) alongside vector keys in the same file.

kvstore_vec_get

Fetch value bytes. TTL-aware: returns KVSTORE_NOTFOUND and lazily deletes the key if it has expired. Caller must snkv_free(*ppVal).

kvstore_vec_get_vector

Fetch the stored float32 vector. *ppVec is a flat array of dim floats. Caller must snkv_free(*ppVec). TTL-aware: returns KVSTORE_NOTFOUND if the key is missing or expired. Returns KVVEC_INDEX_DROPPED after kvstore_vec_drop_index.

kvstore_vec_get_metadata

Fetch JSON metadata bytes. TTL-aware: returns KVSTORE_NOTFOUND with *ppMeta=NULL if the key is missing or expired. For a live key: returns KVSTORE_OK with *ppMeta=NULL when no metadata has ever been written to this store (tags CF does not yet exist), and KVSTORE_NOTFOUND with *ppMeta=NULL when this key has no metadata. Neither is an error. Metadata stays readable after the store is reopened. Caller must snkv_free(*ppMeta) on KVSTORE_OK with non-NULL result.

kvstore_vec_contains

Returns 1 if the key exists and is not expired, 0 otherwise.

kvstore_vec_count

Returns the number of active (non-deleted) vectors in the HNSW index (usearch_size).

kvstore_vec_search

Approximate nearest-neighbour search. Expired keys are filtered out transparently (without replacement, so fewer than top_k results can come back; rerank's oversampling makes this less likely). Values are read only for the results returned. Results are sorted ascending by distance. Caller must pass the array to kvstore_vec_free_results. Returns KVVEC_INDEX_EMPTY if no vectors have been inserted, KVVEC_INDEX_DROPPED after kvstore_vec_drop_index.

float q[128] = { /* ... */ };
KVVecSearchResult *res = NULL; int n = 0;

/* Basic ANN search */
kvstore_vec_search(vs, q, 5, 0, 0, 0.0f, &res, &n);

/* With exact rerank (oversample×top_k candidates → exact distance sort) */
kvstore_vec_search(vs, q, 5, 1, 3, 0.0f, &res, &n);

for (int i = 0; i < n; i++)
    printf("%.*s  dist=%.4f  val=%.*s\n",
           res[i].nKey, (char*)res[i].pKey, res[i].distance,
           res[i].nValue, (char*)res[i].pValue);
kvstore_vec_free_results(res, n);

kvstore_vec_search_keys

ANN search returning (key, distance) pairs only — no value fetch. Cheaper than kvstore_vec_search when values are not needed. Caller must pass the array to kvstore_vec_free_key_results.

kvstore_vec_free_results / kvstore_vec_free_key_results

Free the result arrays returned by the search functions. Safe to call with NULL.

kvstore_vec_delete

Delete the key's value and its vector, label and metadata rows in one atomic transaction, then remove it from the HNSW index after the commit. Returns KVSTORE_NOTFOUND if the key does not exist.

kvstore_vec_stats

Fill *pStats with current index configuration and runtime state. Always returns KVSTORE_OK.

kvstore_vec_purge_expired

Scan the __snkv_vec__ CF and delete all expired (or orphaned) vectors from every vector CF and the HNSW index, in batches of up to 64 per transaction (build-time setting KVVEC_PURGE_BATCH), so memory stays bounded however many keys expired. If a later batch fails, earlier batches stay deleted and the error is returned. *pnDeleted (may be NULL) is set to the number removed. Use this in preference to kvstore_purge_expired to keep vector CFs in sync. Returns KVSTORE_OK (0 deleted) when there are no TTL entries.

kvstore_vec_drop_index

Drop all five __snkv_vec*__ column families in one transaction and free the in-memory HNSW index. KV data in the default CF is preserved and readable via kvstore_vec_get. After this call, kvstore_vec_search returns KVVEC_INDEX_DROPPED; the drop persists across reopen. Sidecar files are removed. Returns KVSTORE_BUSY if an iterator is open on the store; on any error the index is kept and the error is returned.

kvstore_vec_drop_index(vs);    /* index gone, KV intact */

void *v = NULL; int n = 0;
kvstore_vec_get(vs, "doc:1", 5, &v, &n);  /* still works */
snkv_free(v);