vectlite 0.1.8 → 0.1.11

package/README.md

@@ -31,8 +31,11 @@ db.upsert('doc2', embedding2, { source: 'notes', title: 'Billing' })
 // Search with filters
 const results = db.search(embeddingQuery, { k: 5, filter: { source: 'blog' } })
 
+// Query-free inspection
+console.log(db.count({ filter: { source: 'blog' } }))
+
 // Clean up
-db.compact()
+db.close()
 ```
 
 ## Features
@@ -62,9 +65,13 @@ db.compact()
 
 - **Physical collections** -- `vectlite.openStore()` manages a directory of independent databases
 - **Bulk ingestion** -- `bulkIngest()` with deferred index rebuilds for fast imports
+- **Listing & filtered counts** -- `list()` and `count({ namespace, filter })` without a vector query
+- **Delete by filter** -- `deleteByFilter()` for bulk deletion by metadata filter
 - **Snapshots** -- `db.snapshot(path)` creates a self-contained copy
 - **Backup / Restore** -- `db.backup(dir)` and `vectlite.restore(dir, path)` for full roundtrips
 - **Read-only mode** -- `vectlite.open(path, { readOnly: true })` for safe concurrent readers
+- **Explicit close** -- `db.close()` to release locks deterministically
+- **Lock timeouts** -- `lockTimeout` for bounded lock acquisition waits
 
 ## Usage
 
@@ -145,11 +152,23 @@ const restored = vectlite.restore('/backups/full/', 'restored.vdb')
 ### Read-Only Mode
 
 ```js
-const ro = vectlite.open('knowledge.vdb', { readOnly: true })
+const ro = vectlite.open('knowledge.vdb', { readOnly: true, lockTimeout: 5 })
 const results = ro.search(query, { k: 5 }) // Reads work
 ro.upsert(...)                              // Throws VectLiteError
 ```
 
+### Listing, Counting, and Lifecycle
+
+```js
+const db = vectlite.open('knowledge.vdb', { dimension: 384, lockTimeout: 5 })
+
+const records = db.list({ namespace: 'docs', filter: { stale: false }, limit: 20 })
+const count = db.count({ namespace: 'docs', filter: { source: 'blog' } })
+const deleted = db.deleteByFilter({ stale: true }, { namespace: 'docs' })
+
+db.close()
+```
+
 ### Search Diagnostics
 
 ```js
@@ -164,6 +183,46 @@ console.log(outcome.stats.used_ann)     // true
 console.log(outcome.results[0].explain) // Detailed scoring breakdown
 ```
 
+## Database Methods Reference
+
+### Write Methods
+
+| Method | Description |
+|---|---|
+| `db.upsert(id, vector, metadata, options)` | Insert or update a single record |
+| `db.insert(id, vector, metadata, options)` | Insert a record (throws on duplicate id) |
+| `db.upsertMany(records, { namespace })` | Upsert a batch of records |
+| `db.insertMany(records, { namespace })` | Insert a batch |
+| `db.bulkIngest(records, { namespace, batchSize })` | Fastest bulk import with batched WAL writes |
+| `db.delete(id, { namespace })` | Delete a single record |
+| `db.deleteMany(ids, { namespace })` | Delete multiple records by id |
+| `db.deleteByFilter(filter, { namespace })` | Delete all records matching a filter |
+
+### Read Methods
+
+| Method | Description |
+|---|---|
+| `db.get(id, { namespace })` | Get a single record by id |
+| `db.search(query, options)` | Search and return a list of results |
+| `db.searchWithStats(query, options)` | Search with detailed performance stats |
+| `db.count({ namespace, filter })` | Count records, optionally scoped by namespace/filter |
+| `db.list({ namespace, filter, limit, offset })` | List records without issuing a vector query |
+| `db.namespaces()` | List all namespaces |
+| `db.dimension` | Vector dimension (property) |
+| `db.path` | Database file path (property) |
+| `db.readOnly` | Whether the database is read-only (property) |
+
+### Maintenance Methods
+
+| Method | Description |
+|---|---|
+| `db.compact()` | Fold WAL into snapshot and persist ANN indexes |
+| `db.flush()` | Alias for `compact()` |
+| `db.snapshot(dest)` | Create a self-contained `.vdb` copy |
+| `db.backup(destDir)` | Full backup including ANN sidecar files |
+| `db.transaction()` | Begin an atomic transaction |
+| `db.close()` | Flush pending state, release the file lock, and invalidate the handle |
+
 ## Filter Operators
 
 | Operator | Example | Description |

package/index.d.ts

@@ -82,6 +82,16 @@ export interface WriteOptions {
   vectors?: NamedVectors | null
 }
 
+export interface CountOptions {
+  namespace?: string | null
+  filter?: Filter | null
+}
+
+export interface ListOptions extends CountOptions {
+  limit?: number | null
+  offset?: number | null
+}
+
 export interface BulkIngestOptions {
   namespace?: string | null
   batchSize?: number
@@ -108,6 +118,7 @@ export interface SearchOptions {
 export interface OpenOptions {
   dimension?: number | null
   readOnly?: boolean
+  lockTimeout?: number | null
 }
 
 export class VectLiteError extends Error {}
@@ -130,8 +141,10 @@ export class Database {
   readonly dimension: number
   readonly readOnly: boolean
 
-  count(): number
+  count(options?: CountOptions): number
   namespaces(): string[]
+  close(): void
+  list(options?: ListOptions): Record[]
   transaction(): Transaction
   insert(id: string, vector: number[], metadata?: Metadata | null, options?: WriteOptions): void
   upsert(id: string, vector: number[], metadata?: Metadata | null, options?: WriteOptions): void
@@ -141,6 +154,7 @@ export class Database {
   get(id: string, options?: { namespace?: string | null }): Record | null
   delete(id: string, options?: { namespace?: string | null }): boolean
   deleteMany(ids: string[], options?: { namespace?: string | null }): number
+  deleteByFilter(filter: Filter, options?: { namespace?: string | null }): number
   flush(): void
   compact(): void
   snapshot(dest: string): void

package/index.js

@@ -209,14 +209,31 @@ class Database {
     return wrapError(() => this._native.readOnly)
   }
 
-  count() {
-    return wrapError(() => this._native.count())
+  count(options = {}) {
+    return wrapError(() => this._native.count(options.namespace ?? null, encode(options.filter)))
   }
 
   namespaces() {
     return wrapError(() => this._native.namespaces())
   }
 
+  close() {
+    return wrapError(() => this._native.close())
+  }
+
+  list(options = {}) {
+    return wrapError(() =>
+      decode(
+        this._native.list(
+          options.namespace ?? null,
+          encode(options.filter),
+          options.limit ?? null,
+          options.offset ?? null,
+        ),
+      ),
+    )
+  }
+
   transaction() {
     return wrapError(() => new Transaction(this._native.transaction()))
   }
@@ -261,6 +278,10 @@ class Database {
     return wrapError(() => this._native.deleteMany(ids, options.namespace ?? null))
   }
 
+  deleteByFilter(filter, options = {}) {
+    return wrapError(() => this._native.deleteByFilter(encode(filter), options.namespace ?? null))
+  }
+
   flush() {
     return wrapError(() => this._native.flush())
   }
@@ -323,7 +344,9 @@ class Store {
 }
 
 function open(path, options = {}) {
-  return wrapError(() => new Database(native.open(path, options.dimension ?? null, options.readOnly ?? false)))
+  return wrapError(() =>
+    new Database(native.open(path, options.dimension ?? null, options.readOnly ?? false, options.lockTimeout ?? null)),
+  )
 }
 
 function openStore(root) {

package/native/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "vectlite-node"
-version = "0.1.8"
+version = "0.1.11"
 edition = "2024"
 license = "MIT"
 description = "Node.js bindings for vectlite."

package/native/src/lib.rs

@@ -133,9 +133,21 @@ impl NativeDatabase {
     }
 
     #[napi]
-    pub fn count(&self) -> Result<u32> {
+    pub fn count(&self, namespace: Option<String>, filter_json: Option<String>) -> Result<u32> {
+        let filter = filter_json
+            .as_ref()
+            .map(|json_str| {
+                let value: serde_json::Value = serde_json::from_str(json_str)
+                    .map_err(|e| err(format!("invalid filter JSON: {e}")))?;
+                json_to_filter(&value)
+            })
+            .transpose()?;
+        if namespace.is_none() && filter.is_none() {
+            let database = self.read()?;
+            return Ok(database.len() as u32);
+        }
         let database = self.read()?;
-        Ok(database.len() as u32)
+        Ok(database.count_filtered(namespace.as_deref(), filter.as_ref()) as u32)
     }
 
     #[napi]
@@ -145,11 +157,63 @@ impl NativeDatabase {
     }
 
     #[napi]
-    pub fn transaction(&self) -> NativeTransaction {
-        NativeTransaction {
+    pub fn close(&self) -> Result<()> {
+        let mut database = self.write()?;
+        database.close().map_err(to_napi_error)
+    }
+
+    #[napi]
+    pub fn list(
+        &self,
+        namespace: Option<String>,
+        filter_json: Option<String>,
+        limit: Option<u32>,
+        offset: Option<u32>,
+    ) -> Result<String> {
+        let filter = filter_json
+            .as_ref()
+            .map(|json_str| {
+                let value: serde_json::Value = serde_json::from_str(json_str)
+                    .map_err(|e| err(format!("invalid filter JSON: {e}")))?;
+                json_to_filter(&value)
+            })
+            .transpose()?;
+        let records = {
+            let database = self.read()?;
+            database
+                .list(
+                    namespace.as_deref(),
+                    filter.as_ref(),
+                    limit.unwrap_or(0) as usize,
+                    offset.unwrap_or(0) as usize,
+                )
+                .into_iter()
+                .cloned()
+                .collect::<Vec<_>>()
+        };
+        let json_records: Vec<Value> = records.iter().map(record_to_json).collect();
+        stringify_value(Value::Array(json_records))
+    }
+
+    #[napi(js_name = "deleteByFilter")]
+    pub fn delete_by_filter(&self, filter_json: String, namespace: Option<String>) -> Result<u32> {
+        let value: serde_json::Value = serde_json::from_str(&filter_json)
+            .map_err(|e| err(format!("invalid filter JSON: {e}")))?;
+        let filter = json_to_filter(&value)?;
+        let mut database = self.write_open()?;
+        database
+            .delete_by_filter(namespace.as_deref(), &filter)
+            .map(|count| count as u32)
+            .map_err(to_napi_error)
+    }
+
+    #[napi]
+    pub fn transaction(&self) -> Result<NativeTransaction> {
+        drop(self.read()?);
+        Ok(NativeTransaction {
             inner: Arc::clone(&self.inner),
             staged: Mutex::new(TransactionState::default()),
-        }
+        })
     }
 
     #[napi]
@@ -166,7 +230,7 @@ impl NativeDatabase {
         let sparse = parse_sparse_json(sparse_json)?;
         let vectors = parse_named_vectors_json(vectors_json)?;
         let vector = js_vector_to_core(vector, "vector")?;
-        let mut database = self.write()?;
+        let mut database = self.write_open()?;
         database
             .insert_with_vectors_in_namespace(
                 namespace.unwrap_or_default(),
@@ -193,7 +257,7 @@ impl NativeDatabase {
         let sparse = parse_sparse_json(sparse_json)?;
         let vectors = parse_named_vectors_json(vectors_json)?;
         let vector = js_vector_to_core(vector, "vector")?;
-        let mut database = self.write()?;
+        let mut database = self.write_open()?;
         database
             .upsert_with_vectors_in_namespace(
                 namespace.unwrap_or_default(),
@@ -209,7 +273,7 @@ impl NativeDatabase {
     #[napi(js_name = "insertMany")]
     pub fn insert_many(&self, records_json: String, namespace: Option<String>) -> Result<u32> {
         let records = parse_record_batch_json(&records_json, namespace.as_deref())?;
-        let mut database = self.write()?;
+        let mut database = self.write_open()?;
         database
             .insert_many(records)
             .map(|count| count as u32)
@@ -219,7 +283,7 @@ impl NativeDatabase {
     #[napi(js_name = "upsertMany")]
     pub fn upsert_many(&self, records_json: String, namespace: Option<String>) -> Result<u32> {
         let records = parse_record_batch_json(&records_json, namespace.as_deref())?;
-        let mut database = self.write()?;
+        let mut database = self.write_open()?;
         database
             .upsert_many(records)
             .map(|count| count as u32)
@@ -234,7 +298,7 @@ impl NativeDatabase {
         batch_size: u32,
     ) -> Result<u32> {
         let records = parse_record_batch_json(&records_json, namespace.as_deref())?;
-        let mut database = self.write()?;
+        let mut database = self.write_open()?;
         database
             .bulk_ingest(records, batch_size as usize)
             .map(|count| count as u32)
@@ -257,7 +321,7 @@ impl NativeDatabase {
 
     #[napi]
     pub fn delete(&self, id: String, namespace: Option<String>) -> Result<bool> {
-        let mut database = self.write()?;
+        let mut database = self.write_open()?;
         database
             .delete_in_namespace(&namespace.unwrap_or_default(), &id)
             .map_err(to_napi_error)
@@ -265,7 +329,7 @@ impl NativeDatabase {
 
     #[napi(js_name = "deleteMany")]
     pub fn delete_many(&self, ids: Vec<String>, namespace: Option<String>) -> Result<u32> {
-        let mut database = self.write()?;
+        let mut database = self.write_open()?;
         database
             .delete_many_in_namespace(&namespace.unwrap_or_default(), ids)
             .map(|count| count as u32)
@@ -274,13 +338,13 @@ impl NativeDatabase {
 
     #[napi]
     pub fn flush(&self) -> Result<()> {
-        let mut database = self.write()?;
+        let mut database = self.write_open()?;
         database.flush().map_err(to_napi_error)
     }
 
     #[napi]
     pub fn compact(&self) -> Result<()> {
-        let mut database = self.write()?;
+        let mut database = self.write_open()?;
         database.compact().map_err(to_napi_error)
     }
 
@@ -478,9 +542,14 @@ impl NativeTransaction {
 
 impl NativeDatabase {
     fn read(&self) -> Result<RwLockReadGuard<'_, CoreDatabase>> {
-        self.inner
+        let database = self
+            .inner
             .read()
-            .map_err(|_| err("database read lock poisoned"))
+            .map_err(|_| err("database read lock poisoned"))?;
+        if database.is_closed() {
+            return Err(to_napi_error(closed_database_error()));
+        }
+        Ok(database)
     }
 
     fn write(&self) -> Result<RwLockWriteGuard<'_, CoreDatabase>> {
@@ -489,6 +558,14 @@ impl NativeDatabase {
             .map_err(|_| err("database write lock poisoned"))
     }
 
+    fn write_open(&self) -> Result<RwLockWriteGuard<'_, CoreDatabase>> {
+        let database = self.write()?;
+        if database.is_closed() {
+            return Err(to_napi_error(closed_database_error()));
+        }
+        Ok(database)
+    }
+
     fn execute_search(
         &self,
         query: Option<Vec<f32>>,
@@ -522,18 +599,40 @@ impl NativeDatabase {
 }
 
 #[napi]
-pub fn open(path: String, dimension: Option<u32>, read_only: bool) -> Result<NativeDatabase> {
+pub fn open(
+    path: String,
+    dimension: Option<u32>,
+    read_only: bool,
+    lock_timeout: Option<f64>,
+) -> Result<NativeDatabase> {
     let database = if read_only {
         if !Path::new(&path).exists() {
             return Err(err("cannot open non-existent database in read-only mode"));
         }
-        CoreDatabase::open_read_only(&path).map_err(to_napi_error)?
+        match lock_timeout {
+            Some(timeout) => CoreDatabase::open_read_only_with_timeout(&path, Some(timeout))
+                .map_err(to_napi_error)?,
+            None => CoreDatabase::open_read_only(&path).map_err(to_napi_error)?,
+        }
     } else if Path::new(&path).exists() {
-        match dimension {
-            Some(dimension) => {
+        match (dimension, lock_timeout) {
+            (Some(dimension), Some(timeout)) => {
+                let db = CoreDatabase::open_with_timeout(&path, timeout).map_err(to_napi_error)?;
+                if db.dimension() != dimension as usize {
+                    return Err(to_napi_error(vectlite::VectLiteError::DimensionMismatch {
+                        expected: db.dimension(),
+                        found: dimension as usize,
+                    }));
+                }
+                db
+            }
+            (Some(dimension), None) => {
                 CoreDatabase::open_or_create(&path, dimension as usize).map_err(to_napi_error)?
             }
-            None => CoreDatabase::open(&path).map_err(to_napi_error)?,
+            (None, Some(timeout)) => {
+                CoreDatabase::open_with_timeout(&path, timeout).map_err(to_napi_error)?
+            }
+            (None, None) => CoreDatabase::open(&path).map_err(to_napi_error)?,
         }
     } else {
         let Some(dimension) = dimension else {
@@ -1212,3 +1311,7 @@ fn err(message: impl Into<String>) -> NapiError {
 fn to_napi_error(error: vectlite::VectLiteError) -> NapiError {
     err(error.to_string())
 }
+
+fn closed_database_error() -> vectlite::VectLiteError {
+    vectlite::VectLiteError::InvalidFormat("database is closed".to_owned())
+}

package/native/vectlite-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "vectlite-core"
-version = "0.1.8"
+version = "0.1.11"
 edition = "2024"
 license = "MIT"
 description = "Core storage engine for vectlite."

package/native/vectlite-core/src/lib.rs

@@ -81,7 +81,9 @@ impl fmt::Display for VectLiteError {
             Self::DimensionMismatch { expected, found } => {
                 write!(
                     f,
-                    "vector dimension mismatch: expected {expected}, found {found}"
+                    "vector dimension mismatch: expected {expected}, found {found}. \
+                     If you changed embedding models, delete the existing .vdb file \
+                     or use a different path to create a new database with dimension {found}"
                 )
             }
             Self::DuplicateId { namespace, id } => {
@@ -808,12 +810,44 @@ impl Database {
         Ok(database)
     }
 
+    /// Open an existing database with a lock timeout in seconds.
+    /// If the lock cannot be acquired within the timeout, returns
+    /// `VectLiteError::LockContention`.
+    pub fn open_with_timeout(path: impl AsRef<Path>, timeout_secs: f64) -> Result<Self> {
+        let path = path.as_ref().to_path_buf();
+        let timeout = timeout_duration(timeout_secs, "lock_timeout")?;
+        let lock = acquire_exclusive_lock_with_timeout(&path, Some(timeout))?;
+        let mut file = File::open(&path)?;
+        let mut database = Self::read_from(&path, &mut file)?;
+        database._lock_file = Some(lock);
+        database.read_only = false;
+        database.replay_wal()?;
+        database.rebuild_sparse_index();
+        database.ann_loaded_from_disk = database.try_load_ann_from_disk();
+        if !database.ann_loaded_from_disk {
+            database.rebuild_ann();
+        }
+        Ok(database)
+    }
+
     /// Open an existing database in read-only mode. Acquires a shared lock
     /// so multiple readers can coexist. All write operations will return
     /// `VectLiteError::ReadOnly`.
     pub fn open_read_only(path: impl AsRef<Path>) -> Result<Self> {
+        Self::open_read_only_with_timeout(path, None)
+    }
+
+    /// Open an existing database in read-only mode, optionally waiting for a
+    /// shared lock to become available.
+    pub fn open_read_only_with_timeout(
+        path: impl AsRef<Path>,
+        timeout_secs: Option<f64>,
+    ) -> Result<Self> {
         let path = path.as_ref().to_path_buf();
-        let lock = acquire_shared_lock(&path)?;
+        let timeout = timeout_secs
+            .map(|seconds| timeout_duration(seconds, "lock_timeout"))
+            .transpose()?;
+        let lock = acquire_shared_lock_with_timeout(&path, timeout)?;
         let mut file = File::open(&path)?;
         let mut database = Self::read_from(&path, &mut file)?;
         database._lock_file = Some(lock);
@@ -831,7 +865,43 @@ impl Database {
         self.read_only
     }
 
+    /// Returns true if the database has been closed.
+    pub fn is_closed(&self) -> bool {
+        self._lock_file.is_none() && self.records.is_empty() && self.dimension == 0
+    }
+
+    /// Close the database: flush WAL (if writable), release the file lock,
+    /// and clear all in-memory state.  After calling this, any further
+    /// operation will return an error.
+    pub fn close(&mut self) -> Result<()> {
+        if self.is_closed() {
+            return Ok(());
+        }
+        // Flush WAL to main file if writable
+        if !self.read_only {
+            self.compact_inner()?;
+        }
+        // Release the lock by dropping the file handle
+        self._lock_file = None;
+        // Clear in-memory state
+        self.records.clear();
+        self.ann = AnnCatalog::default();
+        self.sparse_index = SparseIndex::default();
+        self.dimension = 0;
+        Ok(())
+    }
+
+    fn check_open(&self) -> Result<()> {
+        if self.is_closed() {
+            return Err(VectLiteError::InvalidFormat(
+                "database is closed".to_owned(),
+            ));
+        }
+        Ok(())
+    }
+
     fn check_writable(&self) -> Result<()> {
+        self.check_open()?;
         if self.read_only {
             return Err(VectLiteError::ReadOnly);
         }
@@ -869,6 +939,95 @@ impl Database {
         self.records.is_empty()
     }
 
+    /// Count records, optionally filtered by namespace and/or metadata filter.
+    pub fn count_filtered(
+        &self,
+        namespace: Option<&str>,
+        filter: Option<&MetadataFilter>,
+    ) -> usize {
+        self.records
+            .iter()
+            .filter(|((ns, _), record)| {
+                if let Some(target_ns) = namespace {
+                    if ns != target_ns {
+                        return false;
+                    }
+                }
+                if let Some(filter) = filter {
+                    if !filter.matches(&record.metadata) {
+                        return false;
+                    }
+                }
+                true
+            })
+            .count()
+    }
+
+    /// List records by namespace and/or metadata filter without requiring a
+    /// vector query.  Returns records ordered by (namespace, id).
+    pub fn list(
+        &self,
+        namespace: Option<&str>,
+        filter: Option<&MetadataFilter>,
+        limit: usize,
+        offset: usize,
+    ) -> Vec<&Record> {
+        self.records
+            .iter()
+            .filter(|((ns, _), record)| {
+                if let Some(target_ns) = namespace {
+                    if ns != target_ns {
+                        return false;
+                    }
+                }
+                if let Some(filter) = filter {
+                    if !filter.matches(&record.metadata) {
+                        return false;
+                    }
+                }
+                true
+            })
+            .skip(offset)
+            .take(if limit == 0 { usize::MAX } else { limit })
+            .map(|(_, record)| record)
+            .collect()
+    }
+
+    /// Delete all records matching a filter, optionally within a namespace.
+    /// Returns the number of records deleted.
+    pub fn delete_by_filter(
+        &mut self,
+        namespace: Option<&str>,
+        filter: &MetadataFilter,
+    ) -> Result<usize> {
+        self.check_writable()?;
+        let keys_to_delete: Vec<(String, String)> = self
+            .records
+            .iter()
+            .filter(|((ns, _), record)| {
+                if let Some(target_ns) = namespace {
+                    if ns != target_ns {
+                        return false;
+                    }
+                }
+                filter.matches(&record.metadata)
+            })
+            .map(|(key, _)| key.clone())
+            .collect();
+
+        let count = keys_to_delete.len();
+        if count == 0 {
+            return Ok(0);
+        }
+
+        let ops: Vec<WalOp> = keys_to_delete
+            .into_iter()
+            .map(|(namespace, id)| WalOp::Delete { namespace, id })
+            .collect();
+        self.apply_wal_batch(ops)?;
+        Ok(count)
+    }
+
     pub fn insert(
         &mut self,
         id: impl Into<String>,
@@ -1026,7 +1185,11 @@ impl Database {
             return Ok(0);
         }
 
-        self.apply_wal_batch(records.into_iter().map(WalOp::Upsert).collect())?;
+        self.apply_wal_batch_deferred(records.into_iter().map(WalOp::Upsert).collect())?;
+        self.rebuild_sparse_index();
+        self.rebuild_ann();
+        self.ann_loaded_from_disk = false;
+        self.persist_ann_to_disk()?;
         Ok(count)
     }
 
@@ -1048,7 +1211,11 @@ impl Database {
             return Ok(0);
         }
 
-        self.apply_wal_batch(records.into_iter().map(WalOp::Upsert).collect())?;
+        self.apply_wal_batch_deferred(records.into_iter().map(WalOp::Upsert).collect())?;
+        self.rebuild_sparse_index();
+        self.rebuild_ann();
+        self.ann_loaded_from_disk = false;
+        self.persist_ann_to_disk()?;
         Ok(count)
     }
 
@@ -1239,7 +1406,15 @@ impl Database {
                 WriteOperation::Delete { namespace, id } => Ok(WalOp::Delete { namespace, id }),
             })
             .collect::<Result<Vec<_>>>()?;
-        self.apply_wal_batch(ops)
+        if ops.is_empty() {
+            return Ok(());
+        }
+        self.apply_wal_batch_deferred(ops)?;
+        self.rebuild_sparse_index();
+        self.rebuild_ann();
+        self.ann_loaded_from_disk = false;
+        self.persist_ann_to_disk()?;
+        Ok(())
     }
 
     fn hybrid_search_internal(
@@ -1249,6 +1424,7 @@ impl Database {
         options: HybridSearchOptions,
         namespace: Option<&str>,
     ) -> Result<SearchOutcome> {
+        self.check_open()?;
         if let Some(query) = dense_query {
             self.validate_vector(query)?;
         }
@@ -1298,7 +1474,9 @@ impl Database {
             .unwrap_or_default();
         let sparse_us = sparse_start.elapsed().as_micros() as u64;
 
-        let candidate_keys = if dense_query.is_some() && ann_candidates.is_none() {
+        let candidate_keys = if dense_query.is_none() {
+            Some(sparse_candidates.clone())
+        } else if dense_query.is_some() && ann_candidates.is_none() {
             None
         } else {
             merge_candidate_keys(
@@ -1459,6 +1637,7 @@ impl Database {
     /// self-contained `.vdb` file (WAL is folded in). The current database is
     /// not modified. Works in both read-only and read-write mode.
     pub fn snapshot(&self, dest: impl AsRef<Path>) -> Result<()> {
+        self.check_open()?;
         let dest = dest.as_ref();
         if let Some(parent) = dest.parent() {
             if !parent.as_os_str().is_empty() {
@@ -1479,6 +1658,7 @@ impl Database {
     /// including the `.vdb` file and ANN sidecar files. The backup is
     /// compacted (WAL folded in). Works in both read-only and read-write mode.
     pub fn backup(&self, dest: impl AsRef<Path>) -> Result<()> {
+        self.check_open()?;
         let dest = dest.as_ref();
         fs::create_dir_all(dest)?;
 
@@ -1562,15 +1742,45 @@ impl Database {
             return Ok(());
         }
 
+        let has_sparse = ops.iter().any(|op| match op {
+            WalOp::Upsert(record) => {
+                !record.sparse.is_empty()
+                    || self
+                        .records
+                        .get(&(record.namespace.clone(), record.id.clone()))
+                        .map_or(false, |r| !r.sparse.is_empty())
+            }
+            WalOp::Delete { namespace, id } => self
+                .records
+                .get(&(namespace.clone(), id.clone()))
+                .map_or(false, |r| !r.sparse.is_empty()),
+        });
+
         self.append_wal_batch(&ops)?;
         self.apply_ops_in_memory(ops);
-        self.rebuild_sparse_index();
+
+        if has_sparse {
+            self.rebuild_sparse_index();
+        }
         self.rebuild_ann();
         self.ann_loaded_from_disk = false;
         self.persist_ann_to_disk()?;
         Ok(())
     }
 
+    /// Write ops to WAL and apply in memory, but defer index rebuilds.
+    /// The caller is responsible for calling `rebuild_sparse_index()`,
+    /// `rebuild_ann()`, and `persist_ann_to_disk()` after all batches are done.
+    fn apply_wal_batch_deferred(&mut self, ops: Vec<WalOp>) -> Result<()> {
+        if ops.is_empty() {
+            return Ok(());
+        }
+
+        self.append_wal_batch(&ops)?;
+        self.apply_ops_in_memory(ops);
+        Ok(())
+    }
+
     fn apply_ops_in_memory(&mut self, ops: Vec<WalOp>) {
         for op in ops {
             match op {
@@ -2409,6 +2619,15 @@ fn candidate_count(top_k: usize, total: usize) -> usize {
         .min(total)
 }
 
+fn timeout_duration(timeout_secs: f64, label: &str) -> Result<std::time::Duration> {
+    if !timeout_secs.is_finite() || timeout_secs < 0.0 {
+        return Err(VectLiteError::InvalidFormat(format!(
+            "{label} must be a finite, non-negative number of seconds"
+        )));
+    }
+    Ok(std::time::Duration::from_secs_f64(timeout_secs))
+}
+
 fn wal_path(path: &Path) -> PathBuf {
     let mut wal = path.as_os_str().to_os_string();
     wal.push(".wal");
@@ -2422,6 +2641,13 @@ fn lock_path(path: &Path) -> PathBuf {
 }
 
 fn acquire_exclusive_lock(path: &Path) -> Result<File> {
+    acquire_exclusive_lock_with_timeout(path, None)
+}
+
+fn acquire_exclusive_lock_with_timeout(
+    path: &Path,
+    timeout: Option<std::time::Duration>,
+) -> Result<File> {
     if let Some(parent) = path.parent() {
         if !parent.as_os_str().is_empty() && !parent.exists() {
             fs::create_dir_all(parent)?;
@@ -2433,16 +2659,43 @@ fn acquire_exclusive_lock(path: &Path) -> Result<File> {
         .read(true)
         .write(true)
         .open(lock_path(path))?;
-    file.try_lock_exclusive().map_err(|err| {
-        VectLiteError::LockContention(format!(
-            "could not acquire exclusive lock on '{}': {err}",
-            path.display()
-        ))
-    })?;
+
+    match timeout {
+        None => {
+            file.try_lock_exclusive().map_err(|err| {
+                VectLiteError::LockContention(format!(
+                    "could not acquire exclusive lock on '{}': {err}",
+                    path.display()
+                ))
+            })?;
+        }
+        Some(duration) => {
+            let start = Instant::now();
+            let interval = std::time::Duration::from_millis(50);
+            loop {
+                match file.try_lock_exclusive() {
+                    Ok(()) => break,
+                    Err(err) => {
+                        if start.elapsed() >= duration {
+                            return Err(VectLiteError::LockContention(format!(
+                                "could not acquire exclusive lock on '{}' after {:.1}s: {err}",
+                                path.display(),
+                                duration.as_secs_f64()
+                            )));
+                        }
+                        std::thread::sleep(interval);
+                    }
+                }
+            }
+        }
+    }
     Ok(file)
 }
 
-fn acquire_shared_lock(path: &Path) -> Result<File> {
+fn acquire_shared_lock_with_timeout(
+    path: &Path,
+    timeout: Option<std::time::Duration>,
+) -> Result<File> {
     let lock_file = lock_path(path);
     if !lock_file.exists() {
         // Lock file may not exist yet for read-only opens on existing dbs
@@ -2458,12 +2711,36 @@ fn acquire_shared_lock(path: &Path) -> Result<File> {
         .read(true)
         .write(true)
         .open(&lock_file)?;
-    file.try_lock_shared().map_err(|err| {
-        VectLiteError::LockContention(format!(
-            "could not acquire shared lock on '{}': {err}",
-            path.display()
-        ))
-    })?;
+
+    match timeout {
+        None => {
+            file.try_lock_shared().map_err(|err| {
+                VectLiteError::LockContention(format!(
+                    "could not acquire shared lock on '{}': {err}",
+                    path.display()
+                ))
+            })?;
+        }
+        Some(duration) => {
+            let start = Instant::now();
+            let interval = std::time::Duration::from_millis(50);
+            loop {
+                match file.try_lock_shared() {
+                    Ok(()) => break,
+                    Err(err) => {
+                        if start.elapsed() >= duration {
+                            return Err(VectLiteError::LockContention(format!(
+                                "could not acquire shared lock on '{}' after {:.1}s: {err}",
+                                path.display(),
+                                duration.as_secs_f64()
+                            )));
+                        }
+                        std::thread::sleep(interval);
+                    }
+                }
+            }
+        }
+    }
     Ok(file)
 }
 
@@ -3088,7 +3365,7 @@ fn usize_from_u64(value: u64) -> Result<usize> {
 mod tests {
     use super::{
         Database, HybridSearchOptions, Metadata, MetadataFilter, MetadataValue, NamedVectors,
-        Record, SearchOptions, SparseVector,
+        Record, SearchOptions, SparseVector, VectLiteError,
     };
     use std::path::{Path, PathBuf};
     use std::time::{SystemTime, UNIX_EPOCH};
@@ -3343,6 +3620,67 @@ mod tests {
         cleanup(&path);
     }
 
+    #[test]
+    fn upsert_without_sparse_rebuilds_sparse_index() {
+        let path = temp_file("sparse-upsert-clear");
+        let mut database = Database::create(&path, 2).expect("create database");
+
+        let mut sparse_auth = SparseVector::new();
+        sparse_auth.insert("auth".to_owned(), 1.0);
+
+        database
+            .upsert_with_sparse_in_namespace(
+                "docs",
+                "doc1",
+                vec![1.0, 0.0],
+                sparse_auth,
+                Metadata::new(),
+            )
+            .expect("insert sparse doc");
+
+        let mut query_sparse = SparseVector::new();
+        query_sparse.insert("auth".to_owned(), 1.0);
+
+        let initial_outcome = database
+            .hybrid_search_in_namespace_with_stats(
+                "docs",
+                None,
+                Some(&query_sparse),
+                HybridSearchOptions {
+                    top_k: 10,
+                    filter: None,
+                    dense_weight: 0.0,
+                    sparse_weight: 1.0,
+                    ..HybridSearchOptions::default()
+                },
+            )
+            .expect("initial sparse search");
+        assert_eq!(initial_outcome.stats.sparse_candidate_count, 1);
+
+        database
+            .upsert_in_namespace("docs", "doc1", vec![1.0, 0.0], Metadata::new())
+            .expect("replace doc without sparse terms");
+
+        let updated_outcome = database
+            .hybrid_search_in_namespace_with_stats(
+                "docs",
+                None,
+                Some(&query_sparse),
+                HybridSearchOptions {
+                    top_k: 10,
+                    filter: None,
+                    dense_weight: 0.0,
+                    sparse_weight: 1.0,
+                    ..HybridSearchOptions::default()
+                },
+            )
+            .expect("sparse search after clearing sparse terms");
+        assert_eq!(updated_outcome.stats.sparse_candidate_count, 0);
+        assert!(updated_outcome.results.is_empty());
+
+        cleanup(&path);
+    }
+
     #[test]
     fn named_vectors_roundtrip_and_search() {
         let path = temp_file("named-vectors");
@@ -3528,6 +3866,69 @@ mod tests {
         cleanup(&path);
     }
 
+    #[test]
+    fn closed_database_rejects_result_based_operations() {
+        let path = temp_file("closed-db");
+        let snapshot = temp_file("closed-db-snapshot");
+        let mut database = Database::create(&path, 2).expect("create database");
+        database
+            .insert("doc1", vec![1.0, 0.0], Metadata::new())
+            .expect("insert doc1");
+        database.close().expect("close database");
+
+        let search_err = database
+            .search(
+                &[1.0, 0.0],
+                SearchOptions {
+                    top_k: 1,
+                    filter: None,
+                },
+            )
+            .expect_err("search on closed database should fail");
+        assert!(matches!(
+            search_err,
+            VectLiteError::InvalidFormat(message) if message.contains("database is closed")
+        ));
+
+        let snapshot_err = database
+            .snapshot(&snapshot)
+            .expect_err("snapshot on closed database should fail");
+        assert!(matches!(
+            snapshot_err,
+            VectLiteError::InvalidFormat(message) if message.contains("database is closed")
+        ));
+
+        cleanup(&path);
+        cleanup(&snapshot);
+    }
+
+    #[test]
+    fn lock_timeout_must_be_non_negative_and_finite() {
+        let path = temp_file("timeout-validation");
+        let database = Database::create(&path, 2).expect("create database");
+
+        let negative_err = match Database::open_with_timeout(&path, -1.0) {
+            Ok(_) => panic!("negative lock timeout should fail"),
+            Err(err) => err,
+        };
+        assert!(matches!(
+            negative_err,
+            VectLiteError::InvalidFormat(message) if message.contains("lock_timeout")
+        ));
+
+        let nan_err = match Database::open_with_timeout(&path, f64::NAN) {
+            Ok(_) => panic!("NaN lock timeout should fail"),
+            Err(err) => err,
+        };
+        assert!(matches!(
+            nan_err,
+            VectLiteError::InvalidFormat(message) if message.contains("lock_timeout")
+        ));
+
+        drop(database);
+        cleanup(&path);
+    }
+
     fn temp_file(name: &str) -> PathBuf {
         let nanos = SystemTime::now()
             .duration_since(UNIX_EPOCH)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vectlite",
-  "version": "0.1.8",
+  "version": "0.1.11",
   "description": "Embedded vector store for local-first AI applications.",
   "main": "index.js",
   "types": "index.d.ts",