Erlang API

Complete reference for the Barrel VectorDB Erlang API.

Store Management

start_link/1

Start a vector store.

-spec start_link(Config) -> {ok, pid()} | {error, Reason} when
    Config :: #{
        name := atom(),
        path => string(),
        dimensions => pos_integer(),
        backend => hnsw | faiss,
        embedder => embedder_config(),
        hnsw => hnsw_opts(),
        batch => batch_opts()
    },
    Reason :: term().

Example:

{ok, _} = barrel_vectordb:start_link(#{
    name => my_store,
    path => "/var/data/vectors",
    dimensions => 768,
    embedder => {local, #{}}
}).

stop/1

Stop a vector store.

-spec stop(Store) -> ok when Store :: atom().

stats/1

Get store statistics.

-spec stats(Store) -> {ok, Stats} when
    Store :: atom(),
    Stats :: #{
        count := non_neg_integer(),
        dimensions := pos_integer(),
        backend := atom()
    }.

Document Operations

add/4

Add a document with text (requires embedder).

-spec add(Store, Id, Text, Metadata) -> ok | {error, Reason} when
    Store :: atom(),
    Id :: binary(),
    Text :: binary(),
    Metadata :: map(),
    Reason :: embedder_not_configured | term().

add_vector/5

Add a document with pre-computed vector.

-spec add_vector(Store, Id, Text, Metadata, Vector) -> ok | {error, Reason} when
    Store :: atom(),
    Id :: binary(),
    Text :: binary(),
    Metadata :: map(),
    Vector :: [float()],
    Reason :: term().

add_batch/2

Add multiple documents in a batch.

-spec add_batch(Store, Docs) -> {ok, Result} | {error, Reason} when
    Store :: atom(),
    Docs :: [{Id, Text, Metadata}],
    Id :: binary(),
    Text :: binary(),
    Metadata :: map(),
    Result :: #{inserted := non_neg_integer()},
    Reason :: term().

get/2

Get a document by ID.

-spec get(Store, Id) -> {ok, Doc} | not_found | {error, Reason} when
    Store :: atom(),
    Id :: binary(),
    Doc :: #{
        id := binary(),
        text := binary(),
        metadata := map()
    },
    Reason :: term().

update/4

Update a document (requires embedder).

-spec update(Store, Id, Text, Metadata) -> ok | {error, Reason} when
    Store :: atom(),
    Id :: binary(),
    Text :: binary(),
    Metadata :: map(),
    Reason :: not_found | embedder_not_configured | term().

upsert/4

Insert or update a document (requires embedder).

-spec upsert(Store, Id, Text, Metadata) -> ok | {error, Reason} when
    Store :: atom(),
    Id :: binary(),
    Text :: binary(),
    Metadata :: map(),
    Reason :: embedder_not_configured | term().

delete/2

Delete a document.

-spec delete(Store, Id) -> ok | {error, Reason} when
    Store :: atom(),
    Id :: binary(),
    Reason :: term().

count/1

Count documents in store.

-spec count(Store) -> non_neg_integer() when Store :: atom().

peek/2

Sample documents from store.

-spec peek(Store, N) -> {ok, Docs} when
    Store :: atom(),
    N :: pos_integer(),
    Docs :: [map()].

checkpoint/1

Checkpoint HNSW index to disk.

-spec checkpoint(Store) -> ok | {error, Reason} when
    Store :: atom(),
    Reason :: term().

Search

search/3

Search with text query (requires embedder).

-spec search(Store, Query, Opts) -> {ok, Results} | {error, Reason} when
    Store :: atom(),
    Query :: binary(),
    Opts :: search_opts(),
    Results :: [search_result()],
    Reason :: embedder_not_configured | term().

search_vector/3

Search with vector query.

-spec search_vector(Store, Vector, Opts) -> {ok, Results} | {error, Reason} when
    Store :: atom(),
    Vector :: [float()],
    Opts :: search_opts(),
    Results :: [search_result()],
    Reason :: term().

Search Options

-type search_opts() :: #{
    k => pos_integer(),           %% Number of results (default: 5)
    filter => filter_fun(),       %% Metadata filter function
    include_text => boolean(),    %% Include text in results (default: true)
    include_metadata => boolean(),%% Include metadata (default: true)
    ef_search => pos_integer()    %% HNSW search width (default: max(k, 50))
}.

-type filter_fun() :: fun((Metadata :: map()) -> boolean()).

-type search_result() :: #{
    key := binary(),
    score := float(),
    text => binary(),
    metadata => map()
}.

Cluster API

start_cluster/0, start_cluster/1

Start clustering.

-spec start_cluster() -> ok | {error, Reason}.
-spec start_cluster(Opts) -> ok | {error, Reason} when
    Opts :: #{
        cluster_name => atom(),
        seed_nodes => [node()]
    }.

cluster_join/1

Join existing cluster.

-spec cluster_join(Nodes) -> ok | {error, Reason} when
    Nodes :: [node()].

cluster_leave/0

Leave cluster gracefully.

-spec cluster_leave() -> ok | {error, Reason}.

cluster_status/0

Get cluster status.

-spec cluster_status() -> Status when
    Status :: #{
        state := atom(),
        nodes := [node()],
        leader := node(),
        is_leader := boolean()
    }.

cluster_nodes/0

Get list of healthy cluster nodes.

-spec cluster_nodes() -> [node()].

is_clustered/0

Check if clustering is enabled.

-spec is_clustered() -> boolean().

Cluster Document Operations

cluster_add/4, cluster_add/5

Add document to cluster (routes to shard).

-spec cluster_add(Collection, Id, Text, Metadata) -> ok | {error, Reason}.
-spec cluster_add(Collection, Id, Text, Metadata, EmbedderInfo) -> ok | {error, Reason}.

cluster_add_vector/5

Add document with vector to cluster.

-spec cluster_add_vector(Collection, Id, Text, Metadata, Vector) -> ok | {error, Reason}.

cluster_get/2

Get document from cluster.

-spec cluster_get(Collection, Id) -> {ok, Doc} | not_found | {error, Reason}.

cluster_delete/2

Delete document from cluster.

-spec cluster_delete(Collection, Id) -> ok | {error, Reason}.

cluster_search/3

Search cluster (scatter-gather).

-spec cluster_search(Collection, Query, Opts) -> {ok, Results} | {error, Reason}.

cluster_search_vector/3

Search cluster with vector.

-spec cluster_search_vector(Collection, Vector, Opts) -> {ok, Results} | {error, Reason}.

Collection Management (Cluster Mode)

create_collection/2

Create a collection.

-spec create_collection(Name, Opts) -> ok | {error, Reason} when
    Name :: binary(),
    Opts :: #{
        dimensions => pos_integer(),
        num_shards => pos_integer(),
        replication_factor => pos_integer()
    }.

delete_collection/1

Delete a collection.

-spec delete_collection(Name) -> ok | {error, Reason} when
    Name :: binary().

list_collections/0

List all collections.

-spec list_collections() -> {ok, Collections} | {error, Reason} when
    Collections :: #{binary() => map()}.

get_collection/1

Get collection metadata.

-spec get_collection(Name) -> {ok, Meta} | {error, not_found} when
    Name :: binary(),
    Meta :: map().

Embedding

barrel_vectordb_embed:init/1

Initialize embedder.

-spec init(Config) -> {ok, State} | {error, Reason} when
    Config :: #{embedder := embedder_config()}.

barrel_vectordb_embed:embed/2

Embed text.

-spec embed(Text, State) -> {ok, Vector} | {error, Reason} when
    Text :: binary(),
    Vector :: [float()].

barrel_vectordb_embed:embed_batch/2

Embed multiple texts.

-spec embed_batch(Texts, State) -> {ok, Vectors} | {error, Reason} when
    Texts :: [binary()],
    Vectors :: [[float()]].

BM25

barrel_vectordb_bm25:new/0

Create BM25 index.

-spec new() -> index().

barrel_vectordb_bm25:add/3

Add document to BM25 index.

-spec add(Index, Id, Text) -> Index when
    Index :: index(),
    Id :: binary(),
    Text :: binary().

barrel_vectordb_bm25:search/3

Search BM25 index.

-spec search(Index, Query, K) -> {ok, Results} when
    Index :: index(),
    Query :: binary(),
    K :: pos_integer(),
    Results :: [{Id :: binary(), Score :: float()}].

Reranking

barrel_vectordb_rerank:init/1

Initialize reranker.

-spec init(Config) -> {ok, Reranker} | {error, Reason} when
    Config :: #{model := binary()}.

barrel_vectordb_rerank:rerank/3

Rerank documents.

-spec rerank(Query, Docs, Reranker) -> {ok, Ranked} | {error, Reason} when
    Query :: binary(),
    Docs :: [binary()],
    Ranked :: [{Index :: non_neg_integer(), Score :: float()}].

barrel_vectordb_rerank:stop/1

Stop reranker.

-spec stop(Reranker) -> ok.