Barrel
EN GitHub

L’enregistrement

Une application qui fait de la recherche sur son propre contenu garde souvent trois choses à trois endroits : les données dans une base, les fichiers dans un stockage objet, et les vecteurs dans une base vectorielle. Chaque mise à jour demande alors trois écritures, et tôt ou tard un article supprimé ressort encore dans la recherche, ou un fichier pointe vers une ligne qui n’existe plus. Barrel évite ce décalage en gardant les trois sous un même id.

Un enregistrement est tout ce que Barrel garde sous cet id : un document JSON, les fichiers qui y sont attachés et, en mode enregistrement, le vecteur qui le représente. Ils sont lus, écrits, répliqués et supprimés par cet id. Lisez cette page pour savoir à quoi ressemble un document à l’entrée et à la sortie, quels champs Barrel ajoute, et ce qui accompagne l’enregistrement.

id: kb-142 document JSON, versions gardées pièces jointes fichiers, stockés par blocs vecteur calculé à partir des champs
Un seul id : le document en haut, les pièces jointes à gauche, le vecteur à droite.

Prenons l’article de support kb-142, « Reset a locked account ». Ses champs forment le document, le fichier steps.md est une pièce jointe, et le vecteur calculé à partir de son texte permet à une recherche par le sens de le retrouver. Cette page suit cet article du début à la fin.

Les trois parties

Chaque partie d’un enregistrement se comporte un peu différemment quand elle change ou quand elle part vers une autre copie de la base. Le tableau résume ; les sections qui suivent détaillent chaque ligne.

PartieCe que c’estVersionnéRépliqué
DocumentUn objet JSON avec un idoui, chaque écriture est une versionoui
Pièces jointesDes blobs binaires nommés, par id de document et par nomnon, la dernière écriture l’emporte selon son horodatageoui, sur leur propre flux
VecteurL’embedding des champs que vous choisissezsuit le documentnon, chaque copie le reconstruit

Le document

Le document est la partie que vous interrogez. Vous écrivez une map avec un id. Chaque chemin qu’elle contient est indexé : vous pouvez donc interroger n’importe quel champ sans déclarer d’index.

Shell Erlang
barrel:put_doc(Db, #{<<"id">> => <<"kb-142">>,
  <<"title">> => <<"Reset a locked account">>,
  <<"_note">> => <<"dropped">>}),
barrel:get_doc(Db, <<"kb-142">>).
Sortie d’une exécution sur barrel 1.12.0
{ok,#{<<"_rev">> =>
        <<"000001a1ba45b14e00000000@wddc4e1c028733ad0">>,
    <<"id">> => <<"kb-142">>,
    <<"title">> => <<"Reset a locked account">>}}
Ce qui vient de se passer

La lecture renvoie votre id et votre title, plus un _rev ajouté par Barrel. Le champ _note que vous aviez envoyé a disparu : Barrel l’a écarté parce qu’il commence par _.

  • _rev est la révision : le jeton de version que Barrel ajoute à la lecture. Renvoyez-le pour mettre le document à jour ; un _rev absent ou périmé renvoie {error, conflict}. Vous ne pouvez donc pas écraser une modification que vous n’avez pas lue. Voir Versions, conflits, convergence.
  • Les champs de premier niveau qui commencent par _ sont réservés. Barrel écarte ceux que vous envoyez (_note ci-dessus) et ne les indexe jamais.
  • Une suppression écrit une version qui marque le document comme supprimé. Une lecture renvoie alors {error, not_found}, et le vecteur disparaît aussi.

Champs que Barrel ajoute à la demande

En plus de _rev, Barrel ajoute quelques champs à une lecture quand vous les demandez. Vous en avez besoin quand un document a des conflits à résoudre, ou quand vous voulez voir le vecteur derrière un résultat de recherche.

ChampOption de lectureCe qu’il contient
_revtoujoursLe jeton de la version gagnante
_conflictsconflicts => trueLes autres versions concurrentes
_observedconflicts => trueChaque version que la lecture a montrée, à renvoyer lors d’une résolution
_embeddinginclude_embedding => truevector et source (computed quand Barrel a calculé l’embedding)

Les pièces jointes

Une pièce jointe est un fichier nommé qui appartient à un id de document, comme le fichier steps.md de kb-142. Utilisez-les pour le contenu qui n’est pas du JSON. En écrire une ne change pas le _rev du document : mettre à jour un fichier n’entre donc jamais en conflit avec une modification du document.

Shell Erlang
barrel:put_attachment(Db, <<"kb-142">>, <<"steps.md">>,
                    <<"1. Open the console">>),
barrel:list_attachments(Db, <<"kb-142">>).
Sortie d’une exécution sur barrel 1.12.0, empreinte raccourcie
{ok,#{name => <<"steps.md">>,length => 19,
    digest => <<"sha256-dd490eb840644ed69f89e41c5...">>,
    content_type => <<"application/octet-stream">>,
    chunked => false}}
[<<"steps.md">>]
Ce qui vient de se passer

L’écriture renvoie les métadonnées de la pièce jointe : son nom, sa taille en octets (19), une empreinte SHA-256 du contenu, et un type de contenu générique faute d’en avoir donné un. La liste montre ensuite steps.md comme seule pièce jointe de kb-142.

Voir Pièces jointes.

Le vecteur

Un vecteur est une liste de nombres qui représente le sens d’un texte. C’est lui qui permet à une recherche de trouver kb-142 quand la requête n’emploie pas les mots de l’article.

En mode enregistrement, vous donnez à la base une politique d’embedding : quels champs traiter, avec quel fournisseur, à quelle dimension. Barrel calcule l’embedding de ces champs à chaque écriture et supprime le vecteur à la suppression. Les résultats de recherche lisent leur texte et leurs métadonnées dans le document courant : ils ne montrent jamais une copie périmée.

Dans une base simple, vous gérez les vecteurs vous-même avec vector_add, sous le même id ou un autre. Le document et son vecteur sont alors deux écritures séparées, et c’est à vous de les garder synchronisés.

Ce qu’une écriture peut porter d’autre

Une écriture peut porter des options en plus du document. Elles disent qui a fait la modification, combien de temps le document vit, et s’il faut attendre le disque.

Option d’écritureEffet
provenance => #{actor, session, source}Stockée avec la version, affichée dans l’historique
expires_at => UnixMsLe document disparaît après cette date
sync => trueAttend que l’écriture atteigne le disque

Ici, un agent, agent-7, s’enregistre avec sa session comme auteur d’une écriture. L’historique des versions montre ensuite qui a modifié l’article.

Shell Erlang
barrel:put_doc(Db, Doc,
  #{provenance => #{actor => <<"agent-7">>,
                    session => <<"ses_42">>}}),
barrel:doc_versions(Db, <<"kb-142">>).
Sortie d’une exécution sur barrel 1.12.0
{ok,[#{status => current,
     version =>
         <<"000001a1ba45b14e00000000@wddc4e1c028733ad0">>,
     deleted => false,
     provenance => #{session => <<"ses_42">>,
                     actor => <<"agent-7">>},
     vv => #{<<"wddc4e1c028733ad0">> =>
                 {timestamp,1794126491982,0}}}]}
Ce qui vient de se passer

L’historique contient une seule version, marquée current et non supprimée. Sa provenance contient l’acteur et la session que vous avez passés. vv est le vecteur de versions : pour chaque écrivain, la dernière horloge que cette version avait vue.

La provenance n’est pas répliquée. Voir Audit et provenance.

Traduit de la page anglaise: /docs/concepts/record/ Modifier cette page Voir en Markdown

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