Embarquer barrel dans une application Erlang
barrel est la base de données edge embarquable. Elle compose la couche
documents (barrel_docdb) et la couche vecteurs (barrel_vectordb) derrière
une seule API, où un document, ses pièces jointes (blobs) et son vecteur
partagent un même identifiant. Lisez ce guide quand vous voulez une base de
données dans votre release Erlang sans faire tourner de serveur.
Quand l’utiliser
- Vous voulez des documents, des vecteurs, la recherche BM25/hybride, des pièces jointes et un flux de changements depuis un seul handle, dans le même processus.
- Vous n’avez pas besoin de point d’accès réseau. Pour un accès HTTP, lancez
plutôt
barrel_server.
Ouvrir et fermer
{ok, _} = application:ensure_all_started(barrel_docdb),
{ok, _} = application:ensure_all_started(barrel_vectordb),
{ok, Db} = barrel:open(mydb),
%% options par couche :
{ok, Db2} = barrel:open(mydb, #{
vectordb => #{dimension => 768, bm25_backend => memory}
}),
ok = barrel:close(Db).
Une base lie son stockage vectoriel au processus qui l’a ouverte. Ouvrez-la depuis un processus de longue durée (un gen_server ou un superviseur), pas depuis un processus éphémère.
Ouvrir sans stockage vectoriel
Une base qui ne contient que des documents n’a besoin ni du stockage
vectoriel ni de son RocksDB. Passez vectordb => none :
{ok, Db} = barrel:open(notes, #{vectordb => none}),
{ok, _} = barrel:put_doc(Db, #{<<"id">> => <<"a">>, <<"lang">> => <<"en">>}),
{ok, _Rows, _Meta} = barrel:query(Db, "SELECT * FROM db WHERE lang = 'en'"),
{error, no_vector_store} = barrel:search(Db, <<"anything">>, #{}).
- Les documents, pièces jointes, requêtes, changements et la réplication fonctionnent comme d’habitude.
- Les appels vectoriels (
vector_*,search*,embed*,embedder_info/1,vector_stats/1) et les fonctions de tablevector_top_k,bm25_top_kethybrid_top_krépondent{error, no_vector_store}. - Le mode enregistrement demande un stockage vectoriel :
embeddingavecvectordb => nonerépond{error, {invalid_option, vectordb}}. - Une branche d’une telle base n’a pas non plus de stockage vectoriel. Un
export de contexte la refuse (
{error, no_vector_store}) ; une tranche de cette base ne contient que des documents. barrel_spaces:create_space(#{vectordb => none})crée un espace sans stockage vectoriel ; l’espace se rouvre sans lui sur chaque nœud.
Ouvrir en lecture seule
Ouvrez avec read_only => true pour servir une base sans écrire aucun
fichier, par exemple une copie importée que plusieurs nœuds partagent. Chaque
écriture répond {error, read_only}.
{ok, Ro} = barrel:open(mydb, #{read_only => true}),
{error, read_only} = barrel:put_doc(Ro, #{<<"id">> => <<"z">>}),
{ok, _} = barrel:get_doc(Ro, <<"a">>),
ok = barrel:close(Ro).
- La base doit exister : une base absente échoue avec
read_only_store_missing. Une base écrite par une version plus ancienne qui demande une mise à niveau échoue avecread_only_upgrade_needed; ouvrez-la une fois en écriture. - Le mode enregistrement ne persiste aucune politique et ne démarre aucun
indexeur. Passez
embedding => storedpour utiliser la politique que la base a persistée ({error, no_stored_policy}sur une base simple).
Partager des handles via barrel_dbs
barrel_dbs met en cache les handles ouverts par nom, ferme ceux qui sont
inactifs et évince au-delà d’un plafond. Prenez un bail (lease) quand un
processus a besoin qu’une base reste ouverte pendant qu’il travaille ; prenez
une retenue (hold) quand vous avez besoin que ses fichiers soient fermés
(c’est le cas d’un export).
{error, not_found} = barrel_dbs:ensure(<<"nope">>, #{must_exist => true}),
{ok, Db, Lease} = barrel_dbs:lease(<<"mydb">>, #{}),
%% ... Db reste ouverte malgré la fermeture sur inactivité et l'éviction ...
ok = barrel_dbs:release(Lease),
{ok, #{was_open := _}} = barrel_dbs:hold(<<"mydb">>, #{}),
%% ... chaque ensure de mydb est refusé jusqu'à unhold ...
ok = barrel_dbs:unhold(<<"mydb">>).
- Les baux sont comptés et prennent fin quand leur détenteur s’arrête ;
barrel_dbs:leases/0les liste.lookup/1renvoie l’indicateur d’épinglage, le propriétaire et les options d’ouverture. - Une retenue est refusée sur une base épinglée ou sous bail, ou sur une base ouverte en dehors du gestionnaire.
Documents
{ok, _} = barrel:put_doc(Db, #{<<"id">> => <<"a">>, <<"title">> => <<"hello">>}),
{ok, Doc} = barrel:get_doc(Db, <<"a">>),
{ok, _} = barrel:delete_doc(Db, <<"a">>),
{ok, Rows, _Meta} = barrel:find(Db, #{where => [{path, [<<"title">>], <<"hello">>}]}).
Lots
[{ok, _}, {ok, _}] = barrel:put_docs(Db, [#{<<"id">> => <<"a">>}, #{<<"id">> => <<"b">>}]),
Results = barrel:get_docs(Db, [<<"a">>, <<"b">>]), %% un résultat par id, dans l'ordre
_ = barrel:delete_docs(Db, [<<"a">>, <<"b">>]).
Pièces jointes (blobs)
Les blobs sont des pièces jointes de documents ; le backend de stockage est
enfichable par base via la jonction docdb barrel_att_backend (RocksDB
BlobDB par défaut ; barrel_att_s3 les stocke dans un bucket compatible S3).
{ok, _} = barrel:put_attachment(Db, <<"a">>, <<"f.txt">>, <<"bytes">>),
{ok, <<"bytes">>} = barrel:get_attachment(Db, <<"a">>, <<"f.txt">>),
[<<"f.txt">>] = barrel:list_attachments(Db, <<"a">>),
ok = barrel:delete_attachment(Db, <<"a">>, <<"f.txt">>).
Transférer de gros blobs en streaming :
{ok, W0} = barrel:open_attachment_writer(Db, <<"a">>, <<"big">>, <<"application/octet-stream">>),
{ok, W1} = barrel:write_attachment(W0, <<"chunk">>),
{ok, _} = barrel:finish_attachment(W1),
{ok, R0} = barrel:open_attachment_reader(Db, <<"a">>, <<"big">>),
{ok, _Chunk, R1} = barrel:read_attachment(R0), %% eof à la fin
ok = barrel:close_attachment_reader(R1).
Vecteurs et recherche
Pour garder automatiquement les vecteurs synchronisés avec les documents, ouvrez la base avec une politique d’embedding au lieu de les gérer à la main : voir le mode enregistrement. L’API vectorielle directe ci-dessous s’applique aux bases simples.
ok = barrel:vector_add(Db, <<"a">>, <<"hello world">>, #{}, Vector),
{ok, #{inserted := 2}} = barrel:vector_add_batch(Db, [
{<<"a">>, <<"t1">>, #{}, V1},
{<<"b">>, <<"t2">>, #{}, V2}
]),
{ok, Hits} = barrel:search_vector(Db, Vector, #{k => 5}),
{ok, BHits} = barrel:search_bm25(Db, <<"hello">>, #{k => 5}).
Notes :
vector_add_batch/2prend des tuples{Id, Text, Metadata}(texte embeddé par le stockage) ou{Id, Text, Metadata, Vector}(explicite) ; un lot doit être entièrement d’une seule forme.- BM25 est à activer : ouvrez avec
vectordb => #{bm25_backend => memory}(oudisk). Un index disque survit à une réouverture ; un index mémoire est reconstruit à l’ouverture à partir du texte stocké. search_hybrid/3et les ajouts avec embedding automatique demandent un embedder configuré viabarrel_embed; sans lui, ils renvoient{error, embedder_not_configured}.- Pour embedder vous-même du texte avec l’embedder de la base (même modèle et
même dimension que les vecteurs indexés), utilisez
barrel:embed/2,barrel:embed_batch/2etbarrel:embedder_info/1sur le handle ; traitez le handle comme opaque plutôt que de lire ses champs.
Changements
{ok, Changes, Last} = barrel:changes(Db, first),
Cursor = barrel:hlc_encode(Last), %% curseur sûr pour JSON/URL
Last2 = barrel:hlc_decode(Cursor),
{ok, More, _} = barrel:changes(Db, Last2), %% changements depuis le curseur
{ok, Pid} = barrel:subscribe(Db, Last).