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 sqliteFree() / 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);
    sqliteFree(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. *ppCF receives the handle.

kvstore_cf_open

Open an existing column family. Returns KVSTORE_NOTFOUND if it does not exist.

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.

kvstore_cf_list

List all column families. Caller must free each name and the array with sqliteFree().

char **names = NULL; int count = 0;
kvstore_cf_list(kv, &names, &count);
for (int i = 0; i < count; i++) {
    printf("%s\n", names[i]);
    sqliteFree(names[i]);
}
sqliteFree(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 */ sqliteFree(val); }

kvstore_ttl_remaining

kvstore_purge_expired

Scan the expiry index and delete all expired keys in one write transaction. O(expired keys) — uses sorted expire-time prefix to stop at first non-expired entry.

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

Scan and delete all expired keys in this column family only, in a single write transaction. O(expired keys). 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.

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

kvstore_sync

Force all pending changes to disk. If a write transaction is active, performs a commit-and-reopen cycle to flush the WAL.

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

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 only if the password is wrong on an already-encrypted file. *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. The old password is invalid immediately after this call returns.

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.

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

kvstore_vec_get_metadata

Fetch JSON metadata bytes. Returns KVSTORE_OK with *ppMeta=NULL when no metadata has ever been written to this store (tags CF does not yet exist). Returns KVSTORE_NOTFOUND with *ppMeta=NULL when the tags CF exists but this specific key has no metadata. Both cases are not errors. 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. 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 from the KV store, all 5 vector CFs, and the HNSW index — all in one atomic transaction. 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 vectors from every CF and the HNSW index in one atomic transaction. *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 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. Sidecar files are removed.

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);