barrel_vectordb_index_faiss (barrel_vectordb v2.1.2)
View SourceFAISS backend wrapper for barrel_vectordb_index behaviour
Wraps barrel_faiss (Facebook FAISS NIF bindings) with: - ID mapping: binary IDs <-> sequential integer labels - Soft delete: deleted IDs filtered from search results - Metric normalization: cosine via normalized inner product - Combined serialization: FAISS binary + Erlang state
Delete Strategy
FAISS doesn't support deletion natively. This backend uses soft delete: deleted IDs are added to a set and filtered from search results. Use compact/1 to rebuild the index without deleted vectors.
Summary
Functions
Close and release FAISS index resources.
Compact the index by rebuilding without deleted vectors. This reclaims space used by soft-deleted vectors.
Delete a vector by ID (soft delete).
Get the number of soft-deleted vectors.
Deserialize index from binary.
Get index information and statistics.
Insert a vector with the given ID.
Create a new FAISS index. Config options: - dimension: Vector dimension (required) - distance_fn: cosine | euclidean (default: cosine) - index_type: FAISS factory string (default: "HNSW32")
Search for K nearest neighbors.
Search for K nearest neighbors with options.
Serialize index to binary. Format: <<Version, FAISSLen, FAISSBin, StateLen, StateBin>>
Get the number of active (non-deleted) vectors.
Functions
-spec close(#faiss_state{index :: reference(), dimension :: pos_integer(), metric :: l2 | inner_product, distance_fn :: cosine | euclidean, id_to_label :: #{binary() => non_neg_integer()}, label_to_id :: #{non_neg_integer() => binary()}, vectors :: #{binary() => [float()]}, next_label :: non_neg_integer(), deleted_ids :: sets:set(binary()), config :: map()}) -> ok.
Close and release FAISS index resources.
-spec compact(#faiss_state{index :: reference(), dimension :: pos_integer(), metric :: l2 | inner_product, distance_fn :: cosine | euclidean, id_to_label :: #{binary() => non_neg_integer()}, label_to_id :: #{non_neg_integer() => binary()}, vectors :: #{binary() => [float()]}, next_label :: non_neg_integer(), deleted_ids :: sets:set(binary()), config :: map()}) -> {ok, #faiss_state{index :: reference(), dimension :: pos_integer(), metric :: l2 | inner_product, distance_fn :: cosine | euclidean, id_to_label :: #{binary() => non_neg_integer()}, label_to_id :: #{non_neg_integer() => binary()}, vectors :: #{binary() => [float()]}, next_label :: non_neg_integer(), deleted_ids :: sets:set(binary()), config :: map()}} | {error, term()}.
Compact the index by rebuilding without deleted vectors. This reclaims space used by soft-deleted vectors.
-spec delete(#faiss_state{index :: reference(), dimension :: pos_integer(), metric :: l2 | inner_product, distance_fn :: cosine | euclidean, id_to_label :: #{binary() => non_neg_integer()}, label_to_id :: #{non_neg_integer() => binary()}, vectors :: #{binary() => [float()]}, next_label :: non_neg_integer(), deleted_ids :: sets:set(binary()), config :: map()}, binary()) -> {ok, #faiss_state{index :: reference(), dimension :: pos_integer(), metric :: l2 | inner_product, distance_fn :: cosine | euclidean, id_to_label :: #{binary() => non_neg_integer()}, label_to_id :: #{non_neg_integer() => binary()}, vectors :: #{binary() => [float()]}, next_label :: non_neg_integer(), deleted_ids :: sets:set(binary()), config :: map()}} | {error, term()}.
Delete a vector by ID (soft delete).
-spec deleted_count(#faiss_state{index :: reference(), dimension :: pos_integer(), metric :: l2 | inner_product, distance_fn :: cosine | euclidean, id_to_label :: #{binary() => non_neg_integer()}, label_to_id :: #{non_neg_integer() => binary()}, vectors :: #{binary() => [float()]}, next_label :: non_neg_integer(), deleted_ids :: sets:set(binary()), config :: map()}) -> non_neg_integer().
Get the number of soft-deleted vectors.
-spec deserialize(binary()) -> {ok, #faiss_state{index :: reference(), dimension :: pos_integer(), metric :: l2 | inner_product, distance_fn :: cosine | euclidean, id_to_label :: #{binary() => non_neg_integer()}, label_to_id :: #{non_neg_integer() => binary()}, vectors :: #{binary() => [float()]}, next_label :: non_neg_integer(), deleted_ids :: sets:set(binary()), config :: map()}} | {error, term()}.
Deserialize index from binary.
-spec info(#faiss_state{index :: reference(), dimension :: pos_integer(), metric :: l2 | inner_product, distance_fn :: cosine | euclidean, id_to_label :: #{binary() => non_neg_integer()}, label_to_id :: #{non_neg_integer() => binary()}, vectors :: #{binary() => [float()]}, next_label :: non_neg_integer(), deleted_ids :: sets:set(binary()), config :: map()}) -> map().
Get index information and statistics.
-spec insert(#faiss_state{index :: reference(), dimension :: pos_integer(), metric :: l2 | inner_product, distance_fn :: cosine | euclidean, id_to_label :: #{binary() => non_neg_integer()}, label_to_id :: #{non_neg_integer() => binary()}, vectors :: #{binary() => [float()]}, next_label :: non_neg_integer(), deleted_ids :: sets:set(binary()), config :: map()}, binary(), [float()]) -> {ok, #faiss_state{index :: reference(), dimension :: pos_integer(), metric :: l2 | inner_product, distance_fn :: cosine | euclidean, id_to_label :: #{binary() => non_neg_integer()}, label_to_id :: #{non_neg_integer() => binary()}, vectors :: #{binary() => [float()]}, next_label :: non_neg_integer(), deleted_ids :: sets:set(binary()), config :: map()}} | {error, term()}.
Insert a vector with the given ID.
-spec new(map()) -> {ok, #faiss_state{index :: reference(), dimension :: pos_integer(), metric :: l2 | inner_product, distance_fn :: cosine | euclidean, id_to_label :: #{binary() => non_neg_integer()}, label_to_id :: #{non_neg_integer() => binary()}, vectors :: #{binary() => [float()]}, next_label :: non_neg_integer(), deleted_ids :: sets:set(binary()), config :: map()}} | {error, term()}.
Create a new FAISS index. Config options: - dimension: Vector dimension (required) - distance_fn: cosine | euclidean (default: cosine) - index_type: FAISS factory string (default: "HNSW32")
-spec search(#faiss_state{index :: reference(), dimension :: pos_integer(), metric :: l2 | inner_product, distance_fn :: cosine | euclidean, id_to_label :: #{binary() => non_neg_integer()}, label_to_id :: #{non_neg_integer() => binary()}, vectors :: #{binary() => [float()]}, next_label :: non_neg_integer(), deleted_ids :: sets:set(binary()), config :: map()}, [float()], pos_integer()) -> [{binary(), float()}].
Search for K nearest neighbors.
-spec search(#faiss_state{index :: reference(), dimension :: pos_integer(), metric :: l2 | inner_product, distance_fn :: cosine | euclidean, id_to_label :: #{binary() => non_neg_integer()}, label_to_id :: #{non_neg_integer() => binary()}, vectors :: #{binary() => [float()]}, next_label :: non_neg_integer(), deleted_ids :: sets:set(binary()), config :: map()}, [float()], pos_integer(), map()) -> [{binary(), float()}].
Search for K nearest neighbors with options.
-spec serialize(#faiss_state{index :: reference(), dimension :: pos_integer(), metric :: l2 | inner_product, distance_fn :: cosine | euclidean, id_to_label :: #{binary() => non_neg_integer()}, label_to_id :: #{non_neg_integer() => binary()}, vectors :: #{binary() => [float()]}, next_label :: non_neg_integer(), deleted_ids :: sets:set(binary()), config :: map()}) -> binary().
Serialize index to binary. Format: <<Version, FAISSLen, FAISSBin, StateLen, StateBin>>
-spec size(#faiss_state{index :: reference(), dimension :: pos_integer(), metric :: l2 | inner_product, distance_fn :: cosine | euclidean, id_to_label :: #{binary() => non_neg_integer()}, label_to_id :: #{non_neg_integer() => binary()}, vectors :: #{binary() => [float()]}, next_label :: non_neg_integer(), deleted_ids :: sets:set(binary()), config :: map()}) -> non_neg_integer().
Get the number of active (non-deleted) vectors.