Barrel
EN GitHub

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 table vector_top_k, bm25_top_k et hybrid_top_k répondent {error, no_vector_store}.
  • Le mode enregistrement demande un stockage vectoriel : embedding avec vectordb => none ré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 avec read_only_upgrade_needed ; ouvrez-la une fois en écriture.
  • Le mode enregistrement ne persiste aucune politique et ne démarre aucun indexeur. Passez embedding => stored pour 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/0 les liste. lookup/1 renvoie 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/2 prend 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} (ou disk). Un index disque survit à une réouverture ; un index mémoire est reconstruit à l’ouverture à partir du texte stocké.
  • search_hybrid/3 et les ajouts avec embedding automatique demandent un embedder configuré via barrel_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/2 et barrel:embedder_info/1 sur 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).

Traduit de la page anglaise: /docs/guides/embedding/ (docs/guides/embedding.md) Modifier cette page Voir en Markdown

Haut et bas pour se déplacerEntrée pour ouvrir