Barrel
EN GitHub

Interroger avec BQL

BQL est le langage de requête de barrel, un dialecte de PartiQL (SQL pour JSON) : une seule instruction SELECT interroge les documents, la recherche vectorielle et la recherche par mots-clés, avec des abonnements en direct. Lisez ce guide si vous voulez interroger barrel avec une chaîne de requête plutôt qu’avec les maps de spécification structurées de find/2, ou si vous voulez que les résultats vectoriels et BM25 soient joints à leurs documents.

Quand l’utiliser

  • Vous voulez une seule surface de requête : filtres, projections, récupération top-k vectorielle ou par mots-clés, et mises à jour en direct avec la même syntaxe.
  • Vous pilotez barrel sur HTTP et voulez envoyer une chaîne de requête.
  • Pour construire des requêtes par programme, l’API structurée de spécification barrel:find/2 reste de premier plan ; BQL se compile sur le même moteur.

Lancer une requête

{ok, Db} = barrel:open(mydb),

{ok, Rows, Meta} = barrel:query(Db,
    <<"SELECT title, author.name AS who "
      "FROM db "
      "WHERE type = 'post' AND rank >= 3 "
      "ORDER BY title LIMIT 10">>),

%% paramètres nommés
{ok, Rows2, _} = barrel:query(Db,
    <<"SELECT * FROM db WHERE org = $org">>,
    #{params => #{<<"org">> => <<"acme">>}}).

Les lignes sont des maps : <<"id">> plus vos projections (SELECT * renvoie le document entier aplati). Un attribut manquant laisse sa clé absente de la ligne. Si vous embarquez seulement docdb, vous obtenez les mêmes requêtes sur les documents via barrel_docdb:query/2,3.

Savoir quel état a répondu

Chaque méta de résultat, depuis query/2,3 et query_fold/5, pour les requêtes sur collection comme pour les fonctions de table, porte la version observée de la base : instance_id (l’instance de la base) et last_seq (sa dernière séquence validée au moment de la requête). Deux réponses avec la même paire ont vu le même état.

{ok, _Rows, #{instance_id := Instance, last_seq := Seq, has_more := false}} =
    barrel:query(Db, <<"SELECT title FROM db ORDER BY title LIMIT 2">>).
%% Instance = <<"03798dac60334e1e">>, Seq = <<0,0,1,160,221,21,85,206,0,0,0,0>>

barrel_bql_query:row_bound/1 vous donne le nombre maximal de lignes qu’un plan compilé peut renvoyer : son LIMIT, ou k plafonné par LIMIT pour une fonction de table (undefined sans l’un ni l’autre).

{ok, Plan} = barrel_bql:compile(
    <<"SELECT * FROM vector_top_k('x', k => 20) AS v LIMIT 5">>, #{}),
5 = barrel_bql_query:row_bound(Plan).

Parcourir de gros résultats en flux

Les requêtes sans ORDER BY, UNNEST ni LIMIT sont envoyées en flux par morceaux : passez chunk_size et suivez Meta (has_more, continuation), ou faites un fold sans tout matérialiser :

{ok, Count, _} = barrel:query_fold(Db,
    <<"SELECT * FROM db WHERE type = 'post'">>, #{chunk_size => 100},
    fun(_Row, N) -> {ok, N + 1} end, 0).

Le langage

SELECT d.title, d.author.name AS who
FROM db AS d
WHERE d.type = 'post' AND (d.rank > 3 OR d.pinned = true)
ORDER BY d.title DESC
LIMIT 10 OFFSET 20
  • Le nom dans FROM est la variable de parcours ; la base vient de l’appel d’API. AS d est optionnel ; sans lui, le nom dans FROM sert d’alias.
  • Chemins : d.a.b, index de tableau d.tags[0], clés entre guillemets d."a key". Les mots-clés sont acceptés après un point (d.order). Les champs de premier niveau préfixés par _ sont réservés et rejetés.
  • Opérateurs : =, !=, <, <=, >, >=, IN (..), LIKE, BETWEEN a AND b, IS [NOT] NULL, IS [NOT] MISSING, CONTAINS(path, value), AND, OR, NOT. Les comparaisons ne correspondent qu’entre valeurs du même type (deux nombres ou deux chaînes).
  • Appartenance à un tableau : d.tags CONTAINS 'erlang' (infixe) et 'erlang' IN d.tags testent tous deux si la liste à d.tags contient la valeur ; ils équivalent à CONTAINS(d.tags, 'erlang'). IN avec une liste entre parenthèses, d.status IN ('a', 'b'), reste une appartenance à un ensemble de scalaires.
  • Les paramètres $name lient des scalaires depuis la map params.
  • WHERE id = 'x', les plages d’id et id LIKE 'prefix%' deviennent des parcours de clé primaire.
  • ORDER BY prend une seule clé ; les valeurs manquantes sont triées après les nombres et les chaînes.

L’égalité, les plages, LIKE 'prefix%', IS NOT MISSING et leurs combinaisons par AND utilisent les index de chemins. OR, IN, NOT, les LIKE en forme d’expression régulière, IS NULL, IS MISSING et CONTAINS font un parcours complet ; explain_query liste un avertissement {full_scan, _} pour chacun :

{ok, #{engine := #{strategy := Strategy}, warnings := Warnings}} =
    barrel:explain_query(Db, <<"SELECT * FROM db WHERE a = 1 OR b = 2">>).

MISSING ou NULL

PartiQL distingue un null stocké d’un attribut absent :

  • a IS MISSING : l’attribut est absent.
  • a IS NULL : l’attribut vaut null OU est absent.
  • a = NULL ne correspond jamais et est rejeté ; utilisez les formes ci-dessus.

Dérouler des tableaux avec UNNEST

UNNEST produit une ligne par élément du tableau ; l’élément reçoit son propre alias, utilisable dans WHERE, SELECT et ORDER BY. Les valeurs vides, manquantes ou qui ne sont pas des tableaux ne produisent aucune ligne.

SELECT d.title, t AS tag
FROM db AS d, UNNEST(d.tags) AS t
WHERE d.type = 'post' AND t = 'erlang'

Les prédicats sur l’élément sont évalués ligne par ligne ; les prédicats sur le document lui-même utilisent toujours les index.

Fonctions de table de recherche

La recherche vectorielle et la recherche par mots-clés entrent dans le langage comme sources de FROM. L’alias est obligatoire ; chaque fonction prend une chaîne de requête (ou $param) et des options nommées.

SELECT v._score, title FROM vector_top_k('rust orm', k => 10) AS v
SELECT m._score, title FROM bm25_top_k('rust', k => 10) AS m
SELECT h._score, title FROM hybrid_top_k('rust orm', k => 10) AS h
WHERE h.lang = 'en'
  • k vaut 10 par défaut ; vector_top_k accepte aussi ef_search.
  • hybrid_top_k fusionne les branches vectorielle et BM25 avec RRF.
  • Les résultats sont joints à leurs documents par id ; ceux dont le document a disparu sont écartés. Sur les bases en mode enregistrement, le texte de la requête est vectorisé par l’embedder de la base.
  • _score dépend de la fonction (1 - distance, BM25 brut, fusion RRF) et n’est pas comparable d’une fonction à l’autre. Les lignes de vector_top_k portent aussi _distance. Ce sont des colonnes de SELECT et d’ORDER BY uniquement.
  • Un WHERE filtre les résultats après la récupération : barrel récupère une fois plus large (3x k, plafonné à 1000) et renvoie JUSQU’À k lignes ; un filtrage fort peut en renvoyer moins. L’ordre par défaut est le rang de recherche.

Requêtes en direct

Ajoutez SUBSCRIBE et abonnez-vous au lieu d’exécuter : vous recevez le snapshot, puis des deltas d’ajout, de modification et de suppression quand des documents commencent ou cessent de correspondre.

{ok, Sub} = barrel:subscribe_query(Db,
    <<"SELECT name FROM db WHERE status = 'active' SUBSCRIBE">>),
#{ref := Ref} = Sub,
receive {bql_rows, Ref, Rows} -> Rows end,
receive {bql_ready, Ref, #{count := N}} -> N end,
%% puis, pour chaque écriture correspondante :
%% {bql_change, Ref, #{action := add | change, id, rev, row}}
%% {bql_change, Ref, #{action := remove, id}}
ok = barrel:unsubscribe_query(Sub).
  • LIMIT plafonne seulement le snapshot initial ; les deltas ne sont pas bornés.
  • Les fonctions de table, UNNEST, ORDER BY et OFFSET ne se combinent pas avec SUBSCRIBE.
  • La requête s’arrête quand vous vous désabonnez ou quand le processus propriétaire meurt. La détection des suppressions passe par le flux de changements : attendez-la dans son intervalle de polling (environ 100 ms).

Sur HTTP

POST /db/:db/query prend le texte BQL comme corps (ou du JSON {"query", "params", "continuation", "max_rows", "deadline_ms"}) et renvoie un flux ndjson : une ligne {"row": ...} par ligne, puis une ligne {"meta": ...} avec has_more, bound (limit_reached ou exhausted), la version observée (instance_id, last_seq en base64url) et, quand l’instruction est paginée, un jeton continuation à renvoyer par POST. max_rows (au plus 1000) et deadline_ms (au plus 300000) bornent la requête ; voir Borner une requête. Les erreurs de requête sont une 400 avec error: invalid_query, message, line et column.

curl -s http://localhost:8080/db/mydb/query \
  -d "SELECT title FROM db WHERE type = 'post' LIMIT 3"
{"row":{"id":"post:1","title":"..."}}
{"row":{"id":"post:2","title":"..."}}
{"row":{"id":"post:3","title":"..."}}
{"meta":{"bound":"limit_reached","has_more":false,"instance_id":"03798dac60334e1e","last_seq":"AAABoN0VVc4AAAAA"}}

Les instructions SUBSCRIBE nécessitent Accept: text/event-stream (ou une EventSource de navigateur sur GET /db/:db/query?q=...) et envoient en flux des événements row, ready, change et error avec un ping périodique.

Notes

  • Périmètre de la v1 : SELECT, WHERE, ORDER BY (une clé), LIMIT/OFFSET, UNNEST (un seul), les trois fonctions de table, SUBSCRIBE. Pas de jointures, pas de GROUP BY, pas de chemins avec joker [*] (utilisez UNNEST).
  • ORDER BY, UNNEST et LIMIT/OFFSET matérialisent leur résultat (borné) avant de répondre ; les filtres simples sont envoyés en flux.
  • Un SELECT de projections étroites lit tout de même les documents complets ; la projection a lieu après la lecture.

Traduit de la page anglaise: /docs/guides/query-bql/ (docs/guides/query-bql.md) Modifier cette page Voir en Markdown

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