barrel
La base de données intégrable. Une base barrel est à la fois une base de documents et un magasin de vecteurs, sous un même nom et un même espace d’identifiants : un document, ses pièces jointes et son vecteur partagent un identifiant.
Ce qu’elle résout
Les agents et les fonctions de recherche ont besoin de documents, de fichiers et de vecteurs qui restent ensemble. Faire cohabiter une base de documents et un index vectoriel, c’est deux identifiants, deux cycles de vie et des écritures qui divergent. barrel les assemble, et ajoute le mode enregistrement (des embeddings tenus à jour avec les documents), BQL avec des fonctions de table de recherche et des requêtes en direct, la timeline (branche, récupération, fusion), les contextes et l’export.
Quand l’utiliser
- Vous écrivez une application Erlang ou Elixir et voulez documents, pièces jointes et recherche vectorielle dans le même processus.
- Vous voulez des embeddings calculés à partir des champs des documents et tenus à jour à chaque écriture (mode enregistrement).
- Vous voulez créer une branche d’une base pour une exécution d’agent, relire le résultat, puis la fusionner.
Quand ne pas l’utiliser
- Vous avez besoin de clients sur le réseau : lancez barrel_server par-dessus.
- Vous n’avez besoin que de documents et de synchronisation, sans vecteurs : barrel_docdb suffit.
- Vous avez besoin de la réplication par cette façade : elle n’y est pas encore exposée ; appelez
barrel_repavec le nom de la base docdb.
Sa place dans Barrel
- Repose sur
barrel_docdb,barrel_vectordb,barrel_embed,barrel_crypto- Utilisée par
barrel_spaces,barrel_server- Autres dépendances
- hackney (client des contextes distants) ; OTP 26 ou plus récent
- Seule
- Oui, comme bibliothèque. Elle ne sert aucun protocole réseau par elle-même.
Installation
{barrel, "~> 1.14"} Le mode enregistrement demande que l’application barrel soit démarrée ; sinon l’ouverture avec une politique renvoie {error, barrel_app_not_started}.
Configuration
Options de barrel:open/2
| Clé | Défaut | Rôle |
|---|---|---|
docdb | #{} | Options transmises à barrel_docdb:create_db/2 |
vectordb | un magasin de vecteurs | Table de configuration du magasin, ou none pour des documents seuls |
vectordb.db_path | <data_dir>/<name>.vectordb | À côté des documents. Un magasin créé avant la 1.13.0 dans ./priv/barrel_vectordb_<name> y reste. |
embedding | none | Table de politique du mode enregistrement, ou stored pour réutiliser celle enregistrée |
encryption | désactivé | default ou #{provider => Mod} |
read_only | false | Les écritures renvoient {error, read_only} |
store_supervised | false | Par défaut, le magasin de vecteurs est lié à l’appelant |
Politique du mode enregistrement
| Clé | Défaut | Rôle |
|---|---|---|
fields | tous | Chemins dont le texte est transformé en embedding |
mode | async | sync calcule l’embedding avant que l’écriture ne rende la main |
dimensions | 768 | Taille du vecteur |
embedder | none | Une configuration de fournisseur barrel_embed |
metadata_fields | le document sans l’id ni les clés _ | Champs copiés dans les métadonnées du vecteur |
Environnement de l’application (barrel)
| Clé | Défaut | Rôle |
|---|---|---|
dbs_idle_timeout | 300000 ms | barrel_dbs ferme les bases inactives ; 0 désactive |
dbs_max_open | 0 | Nombre maximal de bases ouvertes ; 0 pour illimité |
ctx_max_contexts | 8 | Contextes par requête fédérée |
ctx_deadline_ms | 5000 | Délai d’une requête de contexte (60000 au plus) |
Seulement les clés les plus utilisées. Pour toutes les options, voyez la référence de configuration et la référence de l’API.
L’API par tâche
Ouvrir et gérer
| Tâche | Appel | Renvoie |
|---|---|---|
| Ouvrir ou créer | barrel:open/1,2 | {ok, Db} |
| Fermer, supprimer | barrel:close/1, delete/1 | ok |
| Décrire | barrel:info/1 | les infos docdb, plus embedding, dimensions, embedder |
| Cycle de vie géré | barrel_dbs:ensure/1,2, lease/2, release/1 | {ok, Db}, {ok, Db, LeaseRef} |
Documents et fichiers
| Tâche | Appel | Renvoie |
|---|---|---|
| Écrire | barrel:put_doc/2,3, put_docs/2,3 | {ok, #{<<"id">>, <<"rev">>, <<"ok">>}} |
| Lire | barrel:get_doc/2,3, get_docs/2,3 | {ok, Doc} |
| Supprimer | barrel:delete_doc/2,3 | {ok, _} |
| Chercher | barrel:find/2,3 | {ok, Rows, Meta} |
| Joindre un fichier | barrel:put_attachment/4,5, get_attachment/3 | {ok, Info}, {ok, Bytes} |
Recherche et requêtes
| Tâche | Appel | Renvoie |
|---|---|---|
| Ajouter un vecteur | barrel:vector_add/4,5, vector_add_batch/2 | ok, {ok, #{inserted}} |
| Recherche sémantique | barrel:search/3, search_vector/3 | {ok, [#{key, score, text, metadata}]} |
| Mots-clés, hybride | barrel:search_bm25/3, search_hybrid/3 | {ok, [{Id, Score}]}, {ok, [Hit]} |
| BQL | barrel:query/2,3, explain_query/2,3 | {ok, Rows, Meta} |
| Requête en direct | barrel:subscribe_query/2,3, unsubscribe_query/1 | {ok, #{pid, ref}}, puis des messages bql_rows, bql_ready, bql_change |
Timeline et historique
| Tâche | Appel | Renvoie |
|---|---|---|
| Créer une branche | barrel:branch/2,3 | {ok, BranchDb} |
| Fusionner | barrel:merge/1,2 | {ok, Report} |
| Changements | barrel:changes/2,3, subscribe/2,3 | liste des changements, ou un pid de flux |
| Versions | barrel:doc_versions/2, version_body/3 | {ok, [Version]}, {ok, Body} |
Documents, vecteurs, BM25 et BQL dans une même base
D’après une exécution vérifiée. kb_embed est un fournisseur de démonstration en 64 dimensions écrit pour l’exécution (hachage de caractéristiques : il rapproche les mots communs, il n’est pas sémantique). N’importe quel fournisseur barrel_embed peut le remplacer.
{ok, _} = application:ensure_all_started(barrel).
{ok, Db} = barrel:open(<<"research">>, #{vectordb => #{
db_path => filename:join(VecDir, "research"),
dimensions => 64,
embedder => {kb_embed, #{}},
bm25_backend => memory}}).
Notes = [
{<<"paper:raft">>, <<"Raft consensus: leader election "
"and log replication for replicated state machines">>,
#{<<"topic">> => <<"distributed-systems">>,
<<"year">> => 2014}},
{<<"paper:crdt">>, <<"Conflict-free replicated data "
"types converge without coordination">>,
#{<<"topic">> => <<"distributed-systems">>,
<<"year">> => 2011}},
{<<"paper:hnsw">>, <<"HNSW: hierarchical navigable small "
"world graphs for approximate nearest neighbor "
"search">>,
#{<<"topic">> => <<"vector-search">>,
<<"year">> => 2016}},
{<<"paper:bm25">>, <<"Okapi BM25 ranking function for "
"keyword search over documents">>,
#{<<"topic">> => <<"information-retrieval">>,
<<"year">> => 1994}}].
[{ok, _} = barrel:put_doc(Db,
M#{<<"id">> => Id, <<"abstract">> => T})
|| {Id, T, M} <- Notes].
barrel:vector_add_batch(Db, Notes).
barrel:search(Db, <<"leader election in replicated logs">>,
#{k => 2}).
barrel:search_bm25(Db, <<"keyword search">>, #{k => 2}).
barrel:query(Db, <<"SELECT v.id, v._score, v._distance, "
"abstract FROM vector_top_k("
"'replicated state machines', k => 2) AS v">>). {ok,#{inserted => 4}}
{ok,[#{metadata => #{<<"topic">> => <<"distributed-systems">>,
<<"year">> => 2014},
text => <<"Raft consensus: ...">>,
key => <<"paper:raft">>,score => 0.5257737534501699},
#{metadata => #{<<"topic">> => <<"distributed-systems">>,
<<"year">> => 2011},
text => <<"Conflict-free replicated data types ...">>,
key => <<"paper:crdt">>,score => 0.14173227881546058}]}
{ok,[{<<"paper:bm25">>,1.9587592623731485},
{<<"paper:hnsw">>,0.6586049622596158}]}
{ok,[#{<<"_distance">> => 0.5158329928408527,
<<"_score">> => 0.4841670071591473,
<<"abstract">> => <<"Raft consensus: ...">>,
<<"id">> => <<"paper:raft">>},
#{<<"_distance">> => 0.7817821172596275,
<<"_score">> => 0.21821788274037246,
<<"abstract">> => <<"Conflict-free replicated ...">>,
<<"id">> => <<"paper:crdt">>}],
#{count => 2, has_more => false, ...}} Limites à connaître
- Un magasin de vecteurs créé avant barrel 1.13.0 sans
db_pathreste dans./priv/barrel_vectordb_<name>sous le répertoire courant, avec une notice dans le journal. Une sauvegarde du seuldata_dirle manque ; les nouveaux magasins vont dans<data_dir>/<name>.vectordb. - Le magasin de vecteurs est lié au processus qui l’a ouvert. Utilisez
barrel_dbsoustore_supervised => truepour des propriétaires de longue durée. - En mode simple,
put_docetvector_addsont deux écritures séparées. Le mode enregistrement est la voie atomique. - Changer la politique du mode enregistrement à la réouverture écrit un avertissement dans les logs et ne réindexe pas les documents existants.
- Les branches simples n’emportent pas de vecteurs. Une branche d’une branche est refusée (
cannot_branch_a_branch). - L’export demande un magasin de vecteurs (sinon
{error, no_vector_store}) et ferme la base pendant la copie. - Les requêtes de contexte demandent
LIMIT; OFFSET, UNNEST, SUBSCRIBE et la continuation sont refusés.
Dans find/2, order_by sur un chemin est ignoré si le chemin n’est pas sélectionné ou lié à une variable. ORDER BY en BQL trie correctement.