Barrel
EN GitHub

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_rep avec le nom de la base docdb.

Sa place dans Barrel

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

dépendances rebar.config
{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éfautRô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éfautRô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éfautRô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âcheAppelRenvoie
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âcheAppelRenvoie
É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âcheAppelRenvoie
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âcheAppelRenvoie
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.

Shell Erlang
{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">>).
Sortie d’une exécution sur barrel 1.12.0 (abrégée)
{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_path reste dans ./priv/barrel_vectordb_<name> sous le répertoire courant, avec une notice dans le journal. Une sauvegarde du seul data_dir le manque ; les nouveaux magasins vont dans <data_dir>/<name>.vectordb.
  • Le magasin de vecteurs est lié au processus qui l’a ouvert. Utilisez barrel_dbs ou store_supervised => true pour des propriétaires de longue durée.
  • En mode simple, put_doc et vector_add sont 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.
Lacune connue

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.

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