@taladb/react-native 0.11.3 → 0.11.4

package/cpp/TalaDBHostObject.cpp

@@ -643,6 +643,24 @@ Value TalaDBHostObject::get(Runtime &rt, const PropNameID &propName) {
             });
     }
 
+    // ------------------------------------------------------------------
+    // rebuildVectorIndexes(): void
+    //
+    // Warms every HNSW graph in the database. The graphs are memory-only, so
+    // without this findNearest silently degrades to an exact linear scan for
+    // the whole process lifetime. Scans every indexed vector — call it once at
+    // startup, off the first frame.
+    // ------------------------------------------------------------------
+    if (name == "rebuildVectorIndexes") {
+        return Function::createFromHostFunction(
+            rt, PropNameID::forAscii(rt, "rebuildVectorIndexes"), 0,
+            [this](Runtime &rt, const Value &, const Value *, size_t) -> Value {
+                int32_t res = taladb_rebuild_hnsw_indexes(db_);
+                if (res < 0) throw ffiError(rt, "taladb_rebuild_hnsw_indexes failed");
+                return Value::undefined();
+            });
+    }
+
     // ------------------------------------------------------------------
     // findNearest(collection, field, query, topK, filter?): { document, score }[]
     //   query — Float32Array (preferred, zero-copy) or number[]
@@ -799,7 +817,7 @@ Value TalaDBHostObject::get(Runtime &rt, const PropNameID &propName) {
     if (name == "close") {
         return Function::createFromHostFunction(
             rt, PropNameID::forAscii(rt, "close"), 0,
-            [this](Runtime &rt, const Value &, const Value *, size_t) -> Value {
+            [this](Runtime &, const Value &, const Value *, size_t) -> Value {
                 if (db_) {
                     taladb_close(db_);
                     db_ = nullptr;

package/cpp/taladb.h

@@ -1,13 +1,13 @@
-#pragma once
-#ifndef TALADB_FFI_H
-#define TALADB_FFI_H
-
 /*
  * TalaDB C FFI header.
  *
- * This file is the stable C interface between the Rust taladb-ffi crate and
- * the C++ JSI HostObject.  It is kept in sync with rust/src/lib.rs manually
- * (or regenerated with cbindgen — see rust/cbindgen.toml).
+ * GENERATED FILE — do not edit. Regenerate with:
+ *   pnpm --filter @taladb/react-native build:cbindgen
+ * CI fails if this file and rust/src/lib.rs disagree.
+ *
+ * This is the stable C interface between the Rust taladb-ffi crate and the C++
+ * JSI HostObject (cpp/TalaDBHostObject.cpp, cpp/TalaDBJni.cpp) and the iOS
+ * TurboModule (ios/TalaDB.mm).
  *
  * Ownership rules
  * ---------------
@@ -15,293 +15,383 @@
  *  - Strings OUT : heap-allocated by Rust; caller must free with
  *                  taladb_free_string().
  *  - Handles     : allocated by taladb_open(); freed by taladb_close().
- *  - Errors      : string functions return NULL; integer functions return -1.
+ *  - Errors      : string functions return NULL; integer functions return -1,
+ *                  with detail available from taladb_last_error().
  */
 
+
+#ifndef TALADB_FFI_H
+#define TALADB_FFI_H
+
+#pragma once
+
+#include <stdarg.h>
+#include <stdbool.h>
 #include <stdint.h>
 #include <stdlib.h>
 
-#ifdef __cplusplus
-extern "C" {
-#endif
 
-/* -------------------------------------------------------------------------
- * Opaque database handle
- * ---------------------------------------------------------------------- */
 typedef struct TalaDbHandle TalaDbHandle;
 
-/* -------------------------------------------------------------------------
- * Lifecycle
- * ---------------------------------------------------------------------- */
+/**
+ * A background job handle. Opaque to the caller.
+ */
+typedef struct TalaDbJob TalaDbJob;
 
-/** Open (or create) a database at the given file-system path. */
-TalaDbHandle *taladb_open(const char *path);
+#ifdef __cplusplus
+extern "C" {
+#endif // __cplusplus
 
 /**
- * Open (or create) a database with durability/encryption configuration.
+ * Return the last error message as a null-terminated C string, or NULL if no error.
+ *
+ * The message always describes the most recent `taladb_*` call on this thread:
+ * every entry point clears the slot before doing any work, so a NULL return
+ * means that call succeeded rather than that it forgot to report.
  *
- * config_json — JSON-serialised TalaDbConfig, or NULL for defaults.
- * Returns an opaque handle (same semantics as taladb_open), or NULL on failure.
+ * The returned pointer is valid until the next taladb_* call on this thread.
+ * Do NOT free the returned string.
  */
-TalaDbHandle *taladb_open_with_config(const char *path, const char *config_json);
+const char *taladb_last_error(void);
 
-/** Flush and close the database, freeing the handle. */
-void taladb_close(TalaDbHandle *handle);
+/**
+ * Open (or create) a TalaDB database at `path`.
+ *
+ * Returns an opaque handle, or NULL on failure.
+ * The handle must be freed with `taladb_close`.
+ */
+struct TalaDbHandle *taladb_open(const char *path);
 
 /**
- * Compact the underlying storage file, reclaiming space freed by deletes and
- * updates. No-op on in-memory databases. Returns 1 on success, -1 on error.
+ * Open (or create) a TalaDB database at `path` with an optional config.
+ *
+ * `config_json` — JSON-serialised `TalaDbConfig` (durability, plus an optional
+ * `passphrase` for encryption at rest), or NULL for defaults. Change webhooks
+ * are delivered by the `taladb` TypeScript client, not by this binding.
+ *
+ * Unknown config keys are ignored so one config file can be shared with the TS
+ * client — **except** a key that differs from `passphrase` only in spelling, and
+ * a `passphrase` that is present but not a string. Both are errors rather than
+ * a silent unencrypted open; see [`passphrase_from_config`].
+ *
+ * Returns an opaque handle, or NULL on failure.
+ * The handle must be freed with `taladb_close`.
  */
-int32_t taladb_compact(TalaDbHandle *handle);
+struct TalaDbHandle *taladb_open_with_config(const char *path, const char *config_json);
 
-/** Free a C string returned by any taladb_* function. */
-void taladb_free_string(char *s);
+/**
+ * Compact the underlying storage file for this database handle.
+ * No-op on in-memory databases. Returns 1 on success, -1 on error.
+ */
+int32_t taladb_compact(struct TalaDbHandle *handle);
 
-/* -------------------------------------------------------------------------
- * Insert
- * ---------------------------------------------------------------------- */
+/**
+ * Close the database and free the handle.
+ */
+void taladb_close(struct TalaDbHandle *handle);
 
 /**
- * Insert a document (JSON object).
+ * Free a string returned by any taladb_* function.
+ */
+void taladb_free_string(char *s);
+
+/**
+ * Insert a document (JSON object string).
  * Returns the new document's ULID as a C string, or NULL on error.
- * Caller must free with taladb_free_string().
+ * Caller must free the returned string with `taladb_free_string`.
  */
-char *taladb_insert(TalaDbHandle *handle,
-                    const char   *collection,
-                    const char   *doc_json);
+char *taladb_insert(struct TalaDbHandle *handle, const char *collection, const char *doc_json);
 
 /**
  * Insert multiple documents (JSON array of objects).
  * Returns a JSON array of ULID strings, or NULL on error.
- * Caller must free with taladb_free_string().
+ * Caller must free with `taladb_free_string`.
+ *
+ * **All or nothing.** If any element of the array is not an object, the whole
+ * call fails and nothing is written. It previously skipped unparseable
+ * elements and returned a shorter id array, so a caller zipping the returned
+ * ids back onto its input silently mis-associated every document after the
+ * first bad one — and had no way to learn which had been dropped.
  */
-char *taladb_insert_many(TalaDbHandle *handle,
-                         const char   *collection,
-                         const char   *docs_json);
-
-/* -------------------------------------------------------------------------
- * Find
- * ---------------------------------------------------------------------- */
+char *taladb_insert_many(struct TalaDbHandle *handle,
+                         const char *collection,
+                         const char *docs_json);
 
 /**
- * Find all documents matching filter_json.
- * Pass "{}" or "null" to match all.
+ * Find all documents matching `filter_json`.
+ * Pass `"{}"` or `"null"` to match all.
  * Returns a JSON array string, or NULL on error.
- * Caller must free with taladb_free_string().
+ * Caller must free with `taladb_free_string`.
  */
-char *taladb_find(TalaDbHandle *handle,
-                  const char   *collection,
-                  const char   *filter_json);
+char *taladb_find(struct TalaDbHandle *handle, const char *collection, const char *filter_json);
 
 /**
- * Find the first document matching filter_json.
- * Returns a JSON object string, or the string "null" if not found.
- * Caller must free with taladb_free_string().
+ * Find one document matching `filter_json`, or JSON `null` if none.
+ * Caller must free with `taladb_free_string`.
  */
-char *taladb_find_one(TalaDbHandle *handle,
-                      const char   *collection,
-                      const char   *filter_json);
+char *taladb_find_one(struct TalaDbHandle *handle, const char *collection, const char *filter_json);
 
-/* -------------------------------------------------------------------------
- * Update
- * ---------------------------------------------------------------------- */
+/**
+ * Update the first matching document.
+ * Returns 1 if updated, 0 if not found, -1 on error.
+ */
+int32_t taladb_update_one(struct TalaDbHandle *handle,
+                          const char *collection,
+                          const char *filter_json,
+                          const char *update_json);
 
-/** Update the first matching document. Returns 1 updated, 0 not found, -1 error. */
-int32_t taladb_update_one(TalaDbHandle *handle,
-                          const char   *collection,
-                          const char   *filter_json,
-                          const char   *update_json);
+/**
+ * Update all matching documents.
+ * Returns count updated, or -1 on error.
+ */
+int32_t taladb_update_many(struct TalaDbHandle *handle,
+                           const char *collection,
+                           const char *filter_json,
+                           const char *update_json);
 
-/** Update all matching documents. Returns count updated, or -1 on error. */
-int32_t taladb_update_many(TalaDbHandle *handle,
-                           const char   *collection,
-                           const char   *filter_json,
-                           const char   *update_json);
+/**
+ * Delete the first matching document.
+ * Returns 1 if deleted, 0 if not found, -1 on error.
+ */
+int32_t taladb_delete_one(struct TalaDbHandle *handle,
+                          const char *collection,
+                          const char *filter_json);
 
-/* -------------------------------------------------------------------------
- * Delete
- * ---------------------------------------------------------------------- */
+/**
+ * Delete all matching documents.
+ * Returns count deleted, or -1 on error.
+ */
+int32_t taladb_delete_many(struct TalaDbHandle *handle,
+                           const char *collection,
+                           const char *filter_json);
 
-/** Delete the first matching document. Returns 1 deleted, 0 not found, -1 error. */
-int32_t taladb_delete_one(TalaDbHandle *handle,
-                          const char   *collection,
-                          const char   *filter_json);
+/**
+ * Count documents matching `filter_json`.
+ * Returns count, or -1 on error.
+ */
+int32_t taladb_count(struct TalaDbHandle *handle, const char *collection, const char *filter_json);
 
-/** Delete all matching documents. Returns count deleted, or -1 on error. */
-int32_t taladb_delete_many(TalaDbHandle *handle,
-                           const char   *collection,
-                           const char   *filter_json);
+/**
+ * Run an aggregation pipeline (`pipeline_json` is a JSON array of stages).
+ * Returns a JSON array of result documents, or NULL on error.
+ * Caller must free with `taladb_free_string`.
+ */
+char *taladb_aggregate(struct TalaDbHandle *handle,
+                       const char *collection,
+                       const char *pipeline_json);
 
-/* -------------------------------------------------------------------------
- * Count
- * ---------------------------------------------------------------------- */
+/**
+ * User collection names (reserved `_`-prefixed excluded), as a JSON array
+ * string. Backs the sync orchestration's "sync all collections" default.
+ * NULL on error. Caller must free with `taladb_free_string`.
+ */
+char *taladb_list_collection_names(struct TalaDbHandle *handle);
 
-/** Count documents matching filter_json. Returns count, or -1 on error. */
-int32_t taladb_count(TalaDbHandle *handle,
-                     const char   *collection,
-                     const char   *filter_json);
+/**
+ * Read the current application migration version (0 if never set), or -1 on
+ * error. Backs the `openDB({ migrations })` runner.
+ */
+int64_t taladb_user_version(struct TalaDbHandle *handle);
 
-/* -------------------------------------------------------------------------
- * Aggregate
- * ---------------------------------------------------------------------- */
+/**
+ * Persist the application migration version. Returns 0 on success, -1 on error.
+ */
+int32_t taladb_set_user_version(struct TalaDbHandle *handle, uint32_t version);
 
 /**
- * Run an aggregation pipeline. pipeline_json is a JSON array of stages.
- * Returns a JSON array of result documents, or NULL on error.
- * Caller must free with taladb_free_string().
+ * Force any batched (eventual-durability) writes to disk. Returns 0 on
+ * success, -1 on error. No-op under the default immediate durability.
  */
-char *taladb_aggregate(TalaDbHandle *handle,
-                       const char   *collection,
-                       const char   *pipeline_json);
+int32_t taladb_flush(struct TalaDbHandle *handle);
 
 /**
- * User collection names (reserved names excluded) as a JSON array string.
- * Returns NULL on error. Caller must free with taladb_free_string().
+ * Create a secondary index on `field`. No-op if already exists.
  */
-char *taladb_list_collection_names(TalaDbHandle *handle);
+void taladb_create_index(struct TalaDbHandle *handle, const char *collection, const char *field);
 
 /**
- * Read / write the application migration version (backs openDB({ migrations })).
- * taladb_user_version returns the version (0 if unset) or -1 on error;
- * taladb_set_user_version returns 0 on success, -1 on error.
+ * Drop a secondary index on `field`.
  */
-int64_t taladb_user_version(TalaDbHandle *handle);
-int32_t taladb_set_user_version(TalaDbHandle *handle, uint32_t version);
+void taladb_drop_index(struct TalaDbHandle *handle, const char *collection, const char *field);
 
 /**
- * Force any batched (eventual-durability) writes to disk. Returns 0 on success,
- * -1 on error. No-op under the default immediate durability. Backs db.flush().
+ * Create a compound index over `fields_json` (a JSON array of field names).
  */
-int32_t taladb_flush(TalaDbHandle *handle);
+void taladb_create_compound_index(struct TalaDbHandle *handle,
+                                  const char *collection,
+                                  const char *fields_json);
 
-/* -------------------------------------------------------------------------
- * Index management
- * ---------------------------------------------------------------------- */
+/**
+ * Drop a compound index by its ordered field list (`fields_json`).
+ */
+void taladb_drop_compound_index(struct TalaDbHandle *handle,
+                                const char *collection,
+                                const char *fields_json);
 
-void taladb_create_index    (TalaDbHandle *handle, const char *collection, const char *field);
-void taladb_drop_index      (TalaDbHandle *handle, const char *collection, const char *field);
-void taladb_create_fts_index(TalaDbHandle *handle, const char *collection, const char *field);
-void taladb_drop_fts_index  (TalaDbHandle *handle, const char *collection, const char *field);
+/**
+ * Create a full-text search index on `field`.
+ */
+void taladb_create_fts_index(struct TalaDbHandle *handle,
+                             const char *collection,
+                             const char *field);
 
-/* Compound (multi-field) indexes. fields_json is a JSON array of field names. */
-void taladb_create_compound_index(TalaDbHandle *handle, const char *collection, const char *fields_json);
-void taladb_drop_compound_index  (TalaDbHandle *handle, const char *collection, const char *fields_json);
+/**
+ * Drop a full-text search index on `field`.
+ */
+void taladb_drop_fts_index(struct TalaDbHandle *handle, const char *collection, const char *field);
 
-/* -------------------------------------------------------------------------
- * Vector index management
- *
- *   metric    — "cosine" (default), "dot", or "euclidean". NULL ⇒ cosine.
- *   hnsw_json — JSON-encoded HnswOptions, or NULL for flat index.
- * ---------------------------------------------------------------------- */
-
-int32_t taladb_create_vector_index(TalaDbHandle *handle,
-                                   const char   *collection,
-                                   const char   *field,
-                                   size_t        dimensions,
-                                   const char   *metric,
-                                   const char   *hnsw_json);
-
-int32_t taladb_drop_vector_index   (TalaDbHandle *handle, const char *collection, const char *field);
-int32_t taladb_upgrade_vector_index(TalaDbHandle *handle, const char *collection, const char *field);
-
-/* -------------------------------------------------------------------------
- * findNearest — Float32 zero-copy fast path
+/**
+ * Rank documents against a free-text query using BM25 (OR semantics).
  *
- * query_ptr / query_len address `query_len` consecutive f32 values. Caller
- * retains ownership; the buffer may be freed immediately after the call.
- * filter_json may be NULL / "{}" / "null" to search without a pre-filter.
+ * `filter_json` / `options_json` may be NULL. `options_json` accepts
+ * `{ k1, b }`.
  *
  * Returns a JSON array string `[{document, score}, ...]`, or NULL on error.
- * Caller must free with taladb_free_string.
- * ---------------------------------------------------------------------- */
-
-char *taladb_find_nearest(TalaDbHandle *handle,
-                          const char   *collection,
-                          const char   *field,
-                          const float  *query_ptr,
-                          size_t        query_len,
-                          size_t        top_k,
-                          const char   *filter_json);
-
-/* BM25 full-text ranking. Returns a JSON array `[{document, score}, ...]`,
- * or NULL on error. filter_json / options_json may be NULL. options_json
- * accepts `{ k1, b }`. Caller must free with taladb_free_string. */
-char *taladb_search_text(TalaDbHandle *handle,
-                         const char   *collection,
-                         const char   *field,
-                         const char   *query,
-                         size_t        top_k,
-                         const char   *filter_json,
-                         const char   *options_json);
-
-/* Hybrid retrieval (BM25 + vector, fused with RRF). Returns a JSON array
- * `[{document, score, textRank, vectorRank}, ...]`, or NULL on error.
- * filter_json / options_json may be NULL. options_json accepts
- * `{ rrfK, textWeight, vectorWeight, candidates, k1, b }`.
- * Caller must free with taladb_free_string. */
-char *taladb_hybrid_search(TalaDbHandle *handle,
-                           const char   *collection,
-                           const char   *text_field,
-                           const char   *text,
-                           const char   *vector_field,
-                           const float  *vector_ptr,
-                           size_t        vector_len,
-                           size_t        top_k,
-                           const char   *filter_json,
-                           const char   *options_json);
-
-/* -------------------------------------------------------------------------
- * Async job API — run heavy queries on a background thread.
+ * Caller must free with `taladb_free_string`.
+ */
+char *taladb_search_text(struct TalaDbHandle *handle,
+                         const char *collection,
+                         const char *field,
+                         const char *query,
+                         uintptr_t top_k,
+                         const char *filter_json,
+                         const char *options_json);
+
+/**
+ * Hybrid retrieval — BM25 and vector similarity fused with reciprocal rank
+ * fusion.
+ *
+ * `vector_ptr` must point to `vector_len` consecutive `f32` values.
+ * `options_json` accepts `{ rrfK, textWeight, vectorWeight, candidates, k1, b }`.
  *
- * Flow
- * ----
- *   TalaDbJob *j = taladb_find_nearest_start(...);  // spawns worker thread
- *   while (taladb_job_poll(j) == 0) { } // yield to JS event loop
- *   char *json = taladb_job_take_result(j);         // frees the job
+ * Returns a JSON array string `[{document, score, textRank, vectorRank}, ...]`,
+ * or NULL on error. Caller must free with `taladb_free_string`.
  *
- * Workers clone the Arc-backed database state and do not borrow the handle.
- * ---------------------------------------------------------------------- */
+ * # Safety
+ * `vector_ptr` must be valid for `vector_len` `f32` reads.
+ */
+char *taladb_hybrid_search(struct TalaDbHandle *handle,
+                           const char *collection,
+                           const char *text_field,
+                           const char *text,
+                           const char *vector_field,
+                           const float *vector_ptr,
+                           uintptr_t vector_len,
+                           uintptr_t top_k,
+                           const char *filter_json,
+                           const char *options_json);
 
-typedef struct TalaDbJob TalaDbJob;
+/**
+ * Create a vector index. `metric` and `hnsw_json` may be NULL.
+ * Returns 1 on success, -1 on error.
+ */
+int32_t taladb_create_vector_index(struct TalaDbHandle *handle,
+                                   const char *collection,
+                                   const char *field,
+                                   uintptr_t dimensions,
+                                   const char *metric,
+                                   const char *hnsw_json);
+
+/**
+ * Drop a vector index. Returns 1 on success, -1 on error.
+ */
+int32_t taladb_drop_vector_index(struct TalaDbHandle *handle,
+                                 const char *collection,
+                                 const char *field);
 
-/** Kick a background `find_nearest`. Returns NULL on immediate arg error. */
-TalaDbJob *taladb_find_nearest_start(TalaDbHandle *handle,
-                                     const char   *collection,
-                                     const char   *field,
-                                     const float  *query_ptr,
-                                     size_t        query_len,
-                                     size_t        top_k,
-                                     const char   *filter_json);
+/**
+ * Promote a flat/legacy vector index or compact its persistent HNSW graph.
+ * Returns 1 on success, -1 on error.
+ */
+int32_t taladb_upgrade_vector_index(struct TalaDbHandle *handle,
+                                    const char *collection,
+                                    const char *field);
 
-/** Kick a background `find`. Returns NULL on immediate arg error. */
-TalaDbJob *taladb_find_start(TalaDbHandle *handle,
-                             const char   *collection,
-                             const char   *filter_json);
+/**
+ * Rebuild every configured persistent HNSW graph in the database.
+ *
+ * This walks the stored HNSW options and rebuilds each one, so a caller does
+ * not have to know which collections and fields were configured as HNSW —
+ * unlike `taladb_upgrade_vector_index`, which rebuilds a single named field.
+ *
+ * It reads and re-inserts every indexed vector, so call it for maintenance or
+ * legacy migration and off any latency-sensitive path. Normal startup does
+ * not need a rebuild. Returns 1 on success, -1 on error.
+ */
+int32_t taladb_rebuild_hnsw_indexes(struct TalaDbHandle *handle);
 
-/** Non-blocking. Returns 1 if complete, 0 if still running, -1 on NULL job. */
-int32_t taladb_job_poll(TalaDbJob *job);
+/**
+ * Synchronous `find_nearest` with a zero-copy Float32 query vector.
+ *
+ * `query_ptr` — pointer to `query_len` consecutive f32 values (caller-owned).
+ * `filter_json` — optional pre-filter JSON (may be NULL / "{}" / "null").
+ *
+ * Returns a JSON array string `[{document, score}, ...]`, or NULL on error.
+ * Caller must free with `taladb_free_string`.
+ */
+char *taladb_find_nearest(struct TalaDbHandle *handle,
+                          const char *collection,
+                          const char *field,
+                          const float *query_ptr,
+                          uintptr_t query_len,
+                          uintptr_t top_k,
+                          const char *filter_json);
 
 /**
- * Join the worker, take its result, and free the job.
- * Returns a JSON string on success, or NULL on error (see taladb_last_error).
- * Caller must free with taladb_free_string. Always frees the job.
+ * Non-blocking poll. Returns 1 if the job has finished, 0 if still running.
  */
-char *taladb_job_take_result(TalaDbJob *job);
+int32_t taladb_job_poll(struct TalaDbJob *job);
 
-/** Detach the job and free the handle without waiting. */
-TalaDbJob *taladb_call_start(TalaDbHandle *handle, const char *op, const char *args_json);
+/**
+ * Wait for the job to complete, take its result, and free the job.
+ * Returns the result JSON string on success, or NULL on error (see
+ * `taladb_last_error`). Always consumes and frees the job.
+ * Caller must free the returned string with `taladb_free_string`.
+ */
+char *taladb_job_take_result(struct TalaDbJob *job);
 
-void taladb_job_cancel(TalaDbJob *job);
+/**
+ * Cancel (detach) the job and free its handle. The worker owns a clone of all
+ * database state it needs, so it can safely finish after the caller closes the
+ * original database handle.
+ */
+void taladb_job_cancel(struct TalaDbJob *job);
 
 /**
- * Last error message for the current thread, or NULL.
- * The returned pointer is valid until the next taladb_* call on this thread.
- * Do NOT free.
+ * Start a bounded JSON operation on a background worker.
+ *
+ * # Safety
+ * The handle must be live; both strings must be valid NUL-terminated UTF-8
+ * for this call. All arguments are copied before returning.
  */
-const char *taladb_last_error(void);
+struct TalaDbJob *taladb_call_start(struct TalaDbHandle *handle,
+                                    const char *op,
+                                    const char *args_json);
+
+/**
+ * Start a `find_nearest` in a background thread. Returns a job handle, or
+ * NULL on immediate error (bad args). The Float32 query vector is copied
+ * into the thread before the call returns, so `query_ptr` may be freed
+ * immediately after this function returns.
+ */
+struct TalaDbJob *taladb_find_nearest_start(struct TalaDbHandle *handle,
+                                            const char *collection,
+                                            const char *field,
+                                            const float *query_ptr,
+                                            uintptr_t query_len,
+                                            uintptr_t top_k,
+                                            const char *filter_json);
+
+/**
+ * Start a `find` in a background thread. Returns a job handle, or NULL on
+ * immediate error.
+ */
+struct TalaDbJob *taladb_find_start(struct TalaDbHandle *handle,
+                                    const char *collection,
+                                    const char *filter_json);
 
 #ifdef __cplusplus
-} /* extern "C" */
-#endif
+}  // extern "C"
+#endif  // __cplusplus
 
-#endif /* TALADB_FFI_H */
+#endif  /* TALADB_FFI_H */