# Démarrage rapide : embarqué

Dans ce démarrage rapide, vous ajoutez Barrel à une application Erlang
et construisez une petite base de connaissances de support : trois
articles, comme kb-142 « Reset a locked account ». Vous les stockez sous
forme de documents JSON, vous les sélectionnez avec une requête, puis vous
retrouvez le bon article à partir d’une question formulée autrement,
comme « I cannot log in ». Suivez ce parcours quand Barrel tournera dans
votre propre release OTP, sans serveur entre les deux : la base est une
bibliothèque que votre code appelle directement, sans saut réseau ni
processus séparé à déployer.

<Goal time="10 minutes" items={["Créer une release OTP qui dépend de barrel", "Écrire et lire des documents JSON", "Sélectionner des documents avec une requête BQL", "Rechercher les articles par leur sens avec des embeddings locaux"]} />

## Avant de commencer

- Erlang/OTP 26 ou plus récent, et rebar3, pour compiler et lancer la
  release.
- CMake et un compilateur C++ : le stockage vectoriel compile une
  bibliothèque native.
- Pour l’étape 5 seulement : [Ollama](https://ollama.com) en marche en
  local avec le modèle `nomic-embed-text` (`ollama pull nomic-embed-text`). Ollama transforme un texte en
  [embedding](/fr/docs/concepts/glossary#embedding), une liste de nombres
  qui place près les uns des autres les textes de sens voisin.

## 1. Créer le projet

Vous partez d’une release OTP vide : Barrel tourne ainsi dans votre
propre application, comme il le fera en production.

```shell
rebar3 new release kb
cd kb
```

Ajoutez barrel aux dépendances, et indiquez-lui où garder ses fichiers.
`data_dir` est le répertoire où le stockage de documents écrit sur
disque.

rebar.config:

```erlang
{deps, [{barrel, "~> 1.14"}]}.
```

config/sys.config:

```erlang
[{barrel_docdb, [{data_dir, "data/docdb"}]}].
```

## 2. Ouvrir une base

Une base est un stockage nommé de documents. L’ouvrir vous donne un
descripteur que vous passez à chaque appel suivant. Lancez un shell avec `rebar3 shell`. `vectordb => none` n’ouvre que le
stockage de documents, donc aucun modèle n’est encore nécessaire.

Shell Erlang:

```erlang
{ok, _} = application:ensure_all_started(barrel),
{ok, Db} = barrel:open(<<"kb">>, #{vectordb => none}).
```

## 3. Écrire des documents

Chaque article est un document JSON, écrit en Erlang sous forme de map à
clés binaires. Le champ `id` nomme le document ; c’est par cet id que vous
le relisez. Ici, vous écrivez les trois articles, puis vous relisez
kb-207.

Shell Erlang:

```erlang
Articles = [
  #{<<"id">> => <<"kb-142">>, <<"product">> => <<"console">>,
    <<"title">> => <<"Reset a locked account">>},
  #{<<"id">> => <<"kb-207">>, <<"product">> => <<"console">>,
    <<"title">> => <<"Rotate an API key">>},
  #{<<"id">> => <<"kb-311">>, <<"product">> => <<"mobile">>,
    <<"title">> => <<"Sign in with a passkey">>}],
[{ok, _} = barrel:put_doc(Db, A) || A <- Articles],
barrel:get_doc(Db, <<"kb-207">>).
```

Sortie d’une exécution sur barrel 1.12.0:

```
{ok,#{<<"_rev">> =>
          <<"000001a1ba3fd05d00000000@w4f0cb98700ad5ffc">>,
      <<"id">> => <<"kb-207">>,<<"product">> => <<"console">>,
      <<"title">> => <<"Rotate an API key">>}}
```

> **Note:** Barrel a stocké le document tel que vous l’avez écrit et a ajouté `_rev`,
> le jeton de [révision](/fr/docs/concepts/glossary#revision) de cette
> écriture. La partie avant `@` est une valeur d’horloge, celle d’après
> désigne l’auteur de l’écriture. Pour mettre le document à jour, renvoyez
> `_rev` avec votre modification : Barrel sait alors quelle version vous
> avez modifiée, et une modification faite sur une copie périmée ne peut pas
> écraser en silence une version plus récente. Voir
> [L’enregistrement](/fr/docs/concepts/record).

## 4. Interroger avec BQL

[BQL](/fr/docs/concepts/glossary#bql) est le langage de requête de
Barrel, proche de SQL. Chaque champ est indexé : vous pouvez filtrer et
trier sur n’importe quel champ sans déclarer d’index au préalable. Cette
requête sélectionne les articles de la console.

Shell Erlang:

```erlang
{ok, Rows, _Meta} = barrel:query(Db,
    <<"SELECT id, title FROM kb "
      "WHERE product = 'console' ORDER BY id">>).
```

Sortie d’une exécution sur barrel 1.12.0:

```
{ok,[#{<<"id">> => <<"kb-142">>,
       <<"title">> => <<"Reset a locked account">>},
     #{<<"id">> => <<"kb-207">>,
       <<"title">> => <<"Rotate an API key">>}],
        #{count => 2, ...}}
```

> **Note:** Le résultat est une liste de lignes, une map par document, qui ne
> contient que les champs sélectionnés, dans l’ordre des `id`. kb-311
> manque, car son `product` vaut `mobile`. La dernière map contient des
> métadonnées sur la réponse ; `count` est le nombre de lignes.

## 5. Rechercher par le sens

Un filtre BQL trouve « console », mais pas « I cannot log in » : aucun
titre ne contient ces mots. La recherche par le sens compare des
embeddings : une question retrouve ainsi l’article qui y répond.

Ouvrez une deuxième base en [mode
enregistrement](/fr/docs/concepts/glossary#record-mode). Dans ce mode,
Barrel calcule l’embedding des champs que vous nommez (ici `title`) pour
chaque document écrit, et garde l’index vectoriel en phase avec les
modifications et suppressions suivantes : vous ne gérez jamais les
vecteurs vous-même. `mode => sync` calcule l’embedding avant que
l’écriture ne rende la main, si bien qu’une recherche juste après la
trouve. Le mode enregistrement ne traite que les documents écrits
après son activation : vous réécrivez donc les articles dans cette
nouvelle base.

Shell Erlang:

```erlang
{ok, Kb} = barrel:open(<<"kb_search">>, #{
    embedding => #{
        fields   => [<<"title">>],
        mode     => sync,
        embedder => {ollama,
                     #{model => <<"nomic-embed-text">>}}},
    vectordb => #{db_path => "data/vectors/kb_search"}}),
[{ok, _} = barrel:put_doc(Kb, A) || A <- Articles],
barrel:search(Kb, <<"I cannot log in">>, #{k => 2}).
```

Sortie d’une exécution sur barrel 1.12.0 avec Ollama nomic-embed-text:

```
{ok,[#{text => <<"Sign in with a passkey">>,
       metadata =>
           #{<<"product">> => <<"mobile">>,
             <<"title">> => <<"Sign in with a passkey">>},
       key => <<"kb-311">>,score => 0.5656703092487099},
     #{text => <<"Reset a locked account">>,
       metadata =>
           #{<<"product">> => <<"console">>,
             <<"title">> => <<"Reset a locked account">>},
              key => <<"kb-142">>,score => 0.5460874853125287}]}
```

> **Note:** Vous avez demandé les 2 articles les plus proches (`k => 2`). Chaque
> résultat donne l’id du document dans `key`, le texte calculé dans
> `text`, les autres champs dans `metadata`, et un `score` de similarité,
> le plus haut en premier. Aucun titre ne contient « log in », et pourtant
> les deux articles de connexion reviennent, pas celui sur la clé d’API.

La même recherche s’exécute depuis BQL, jointe aux documents : vous
pouvez donc sélectionner des champs du document à côté du score :

Shell Erlang:

```erlang
barrel:query(Kb,
    <<"SELECT v.id, v._score, title "
      "FROM vector_top_k('lost my credentials', k => 2) AS v">>).
```

Sortie d’une exécution sur barrel 1.12.0 avec Ollama nomic-embed-text:

```
{ok,[#{<<"_score">> => 0.5919581721812395,
       <<"id">> => <<"kb-142">>,
       <<"title">> => <<"Reset a locked account">>},
     #{<<"_score">> => 0.47384916313011594,
       <<"id">> => <<"kb-311">>,
       <<"title">> => <<"Sign in with a passkey">>}],
        #{count => 2, ...}}
```

> **Note:** `vector_top_k` est une fonction de table : elle renvoie les documents les
> plus proches sous forme de lignes, avec l’alias `v`, leur `id` et leur
> `_score`. `title` vient du document lui-même. Avec une autre question,
> « lost my credentials », kb-142 passe en tête.

> **Note:** Le mode enregistrement traite ce que vous écrivez après son activation ;
> il n’indexe pas les documents déjà présents dans une base ouverte sans
> lui. Pas d’Ollama ? N’importe quel fournisseur fonctionne ici : un modèle
> local via un virtualenv Python, ou une API cloud avec une clé. Voir
> [Choisir un fournisseur
> d’embeddings](/fr/docs/search/embedding-providers).

Définissez `db_path` comme ci-dessus pour choisir où vit le stockage
vectoriel. Sans lui, le stockage va à côté des documents, dans
`<data_dir>/kb_search.vectordb`.

## 6. Fermer

Fermer une base libère son descripteur. Les données restent sur disque,
et le prochain `barrel:open/2` avec le même nom les retrouve.

Shell Erlang:

```erlang
ok = barrel:close(Db),
ok = barrel:close(Kb).
```

<NextSteps steps={[
  { href: '/docs/guides/query-bql', label: 'Interroger avec BQL', why: 'Découvrez les filtres, les tris et les fonctions de table utilisés ici.' },
  { href: '/docs/search/hybrid', label: 'Vectorielle, par mot-clé et hybride', why: 'Combinez le sens et les mots-clés exacts dans une seule recherche.' },
  { href: '/docs/guides/synchronization', label: 'Synchronisation', why: 'Gardez une deuxième copie de la base en phase avec celle-ci.' },
  { href: '/docs/guides/timeline', label: 'Brancher, fusionner, récupérer', why: 'Essayez des changements sur une branche sans toucher l’original.' },
]} />
