Barrel
EN GitHub

API Barrel

Voici le module barrel, l’API que vous utilisez pour intégrer la base dans une application Erlang. Chaque fonction prend le handle renvoyé par barrel:open/1,2, sauf les appels de cycle de vie. Servez-vous de cette page comme d’une carte ; les guides ont des exemples complets, et la référence générée détaille chaque type et chaque option.

{ok, _} = application:ensure_all_started(barrel),
{ok, Db} = barrel:open(<<"notes">>, #{
    vectordb => #{db_path => "/var/lib/app/vec/notes"}}),
{ok, #{<<"rev">> := _}} =
    barrel:put_doc(Db, #{<<"id">> => <<"n1">>,
                         <<"title">> => <<"hello">>}).

Les appels renvoient {ok, Value} ou {error, Reason} ; voir Codes d’erreur.

Cycle de vie

FonctionDescription
open/1, open/2Ouvre une base, en la créant si besoin. Options : docdb, vectordb (une map, ou none pour les documents seuls), embedding (une politique, ou stored, pour le mode enregistrement), encryption, read_only, store_supervised. Voir Configuration.
close/1Arrête l’indexeur et le magasin de vecteurs, puis ferme les documents.
info/1Les infos docdb (configuration, espace de clés, rétention, plancher d’historique, compteurs de groupes d’écriture) plus embedding, dimensions et embedder. Ni nombre de documents ni taille.
delete/1Supprime la base et les fichiers de son magasin de vecteurs.

Ouvrez depuis un processus de longue durée : le magasin de vecteurs est lié à l’appelant, sauf si vous passez store_supervised => true ou ouvrez via barrel_dbs. Voir Intégrer barrel dans une application Erlang.

Documents

FonctionDescription
put_doc/2,3Crée ou met à jour un document (une map avec <<"id">>). Renvoie {ok, #{<<"id">>, <<"rev">>, <<"ok">>}}. Une mise à jour doit porter le <<"_rev">> courant. Les options comprennent provenance, expires_at, sync et, en mode enregistrement, vector.
put_docs/2,3Un résultat par document, dans l’ordre. En mode enregistrement avec mode => sync, un échec d’embedding fait échouer tout le lot.
get_doc/2,3Lit un document. Options : include_embedding, conflicts, include_deleted, rev.
get_docs/2,3Lit plusieurs documents.
delete_doc/2,3, delete_docs/2Supprime (écrit une pierre tombale). delete_docs/2 supprime un par un, pas de façon atomique.
find/2,3Une requête structurée (#{where => [...]}), la même spécification que barrel_docdb:find/2,3.

Requêtes (BQL)

FonctionDescription
query/2,3Exécute une instruction ; renvoie {ok, Rows, Meta}. Options : params, chunk_size, continuation, overfetch.
query_fold/5Replie les lignes sans construire la liste complète.
explain_query/2,3Le plan et ses avertissements.
subscribe_query/2,3, unsubscribe_query/1Requêtes en direct depuis une instruction SUBSCRIBE. Options : params, owner.

Les fonctions de table de recherche vector_top_k, bm25_top_k et hybrid_top_k ne s’exécutent que via ces appels. Voir la référence BQL.

Pièces jointes

FonctionDescription
put_attachment/4,5, get_attachment/3Stocke et lit des octets par nom.
list_attachments/2, delete_attachment/3, attachment_info/3Lister, supprimer, inspecter.
open_attachment_writer/4, write_attachment/2, finish_attachment/1, abort_attachment/1Envoyer une grande pièce jointe en flux.
open_attachment_reader/3, read_attachment/1, close_attachment_reader/1En lire une en flux.

Les lectures par plage d’octets n’existent que dans barrel_docdb (open_attachment_stream/4, read_attachment_range/5).

Vecteurs et recherche

Sur une base ouverte avec vectordb => none, ces appels renvoient {error, no_vector_store}.

FonctionDescription
vector_add/4,5, vector_add_batch/2Ajoute un vecteur avec son texte et ses métadonnées ; /4 calcule l’embedding du texte, /5 prend le vecteur. Renvoie {error, record_mode} en mode enregistrement, où vous écrivez des documents à la place.
vector_get/2, vector_delete/2Lit ou supprime une entrée.
vector_stats/1count, dimension, index, index_origin, config.
search/3Calcule l’embedding du texte de la requête, puis fait une recherche vectorielle. Demande un embedder.
search_vector/3Plus proches voisins d’un vecteur.
search_bm25/3Recherche par mots-clés ; renvoie {ok, [{Id, Score}]}. Demande un backend BM25.
search_hybrid/3Mots-clés et vecteurs, fusionnés (RRF par défaut). Demande les deux.

Options : k (5 pour search et search_vector, 10 pour BM25 et hybride), filter (une fun sur les métadonnées, appliquée après la récupération), include_text, include_metadata ; pour l’hybride aussi bm25_weight, vector_weight, fusion (rrf ou linear) et rrf_k.

Embedding

FonctionDescription
embed/2, embed_batch/2Calcule l’embedding d’un texte avec l’embedder de la base.
embedder_info/1provider, model, dimensions, distance, preprocessing, fingerprint.
embedding_fingerprint/3L’empreinte qui identifie un espace vectoriel.

Changements et abonnements

FonctionDescription
changes/2,3Lit le flux de changements depuis first ou un curseur.
hlc_encode/1, hlc_decode/1Transforme une position du flux en curseur sûr pour une URL, et inversement.
subscribe/2,3, subscribe_ack/2, subscribe_stop/1Un processus de flux de changements ; subscribe_ack/2 acquitte un lot en mode push.

Timeline

FonctionDescription
branch/2,3Crée une branche maintenant, ou à un HLC passé avec at. Une branche simple reçoit un magasin de vecteurs vide ; une branche en mode enregistrement le remplit à partir des embeddings stockés.
merge/1,2Fusionne une branche dans son parent.

Voir Brancher, fusionner, restaurer.

Historique

FonctionDescription
history/1,2, history_floor/1Lit l’historique des changements conservé et son plancher. Options : from, to, limit, id.
doc_versions/2, version_body/3Liste les versions d’un document et lit un corps passé.

Voir Audit et provenance.

Autres modules que vous appelez

ModulePour
barrel_dbsUn handle partagé et supervisé par nom : ensure/1,2 (avec must_exist), lease/2, release/1, close/1, list/0. Le serveur ouvre les bases par ce module.
barrel_rep, barrel_rep_tasksLa réplication ; barrel ne l’enveloppe pas. Passez le nom de la base. Voir Synchronisation.
barrel_ctx, barrel_ctx_exportContextes, ensembles de travail, export et import. Voir Interroger plusieurs jeux de données.
barrel_spaces, barrel_caps, barrel_session, barrel_handoffLa couche agents. Voir Espaces, sessions, passations.
barrel_ngramRecherche par sous-chaîne et expression régulière sur une base docdb. Voir Sous-chaîne et expression régulière.

Traduit de la page anglaise: /docs/reference/barrel-api/ Modifier cette page Voir en Markdown

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