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.
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.
| Partie | Ce que c’est | Versionné | Répliqué |
|---|---|---|---|
| Document | Un objet JSON avec un id | oui, chaque écriture est une version | oui |
| Pièces jointes | Des blobs binaires nommés, par id de document et par nom | non, la dernière écriture l’emporte selon son horodatage | oui, sur leur propre flux |
| Vecteur | L’embedding des champs que vous choisissez | suit le document | non, 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.
barrel:put_doc(Db, #{<<"id">> => <<"kb-142">>,
<<"title">> => <<"Reset a locked account">>,
<<"_note">> => <<"dropped">>}),
barrel:get_doc(Db, <<"kb-142">>). {ok,#{<<"_rev">> =>
<<"000001a1ba45b14e00000000@wddc4e1c028733ad0">>,
<<"id">> => <<"kb-142">>,
<<"title">> => <<"Reset a locked account">>}} 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 _.
_revest la révision : le jeton de version que Barrel ajoute à la lecture. Renvoyez-le pour mettre le document à jour ; un_revabsent 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 (_noteci-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.
| Champ | Option de lecture | Ce qu’il contient |
|---|---|---|
_rev | toujours | Le jeton de la version gagnante |
_conflicts | conflicts => true | Les autres versions concurrentes |
_observed | conflicts => true | Chaque version que la lecture a montrée, à renvoyer lors d’une résolution |
_embedding | include_embedding => true | vector 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.
barrel:put_attachment(Db, <<"kb-142">>, <<"steps.md">>,
<<"1. Open the console">>),
barrel:list_attachments(Db, <<"kb-142">>). {ok,#{name => <<"steps.md">>,length => 19,
digest => <<"sha256-dd490eb840644ed69f89e41c5...">>,
content_type => <<"application/octet-stream">>,
chunked => false}}
[<<"steps.md">>] 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’écriture | Effet |
|---|---|
provenance => #{actor, session, source} | Stockée avec la version, affichée dans l’historique |
expires_at => UnixMs | Le document disparaît après cette date |
sync => true | Attend 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.
barrel:put_doc(Db, Doc,
#{provenance => #{actor => <<"agent-7">>,
session => <<"ses_42">>}}),
barrel:doc_versions(Db, <<"kb-142">>). {ok,[#{status => current,
version =>
<<"000001a1ba45b14e00000000@wddc4e1c028733ad0">>,
deleted => false,
provenance => #{session => <<"ses_42">>,
actor => <<"agent-7">>},
vv => #{<<"wddc4e1c028733ad0">> =>
{timestamp,1794126491982,0}}}]} 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.