​
Delete

Use delete_items(...) to delete records by external ID. 
import brinicle

engine = brinicle.VectorEngine("vector_index", dim=384)

deleted_count, not_found = engine.delete_items(
    ["id1", "id2"],
    return_not_found=True,
)

print(deleted_count)
print(not_found)
If return_not_found=False, the second returned value is None. Deletes are logical until the index is compacted. Deleted records are filtered out during search, but their storage is reclaimed during compact rebuild.

​
Parameters

ParameterTypeDefaultDescription
external_idslist[str]requiredList of external IDs to delete
return_not_foundboolFalseWhether to return IDs that were not found in the index

​
Return Value

The method returns a tuple of (deleted_count, not_found):
  • deleted_count — The number of items that were successfully deleted
  • not_found — A list of IDs that were not found in the index (only populated if return_not_found=True)

​
Checking for Not-Found IDs

By default, return_not_found=False for better performance. If you need to know which IDs were not found (perhaps to clean up your source data), set it to True: 
# Fast: just delete and count
deleted_count, _ = engine.delete_items(["id1", "id2", "id3"])

# Slower: also report which IDs didn't exist
deleted_count, not_found = engine.delete_items(
    ["id1", "id2", "id3"],
    return_not_found=True,
)

if not_found:
    print(f"Warning: these IDs were not in the index: {not_found}")

​
After Deletion

After deleting items, the HNSW graph still references the deleted nodes, but they are marked as removed and will not appear in search results. This lazy deletion approach is fast but can reduce search efficiency over time.

​
Checking if Rebuild is Needed

Use needs_rebuild() to check if the index would benefit from a compact rebuild after deletions: 
engine.delete_items(["id1", "id2", "id3"])

if engine.needs_rebuild():
    print("Index needs rebuild for optimal performance")
    engine.rebuild_compact()

​
Optimizing the Graph

For a lighter-weight alternative to a full rebuild, you can optimize the graph in place: 
engine.optimize_graph()
optimize_graph() checks whether the index needs rebuilding. If the update or delete ratio crosses the delta_ratio threshold, Brinicle rebuilds the graph. Otherwise, it does nothing. For unconditional compaction, use rebuild_compact().

​
Deleting All Data

To completely remove an index and all its data, use the destroy() method: 
engine.destroy()  # Permanently deletes all index files
This removes all index files from disk. Use with caution — this operation is irreversible.