Interroger deux bases comme des contextes
Ce projet enregistre deux bases, les tickets de support de deux régions,
comme contextes et exécute une seule instruction BQL sur les deux. La
réponse fusionne les lignes dans l’ordre de ORDER BY et indique de
quel contexte vient chaque ligne, quels contextes ont répondu et ce que
couvre chaque réponse. Un troisième contexte pointe vers un nœud arrêté :
la même requête renvoie alors une réponse partielle, avec la raison.
Utilisez les contextes quand un agent doit chercher dans des données
réparties sur plusieurs bases ou nœuds et doit savoir ce qu’il n’a pas vu.
Prérequis
- Erlang/OTP 26 ou plus récent (cette exécution a utilisé OTP 29) et rebar3.
- Un compilateur C et CMake pour les dépendances natives (la première compilation prend quelques minutes).
Exécuter
./run.sh
run.sh compile le projet, supprime ./data, puis exécute
contexts_bql:main/0 une fois.
Ce que montre l’exemple
barrel_ctx:register/1: une fiche avec un nom et un emplacement, local (une base sur ce nœud) ou distant (un point d’accès barrel_server et une base sur celui-ci).barrel_ctx:query/1avecqueryetcontexts: chaque contexte exécute la même instruction ; le nom aprèsFROMest ignoré.executionvautsucceeded,partialoufailed;sourcesa une entrée par contexte avec son statut, son nombre de lignes etbound;coverageles compte ;summarydit la même chose en un paragraphe.- Avec
offline => true, les contextes distants sont ignorés, pas contactés. - Une requête de lignes sur des contextes exige
LIMIT: sans lui, la requête est refusée avant qu’aucun contexte ne s’exécute.
Notes
- Non pris en charge entre contextes :
SUBSCRIBE,OFFSET,UNNEST, les continuations et la fusion des scores BM25 ou hybrides (ceux-ci reviennent groupés par contexte). - Les mêmes requêtes passent par REST (
POST /contexts/_query) et MCP (context_query) sur barrel_server.
Sortie attendue
Trois réponses et un refus. La sortie d’une exécution réelle se trouve
dans expected.txt.
Télécharger Le dossier sur GitHub, avec tous les fichiers ci-dessous.
Code source
%% Two databases registered as contexts and queried together with
%% one BQL statement; a third context that cannot answer shows a
%% partial result.
-module(contexts_bql).
-export([main/0]).
-define(Q, <<"SELECT id, subject, minutes FROM c "
"ORDER BY minutes DESC LIMIT 3">>).
main() ->
try run() of
ok -> halt(0)
catch C:R:S ->
io:format(standard_error, "~p:~p~n~p~n", [C, R, S]),
halt(1)
end.
run() ->
{ok, _} = application:ensure_all_started(barrel),
%% Two ordinary databases, one per region.
{ok, Eu} = barrel_dbs:ensure(<<"tickets_eu">>, #{vectordb => none}),
{ok, Us} = barrel_dbs:ensure(<<"tickets_us">>, #{vectordb => none}),
_ = barrel:put_docs(Eu, [
ticket(<<"t:1">>, <<"Invoice PDF missing">>, 42),
ticket(<<"t:2">>, <<"SSO loop on Safari">>, 95),
ticket(<<"t:3">>, <<"CSV export times out">>, 30)]),
_ = barrel:put_docs(Us, [
ticket(<<"t:7">>, <<"Password reset email late">>, 61),
ticket(<<"t:8">>, <<"Webhook retries twice">>, 12)]),
%% One card per context. A card names where the data lives.
ok = add_context(<<"support/eu">>, local(<<"tickets_eu">>)),
ok = add_context(<<"support/us">>, local(<<"tickets_us">>)),
%% A remote node that is down (nothing listens on port 1).
ok = add_context(<<"support/apac">>,
#{<<"kind">> => <<"remote">>,
<<"endpoint">> => <<"http://127.0.0.1:1">>,
<<"db">> => <<"tickets_apac">>}),
io:format("== eu and us~n"),
report(barrel_ctx:query(#{
query => ?Q,
contexts => [<<"support/eu">>, <<"support/us">>]})),
io:format("~n== eu, us and apac (apac is down)~n"),
report(barrel_ctx:query(#{
query => ?Q,
contexts => [<<"support/eu">>, <<"support/us">>,
<<"support/apac">>]})),
io:format("~n== the same, offline~n"),
report(barrel_ctx:query(#{
query => ?Q, offline => true,
contexts => [<<"support/eu">>, <<"support/us">>,
<<"support/apac">>]})),
io:format("~n== a row query without LIMIT~n"),
io:format("~p~n", [barrel_ctx:query(#{
query => <<"SELECT id FROM c">>,
contexts => [<<"support/eu">>]})]),
ok.
ticket(Id, Subject, Minutes) ->
#{<<"id">> => Id, <<"subject">> => Subject,
<<"minutes">> => Minutes}.
local(Db) -> #{<<"kind">> => <<"local">>, <<"db">> => Db}.
add_context(Name, Location) ->
{ok, _Card} = barrel_ctx:register(
#{<<"name">> => Name, <<"locations">> => [Location]}),
ok.
report({ok, R}) ->
io:format("execution: ~p, merge: ~p~n",
[maps:get(execution, R), maps:get(merge, R)]),
io:format("rows:~n"),
[io:format(" ~-12s ~-5s ~3b ~s~n",
[maps:get(<<"_ctx_name">>, Row), maps:get(<<"id">>, Row),
maps:get(<<"minutes">>, Row),
maps:get(<<"subject">>, Row)])
|| Row <- maps:get(rows, R)],
io:format("sources:~n"),
[source(S) || S <- maps:get(sources, R)],
C = maps:get(coverage, R),
io:format("coverage: requested ~b, answered ~b, failed ~b, "
"skipped ~b~n",
[maps:get(K, C) || K <- [requested, answered, failed,
skipped]]),
io:format("summary:~n"),
[io:format(" ~s~n", [L]) || L <- wrap(maps:get(summary, R), 62)],
ok.
source(#{name := N, status := St} = S) ->
case S of
#{error := #{reason := Why}} ->
io:format(" ~-12s ~p: ~p~n", [N, St, Why]);
#{rows := Rows, bound := Bound} ->
io:format(" ~-12s ~p, ~b rows, ~p~n", [N, St, Rows, Bound])
end.
%% Word-wrap a binary to lines of at most Width characters.
wrap(Text, Width) ->
Words = string:lexemes(Text, " "),
{Lines, Last} = lists:foldl(
fun(W, {Acc, <<>>}) -> {Acc, W};
(W, {Acc, Cur}) ->
case string:length(Cur) + 1 + string:length(W) of
L when L > Width -> {[Cur | Acc], W};
_ -> {Acc, <<Cur/binary, " ", W/binary>>}
end
end, {[], <<>>}, Words),
lists:reverse([Last | Lines]). {erl_opts, [debug_info]}.
{deps, [{barrel, "~> 1.12"}]}. #!/bin/sh
# Build, then run main/0 once on a fresh data directory.
set -e
cd "$(dirname "$0")"
rebar3 compile >&2
rm -rf data
exec erl -noshell -config config/sys \
-pa _build/default/lib/*/ebin _build/default/checkouts/*/ebin \
-eval 'contexts_bql:main()' Sortie attendue
Le fichier expected.txt de l’exemple, issu d’une exécution réelle. Les révisions, identifiants, jetons et horodatages changent à chaque exécution ; scripts/verify-examples.sh les masque avant de comparer.
== eu and us
execution: succeeded, merge: ordered
rows:
support/eu t:2 95 SSO loop on Safari
support/us t:7 61 Password reset email late
support/eu t:1 42 Invoice PDF missing
sources:
support/eu ok, 3 rows, limit_reached
support/us ok, 2 rows, exhausted
coverage: requested 2, answered 2, failed 0, skipped 0
summary:
All 2 contexts answered (support/eu, support/us). 3 rows are
merged across contexts in ORDER BY order. support/eu filled
the LIMIT or k; more matches may exist.
== eu, us and apac (apac is down)
execution: partial, merge: ordered
rows:
support/eu t:2 95 SSO loop on Safari
support/us t:7 61 Password reset email late
support/eu t:1 42 Invoice PDF missing
sources:
support/eu ok, 3 rows, limit_reached
support/us ok, 2 rows, exhausted
support/apac unreachable: econnrefused
coverage: requested 3, answered 2, failed 1, skipped 0
summary:
2 of 3 contexts answered; rows from the others are not
included. support/apac: the server did not accept the
connection (econnrefused). 3 rows are merged across contexts
in ORDER BY order. support/eu filled the LIMIT or k; more
matches may exist.
== the same, offline
execution: partial, merge: ordered
rows:
support/eu t:2 95 SSO loop on Safari
support/us t:7 61 Password reset email late
support/eu t:1 42 Invoice PDF missing
sources:
support/eu ok, 3 rows, limit_reached
support/us ok, 2 rows, exhausted
support/apac skipped_offline: no_local_copy
coverage: requested 3, answered 2, failed 0, skipped 1
summary:
2 of 3 contexts answered; rows from the others are not
included. support/apac: skipped: offline and no local copy. 3
rows are merged across contexts in ORDER BY order. support/eu
filled the LIMIT or k; more matches may exist.
== a row query without LIMIT
{error,{limit_required,#{max_limit => 1000}}}