barrel_docdb
Une base de documents intégrée, sur RocksDB. Les écritures sont versionnées par horloges logiques hybrides et vecteurs de version, chaque chemin est indexé pour les requêtes, et les bases se répliquent en active-active.
Ce qu’elle résout
Les copies d’une même donnée sur plusieurs nœuds, appareils ou agents reçoivent des écritures pendant qu’elles sont séparées. barrel_docdb garde chaque version concurrente comme un conflit au lieu d’en perdre une, vous laisse le résoudre, et vous donne sur le même stockage des requêtes, un flux de changements, des pièces jointes, un historique conservé avec sa provenance, un TTL et des branches.
Quand l’utiliser
- Vous avez besoin de documents synchronisés entre nœuds ou sites, avec des conflits conservés et résolubles.
- Vous avez besoin de requêtes sur n’importe quel champ sans déclarer d’index, avec
find/2ou BQL. - Vous avez besoin d’une piste d’audit : qui a écrit chaque version, et le contenu des versions passées.
Quand ne pas l’utiliser
- Il vous faut aussi des vecteurs ou de la recherche sémantique : utilisez barrel, qui associe cette bibliothèque à un magasin de vecteurs.
- Il vous faut des agrégats, GROUP BY ou des jointures : BQL n’en a pas.
Sa place dans Barrel
- Repose sur
barrel_crypto- Fonctionne avec, si présente
barrel_att_s3: stocke les octets des pièces jointes dans un stockage compatible S3- Utilisée par
barrel,barrel_ngram,barrel_spaces,barrel_server,barrel_att_s3- Autres dépendances
- rocksdb, hackney, hlc, match_trie, mimerl, instrument
- Seule
- Oui. La réplication (
barrel_rep,barrel_rep_tasks) et BQL pour les documents sont ici.
Installation
{barrel_docdb, "~> 3.1"} La version 2.1.0 a changé la réplication. Une mise à jour depuis la 2.0 peut demander barrel_rep:reconcile/3.
Configuration
Options de create_db/2
| Clé | Défaut | Rôle |
|---|---|---|
data_dir | data_dir de l’environnement | Emplacement des fichiers de la base |
att_opts | magasin de blobs RocksDB | #{backend => none} le désactive, s3 utilise barrel_att_s3 |
encryption | désactivé | default ou #{provider => Mod} |
channels | aucun | #{Name => [Pattern]}, fixé à la création |
retention_period | 2592000 s (30 jours) | Historique conservé ; 0 désactive le nettoyage |
ttl_sweep_interval | 0 (désactivé) | Nettoyage en arrière-plan des documents expirés |
max_conflict_versions | 8 | Conflits conservés par document |
conflict_resolver | aucun | Résolution automatique à la réplication |
Environnement de l’application (barrel_docdb)
| Clé | Défaut | Rôle |
|---|---|---|
data_dir | "data/barrel_docdb" | Relatif au répertoire courant |
block_cache_size | 512 MiB | Cache de blocs RocksDB |
query_timeout_ms | 30000 | Délai maximal d’une requête |
Seulement les clés les plus utilisées. Pour toutes les options, voyez la référence de configuration et la référence de l’API.
L’API par tâche
Bases
| Tâche | Appel | Renvoie |
|---|---|---|
| Créer, ouvrir | barrel_docdb:create_db/1,2, open_db/1 | {ok, Pid} |
| Fermer, supprimer | barrel_docdb:close_db/1, delete_db/1,2 | ok |
| Décrire, lister | barrel_docdb:db_info/1, list_dbs/0 | table d’infos, noms |
Documents
| Tâche | Appel | Renvoie |
|---|---|---|
| Écrire | barrel_docdb:put_doc/2,3, put_docs/2,3 | {ok, #{id, rev, ok}} ; {error, conflict} sans le _rev courant |
| Lire | barrel_docdb:get_doc/2,3, get_docs/2,3 | {ok, Doc} ou {error, not_found} |
| Supprimer | barrel_docdb:delete_doc/2,3 | {ok, _} |
| Conflits | barrel_docdb:get_conflicts/2, resolve_conflict/4 | {ok, [Rev]}, {ok, #{conflicts_resolved}} |
Requêtes et changements
| Tâche | Appel | Renvoie |
|---|---|---|
| Requête structurée | barrel_docdb:find/2,3, explain/2 | {ok, Rows, Meta} |
| BQL (documents seuls) | barrel_docdb:query/2,3 | {ok, Rows, Meta} |
| Flux de changements | barrel_docdb:get_changes/2,3, subscribe_changes/2,3 | {ok, Changes, Last}, un pid de flux |
| Abonnement à un chemin | barrel_docdb:subscribe/2,3, unsubscribe/1 | des messages {barrel_change, Db, Change} |
Fichiers, historique, timeline, synchronisation
| Tâche | Appel | Renvoie |
|---|---|---|
| Pièces jointes | put_attachment/4,5, get_attachment/3, open_attachment_writer/4,5 | {ok, Info}, {ok, Bytes} |
| Versions | get_doc_versions/2, get_version_body/3, fold_history/3,4 | {ok, [Version]} avec la provenance |
| Branche, fusion | branch_db/3, merge_branch/2, list_branches/1 | {ok, _}, {ok, Report} |
| Répliquer une fois | barrel_rep:replicate/2,3 | {ok, Report} |
| Tâche continue | barrel_rep_tasks:start_task/1, get_task/1, stop_task/1 | {ok, TaskId} |
Écrire, chercher et interroger
D’après une exécution vérifiée sur un répertoire de données vierge.
{ok, _} = application:ensure_all_started(barrel_docdb).
{ok, _} = barrel_docdb:create_db(<<"kb">>).
barrel_docdb:put_docs(<<"kb">>, [
#{<<"id">> => <<"kb:101">>, <<"type">> => <<"article">>,
<<"title">> => <<"Reset a forgotten password">>,
<<"views">> => 1200,
<<"tags">> => [<<"account">>, <<"login">>]},
#{<<"id">> => <<"kb:102">>, <<"type">> => <<"article">>,
<<"title">> => <<"Configure SSO with Okta">>,
<<"views">> => 430,
<<"tags">> => [<<"sso">>, <<"login">>]},
#{<<"id">> => <<"kb:201">>, <<"type">> => <<"article">>,
<<"title">> => <<"Export invoices as CSV">>,
<<"views">> => 980,
<<"tags">> => [<<"export">>]}]).
barrel_docdb:find(<<"kb">>, #{id_prefix => <<"kb:1">>,
include_docs => false}).
barrel_docdb:query(<<"kb">>,
<<"SELECT title, views FROM kb WHERE type = 'article' "
"AND views >= 500 ORDER BY views DESC">>). [{ok,#{<<"id">> => <<"kb:101">>,<<"ok">> => true,
<<"rev">> =>
<<"000001a1b8784bea00000000@waec6d4b23aba0dca">>}},
...]
{ok,[#{<<"id">> => <<"kb:101">>},#{<<"id">> => <<"kb:102">>}],
#{has_more => false, ...}}
{ok,[#{<<"id">> => <<"kb:101">>,
<<"title">> => <<"Reset a forgotten password">>,
<<"views">> => 1200},
#{<<"id">> => <<"kb:201">>,
<<"title">> => <<"Export invoices as CSV">>,
<<"views">> => 980}],
#{count => 2, has_more => false, ...}} Résoudre un conflit après une réplication dans les deux sens
Deux bases locales ont modifié le même document, puis se sont répliquées dans les deux sens. La résolution nomme les versions qu’elle a observées.
barrel_rep:replicate(<<"edge_a">>, <<"edge_b">>),
barrel_rep:replicate(<<"edge_b">>, <<"edge_a">>).
%% both sides edited task:1 while apart
barrel_docdb:get_conflicts(<<"edge_a">>, <<"task:1">>).
{ok, #{<<"_observed">> := Seen}} =
barrel_docdb:get_doc(<<"edge_a">>, <<"task:1">>,
#{conflicts => true}).
barrel_docdb:resolve_conflict(<<"edge_a">>, <<"task:1">>,
Seen, {merge, Merged}).
%% Merged: the body to keep, here with a "note" field {ok,[<<"000001a1b879d59100000000@w7bcb971434496877">>]}
{ok,#{id => <<"task:1">>,
rev => <<"000001a1b879d59500000000@w7bcb971434496877">>,
conflicts_resolved => 1}} Limites à connaître
- La lignée est linéaire : une branche d’une branche est refusée, et une branche à un instant antérieur au plancher de l’historique échoue avec
pitr_window_exceeded. - La réplication ne transporte ni les vecteurs ni la provenance. Les canaux ne suppriment pas des réplicas les documents qui en sont sortis.
- Les tâches de réplication refusent les identifiants passés en ligne. Les points de reprise des pièces jointes attendent que la cible soit durable, sauf si vous fixez
att_durability => best_effort. - Les réglages d’exécution (
encryption,read_only,channels,conflict_resolver, rétention) doivent être repassés à chaque réouverture. - Le
data_dirde l’environnement est relatif au répertoire courant. La documentation decreate_db/2indique encore/tmp/barrel_data.
Dans find/2, order_by sur un chemin est ignoré si ce chemin n’est pas sélectionné ou lié à une variable.
Une requête BQL découpée en morceaux avec un prédicat d’intervalle a perdu une ligne à la continuation, une fois pendant les tests ; le cas n’est pas encore réduit.