Barrel
FR GitHub

Barrel API

This is the barrel module, the API you use to embed the database in an Erlang application. Every function takes the handle returned by barrel:open/1,2, except the lifecycle calls. Use this page as the map; the guides have worked examples, and the generated reference has every type and option.

{ok, _} = application:ensure_all_started(barrel),
{ok, Db} = barrel:open(<<"notes">>, #{
    vectordb => #{db_path => "/var/lib/app/vec/notes"}}),
{ok, #{<<"rev">> := _}} =
    barrel:put_doc(Db, #{<<"id">> => <<"n1">>,
                         <<"title">> => <<"hello">>}).

Calls return {ok, Value} or {error, Reason}; see Error codes.

Lifecycle

FunctionDescription
open/1, open/2Open a database, creating it if needed. Options: docdb, vectordb (a map, or none for documents only), embedding (a policy, or stored, for record mode), encryption, read_only, store_supervised. See Configuration.
close/1Stop the indexer and the vector store, then close the documents.
info/1The docdb info (configuration, keyspace, retention, history floor, write-group counters) plus embedding, dimensions and embedder. No document count or size.
delete/1Delete the database and its vector store files.

Open from a long-lived process: the vector store is linked to the caller unless you pass store_supervised => true, or open through barrel_dbs. See Embed barrel in an Erlang app.

Documents

FunctionDescription
put_doc/2,3Create or update a document (a map with <<"id">>). Returns {ok, #{<<"id">>, <<"rev">>, <<"ok">>}}. An update must carry the current <<"_rev">>. Options include provenance, expires_at, sync and, in record mode, vector.
put_docs/2,3One result per document, in order. In record mode with mode => sync, one embedding failure fails the whole batch.
get_doc/2,3Read a document. Options: include_embedding, conflicts, include_deleted, rev.
get_docs/2,3Read several documents.
delete_doc/2,3, delete_docs/2Delete (writes a tombstone). delete_docs/2 deletes one by one, not atomically.
find/2,3A structured query (#{where => [...]}), the same spec as barrel_docdb:find/2,3.

Queries (BQL)

FunctionDescription
query/2,3Run a statement; returns {ok, Rows, Meta}. Options: params, chunk_size, continuation, overfetch.
query_fold/5Fold rows without building the full list.
explain_query/2,3The plan and its warnings.
subscribe_query/2,3, unsubscribe_query/1Live queries from a SUBSCRIBE statement. Options: params, owner.

The search table functions vector_top_k, bm25_top_k and hybrid_top_k run only through these calls. See the BQL reference.

Attachments

FunctionDescription
put_attachment/4,5, get_attachment/3Store and read bytes by name.
list_attachments/2, delete_attachment/3, attachment_info/3List, delete, inspect.
open_attachment_writer/4, write_attachment/2, finish_attachment/1, abort_attachment/1Stream a large attachment in.
open_attachment_reader/3, read_attachment/1, close_attachment_reader/1Stream one out.

Byte-range reads exist only in barrel_docdb (open_attachment_stream/4, read_attachment_range/5).

On a database opened with vectordb => none, these return {error, no_vector_store}.

FunctionDescription
vector_add/4,5, vector_add_batch/2Add a vector with its text and metadata; /4 embeds the text, /5 takes the vector. Returns {error, record_mode} in record mode, where you write documents instead.
vector_get/2, vector_delete/2Read or delete one entry.
vector_stats/1count, dimension, index, index_origin, config.
search/3Embed the query text, then vector search. Needs an embedder.
search_vector/3Nearest neighbours of a vector.
search_bm25/3Keyword search; returns {ok, [{Id, Score}]}. Needs a BM25 backend.
search_hybrid/3Keyword and vector, fused (RRF by default). Needs both.

Options: k (5 for search and search_vector, 10 for BM25 and hybrid), filter (a fun on the metadata, applied after retrieval), include_text, include_metadata; for hybrid also bm25_weight, vector_weight, fusion (rrf or linear) and rrf_k.

Embedding

FunctionDescription
embed/2, embed_batch/2Embed text with the database's embedder.
embedder_info/1provider, model, dimensions, distance, preprocessing, fingerprint.
embedding_fingerprint/3The fingerprint that identifies a vector space.

Changes and subscriptions

FunctionDescription
changes/2,3Read the changes feed from first or a cursor.
hlc_encode/1, hlc_decode/1Turn a feed position into a URL-safe cursor and back.
subscribe/2,3, subscribe_ack/2, subscribe_stop/1A changes stream process; subscribe_ack/2 acknowledges a batch in push mode.

Timeline

FunctionDescription
branch/2,3Branch at now, or at a past HLC with at. A plain branch gets an empty vector store; a record-mode branch backfills from stored embeddings.
merge/1,2Merge a branch back into its parent.

See Branch, merge, recover.

History

FunctionDescription
history/1,2, history_floor/1Read the retained change history and its floor. Options: from, to, limit, id.
doc_versions/2, version_body/3List a document's versions and read a past body.

See Audit and provenance.

Other modules you call

ModuleFor
barrel_dbsA shared, supervised handle per name: ensure/1,2 (with must_exist), lease/2, release/1, close/1, list/0. The server opens databases through it.
barrel_rep, barrel_rep_tasksReplication; barrel does not wrap it. Pass the database name. See Synchronization.
barrel_ctx, barrel_ctx_exportContexts, working sets, export and import. See Query several datasets.
barrel_spaces, barrel_caps, barrel_session, barrel_handoffThe agent layer. See Spaces, sessions, handoffs.
barrel_ngramSubstring and regex search over a docdb database. See Substring and regex.

Written for the site Edit this page View as Markdown

Up and down to moveEnter to open