Trouvez par le sens, par le mot, ou par la chaîne exacte.
Barrel garde un document et son vecteur sous un même identifiant : une seule requête peut classer par le sens, par mots-clés, ou les deux, et renvoyer des lignes avec les champs du document. Pour les identifiants et les messages d’erreur que le sens manque, un index de trigrammes trouve le texte exact.
La recherche s’exécute là où tourne la base : dans votre nœud Erlang, derrière le serveur REST et MCP, ou sur des vecteurs synchronisés dans un navigateur.
Vectorielle, par mots-clés et hybrideSous-chaîne et expression régulière
Six façons de trouver un enregistrement
Chacune est un index ou une étape distincte que vous activez. La marque indique si elle fonctionne sans installation.
-
Vectorielle
Les plus proches voisins par le sens. HNSW par défaut, DiskANN, ou FAISS via
barrel_faiss. Les requêtes en texte demandent un embedder ; vous pouvez aussi passer vous-même le vecteur de la requête. -
Par mots-clés (BM25)
Recherche par mots-clés classée. Désactivée sur une base simple tant que vous ne fixez pas
bm25_backendàmemoryoudisk; le mode enregistrement l’active avecdisk. -
Hybride
Vecteurs et BM25 fusionnés en un seul classement : fusion par rang réciproque par défaut (
rrf_k60), ou un mélange linéaire avecbm25_weightetvector_weight. Demande que BM25 soit activé. -
Sous-chaîne et expression régulière
Chaînes exactes et motifs PCRE sur les documents avec
barrel_ngram, un index de trigrammes alimenté par le flux des changements. Chaque résultat est confirmé sur le texte et porte ses plages d’octets. -
Reclassement
Une seconde passe avec un cross-encoder dans
barrel_rerank: vous lui donnez la requête et les textes de vos meilleurs résultats, il les renvoie réordonnés, chacun avec un score. -
Fonctions de table BQL
vector_top_k,bm25_top_kethybrid_top_kcomme FROM d’une requête : les résultats sont joints à leurs documents, puis WHERE, ORDER BY et les projections s’appliquent.
Comment s’exécute une requête hybride
Les deux index répondent au même texte ; leurs rangs sont fusionnés, et une fonction de table BQL joint chaque résultat à son document avant que WHERE ne s’applique. Les fonctions de table récupèrent 3 fois k (1000 au plus) pour qu’un WHERE ait encore des lignes à garder.
- Texte de la requête ou un vecteur de requête
embedding par le fournisseur du magasin
- Index vectoriel HNSW, DiskANN ou FAISSIndex BM25 mémoire ou disque
fusion des rangs (RRF, k 60)
- Résultats hybrides id, score, texte, métadonnées
BQL : jointure aux documents, puis WHERE
- Lignes champs, _score
Comment s’exécute la recherche par sous-chaîne et par expression régulière
- barrel_docdb documents
flux des changements
- Segments de trigrammes immuables, avec somme de contrôle
candidats tirés des listes
- Confirmation sur le texte écarte les faux positifs
résultats
- id et plages décalage en octets, longueur
Ce qui tient, et ce qui le teste
Des propriétés sur lesquelles vous pouvez compter, avec le test du dépôt qui vérifie chacune.
Exact veut dire exact
La recherche par sous-chaîne et par expression régulière confirme chaque candidat sur le texte stocké : les collisions de trigrammes n’apparaissent jamais comme résultats.
Vérifié par oracle_equivalence dans barrel_ngram_SUITE, qui compare chaque réponse à un parcours exhaustif.
Le vecteur suit le document
En mode enregistrement, une modification recalcule l’embedding, une suppression retire le vecteur, et le marqueur destiné à l’indexeur est écrit dans le même lot que le document.
Vérifié par barrel_record_SUITE : indexer_update_reembeds, indexer_delete_removes_vector, indexer_crash_restart.
Lire votre écriture, quand vous le demandez
Le mode enregistrement avec mode => sync calcule l’embedding avant que l’écriture ne rende la main. Si l’embedder échoue, l’écriture échoue et rien n’est stocké.
Vérifié par barrel_record_SUITE : sync_put_immediate_search, sync_embed_failure_fails_put.
Un index BM25 sur disque survit à un kill
Les écritures acquittées sont toujours dans l’index après que le processus a été tué et le magasin rouvert. Un index en mémoire se reconstruit à l’ouverture à partir du texte stocké.
Vérifié par barrel_vectordb_bm25_persistence_tests (disk: kill then reopen loses no acked write).
Les documents répliqués sont indexés
Les documents arrivés par réplication reçoivent leur embedding sur la copie qui les reçoit ; la version qui a perdu un conflit, non.
Vérifié par barrel_record_SUITE : replicated_docs_embedded, replicated_loser_not_reembedded.
Le même modèle, ou pas d’ouverture
Chaque magasin enregistre l’empreinte de son embedder : fournisseur, modèle, dimensions, distance. Un espace en mode enregistrement ouvert avec un autre modèle est refusé.
Vérifié par embedder_fingerprint dans barrel_record_SUITE.
L’utiliser
Ouvrir une base avec un magasin de vecteurs et BM25
L’exécution enregistrée ci-dessous utilisait kb_embed, un fournisseur à hachage de caractéristiques en 64 dimensions écrit pour le test : il rapproche les mots communs, il n’est pas sémantique.
{ok, Db} = barrel:open(<<"research">>, #{vectordb => #{
db_path => "data/research_vec",
dimensions => 64,
embedder => {kb_embed, #{}},
bm25_backend => memory}}),
{ok, #{inserted := 4}} = barrel:vector_add_batch(Db, Notes). Vectorielle, par mots-clés et hybride
barrel:search(Db, <<"leader election">>, #{k => 2}),
barrel:search_bm25(Db, <<"keyword search">>, #{k => 2}),
barrel:search_hybrid(Db, <<"nearest neighbor search">>,
#{k => 2}). curl -X POST localhost:8080/db/research/search/bm25 \
-H 'content-type: application/json' \
-d '{"query":"keyword search","k":2}'
curl -X POST localhost:8080/db/research/search/hybrid \
-H 'content-type: application/json' \
-d '{"query":"nearest neighbor search","k":2}' {"jsonrpc":"2.0","id":3,"method":"tools/call",
"params":{"name":"search","arguments":{
"db":"research","mode":"hybrid",
"query":"nearest neighbor search","k":2}}} {ok,[{<<"paper:bm25">>,1.9587592623731485},
{<<"paper:hnsw">>,0.6586049622596158}]} Chercher dans une requête
_score vaut 1 moins la distance pour les vecteurs, le score BM25 brut, ou la valeur fusionnée pour l’hybride. Il peut être sélectionné et trié, pas filtré.
barrel:query(Db,
<<"SELECT h.id, h._score, topic "
"FROM hybrid_top_k($q, k => 3) AS h "
"ORDER BY h._score DESC">>,
#{params => #{<<"q">> => <<"replicated consensus">>}}). curl -X POST localhost:8080/db/research/query \
-H 'content-type: text/plain' \
--data-binary "SELECT b.id, b._score
FROM bm25_top_k('search', k => 3) AS b
WHERE b.year > 2000" {"jsonrpc":"2.0","id":4,"method":"tools/call",
"params":{"name":"query","arguments":{
"db":"research",
"query":"SELECT v.id FROM vector_top_k($q) AS v",
"params":{"q":"consensus"}}}} {ok,[#{<<"_score">> => 0.01639344262295082,
<<"id">> => <<"paper:raft">>,
<<"topic">> => <<"distributed-systems">>},
#{<<"_score">> => 0.016001024065540194,
<<"id">> => <<"paper:crdt">>, ...},
#{<<"_score">> => 0.008536214242239805,
<<"id">> => <<"paper:bm25">>, ...}], ...} Mode enregistrement : la politique calcule les embeddings pour vous
Nommez les champs à transformer en embeddings. Avec mode => sync, l’écriture rend la main une fois le vecteur indexé ; le défaut, async, indexe en arrière-plan et se rétablit après une panne.
Embedder = {ollama, #{model => <<"nomic-embed-text">>}},
Policy = #{fields => [<<"title">>, <<"body">>],
mode => sync, embedder => Embedder,
dimensions => 768},
{ok, Db} = barrel:open(<<"notes">>, #{embedding => Policy,
vectordb => #{db_path => "data/notes_vec"}}),
{ok, _} = barrel:put_doc(Db, #{<<"id">> => <<"n1">>,
<<"title">> => <<"Raft">>,
<<"body">> => <<"Leader election and log replication">>}),
barrel:search(Db, <<"how do replicas agree?">>, #{k => 1}). Sous-chaînes exactes et expressions régulières
L’outil MCP ouvre l’index de la base à la première utilisation et le rafraîchit avant chaque recherche. Il n’y a pas de route REST.
ok = barrel_ngram:open(<<"rb_idx">>, #{db => <<"runbooks">>,
fields => [<<"title">>, <<"body">>]}),
barrel_ngram:search(<<"rb_idx">>, <<"ERR_CONN_TIMEOUT">>),
barrel_ngram:search(<<"rb_idx">>, <<"redis">>,
#{case_sensitive => false}),
barrel_ngram:regex(<<"rb_idx">>,
<<"pg-(primary|replica)-\\d+">>). {"jsonrpc":"2.0","id":5,"method":"tools/call",
"params":{"name":"ngram_search","arguments":{
"db":"runbooks","mode":"regex",
"query":"pg-(primary|replica)-\\d+"}}} {ok,[#{id => <<"rb:db">>,spans => [{11,16}]}]}
{ok,[#{id => <<"rb:cache">>,spans => [{68,5}]}]}
{ok,[#{id => <<"rb:db">>,spans => [{35,13},{58,13}]}]} Reclasser les meilleurs résultats optionnel
Ranker est un serveur barrel_rerank:start_link(#) (modèle par défaut cross-encoder/ms-marco-MiniLM-L-6-v2).
{ok, Hits} = barrel:search(Db, Q, #{k => 20}),
Texts = [maps:get(text, H) || H <- Hits],
{ok, R} = barrel_rerank:rerank(Ranker, Q, Texts,
#{top_k => 5}),
%% R vaut [{Index, Score}], le meilleur d’abord ; Index part de 0
Top = [lists:nth(I + 1, Hits) || {I, _Score} <- R]. {ok,[{0,9.581769943237305},
{2,-5.255744457244873},
{1,-9.625640869140625}]} Valeurs par défaut selon le point d’entrée
| Point d’entrée | Résultats si vous ne passez rien |
|---|---|
barrel:search/3, search_vector/3 | k 5 |
barrel:search_bm25/3, search_hybrid/3 | k 10 |
BQL vector_top_k, bm25_top_k, hybrid_top_k | k 10 |
REST /db/:db/search/* et l’outil MCP search | k 10 (REST le plafonne à 10000) |
MCP ngram_search | limit 50 (plafond 1000) |
Limites
- BM25 est désactivé sur une base simple, y compris les bases qu’ouvre un barrel_server par défaut (un magasin cosinus de 768 dimensions, BM25 désactivé). BM25 et l’hybride répondent alors
bm25_not_enabledouembedder_not_configured, en REST sous forme d’une erreur 500. - Il n’y a pas d’embedder hors ligne intégré. Apportez vos propres vecteurs, lancez Ollama en local, utilisez le fournisseur Python local, ou écrivez un module fournisseur.
- Le filtre de métadonnées (
filter => fun) s’applique après l’étape des plus proches voisins : un filtre strict peut renvoyer moins dekrésultats. - La recherche par sous-chaîne et par expression régulière n’est ni dans l’API
barrelni dans BQL : appelezbarrel_ngramou l’outil MCPngram_search. L’index occupe environ 34 fois la taille du texte, et ses champs sont fixés à sa création. - Le reclassement demande Python 3 avec transformers et torch, et télécharge son modèle à la première utilisation. Les scores sont les logits bruts du cross-encoder, pas des valeurs entre 0 et 1.
- En mode simple, le document et son vecteur sont deux écritures que rien ne lie ; le mode enregistrement est la voie qui les garde ensemble.
- Dans le navigateur, barrel-lite classe localement les vecteurs synchronisés par un cosinus exhaustif ; les requêtes par mots-clés et hybrides vont au serveur.