Barrel
EN GitHub

Référence BQL

BQL est le langage de requête de Barrel : un petit SELECT dans le style de PartiQL sur les documents, plus des fonctions de table de recherche et des requêtes en direct. Cette page est la référence de syntaxe, tirée du lexer, du parser et du compilateur de barrel_docdb. Utilisez-la pour vérifier qu’une instruction est valide ; pour des exemples complets, lisez Interroger avec BQL.

Où une instruction s’exécute

AppelExécute
barrel:query/2,3, barrel:query_fold/5, barrel:explain_query/2,3Tout ce qui suit, fonctions de table comprises
barrel:subscribe_query/2,3Les instructions SUBSCRIBE
barrel_docdb:query/2,3Les documents seulement : les fonctions de table renvoient {error, {table_fn_requires_barrel, Fn}}, SUBSCRIBE renvoie {error, {unsupported, subscribe}}
POST /db/:db/query, MCP queryTout ; SUBSCRIBE demande SSE en REST et query_subscribe en MCP

Forme d’une instruction

SELECT select_list FROM source [ [AS] alias ]
  [ , UNNEST ( path ) AS ident ]
  [ WHERE expr ]
  [ ORDER BY path [ASC | DESC] ]
  [ LIMIT int ] [ OFFSET int ]
  [ SUBSCRIBE ]
  • select_list vaut *, ou des chemins avec un AS name facultatif, séparés par des virgules. L’id est toujours renvoyé.
  • source est un nom de collection, ou une fonction de table de recherche. Le nom de collection n’est qu’un alias : la base vient de l’appel.
  • ORDER BY prend une seule clé.
SELECT k.title, t AS tag
FROM kb AS k, UNNEST(k.tags) AS t
WHERE t LIKE 'log%'

Chemins et littéraux

  • Un chemin commence par un nom et continue avec .key ou [index] : title, owner.name, labels[0], t.owner.name. N’importe quel mot-clé peut suivre un point.
  • Les "guillemets doubles" nomment un champ : "time spent". Doublez un guillemet pour l’échapper.
  • Les 'apostrophes' délimitent des chaînes ; doublez une apostrophe pour l’échapper.
  • Les nombres sont des entiers ou des flottants, avec un moins unaire. TRUE, FALSE et NULL sont des littéraux.
  • $name est un paramètre. -- commence un commentaire jusqu’à la fin de la ligne.
  • Les mots-clés ne tiennent pas compte de la casse.

Prédicats

Combinez-les avec AND, OR, NOT et des parenthèses.

FormeCorrespond à
a = b, !=, <>, <, <=, >, >=Une comparaison entre un chemin et un littéral ou un paramètre. Des valeurs de types différents ne correspondent jamais.
x IS [NOT] NULLUn null stocké, ou un champ absent
x IS [NOT] MISSINGUn champ absent seulement
x [NOT] IN ('a', 'b')Un élément d’un ensemble de littéraux
'a' [NOT] IN tagsL’appartenance à un tableau ; identique à CONTAINS
CONTAINS(tags, 'a'), tags CONTAINS 'a'Un tableau qui contient la valeur
x [NOT] LIKE 'pat%'% une suite quelconque, _ un caractère
x [NOT] BETWEEN a AND bUn intervalle inclusif

Sur id, seuls =, les intervalles et LIKE 'prefix%' (sans % ni _ dans le préfixe) sont acceptés, et pas à l’intérieur d’un OR.

L’index de chemins sert l’égalité, les intervalles, LIKE 'prefix%', IS NOT MISSING et leurs AND. OR, IN, NOT, les autres motifs LIKE, IS NULL, IS MISSING et CONTAINS font un parcours complet ; explain_query avertit alors {full_scan, _}.

Paramètres

Liez $name avec l’option params. Les clés sont des binaires :

barrel:query(Db,
    <<"SELECT id, title FROM kb WHERE product = $p">>,
    #{params => #{<<"p">> => <<"portal">>}}).

Un paramètre doit être un scalaire. Un paramètre manquant échoue avec {unbound_param, Name}. En REST, envoyez "params": {"p": "portal"} dans le corps JSON.

Fonctions de table de recherche

Une fonction de table est la source du FROM et demande un alias. Son premier argument est le texte de la requête, sous forme de chaîne ou de paramètre ; les arguments nommés suivent avec =>.

SELECT v.id, v._score, title
FROM vector_top_k('replicated state machines', k => 5) AS v

SELECT b.id, b._score
FROM bm25_top_k('keyword search', k => 3) AS b
WHERE b.year > 2000

SELECT h.id, h._score
FROM hybrid_top_k($q, k => 10) AS h
ORDER BY h._score DESC
FonctionDemande_score
vector_top_kUn embedder ; accepte aussi ef_search1 moins la distance ; _distance est aussi disponible
bm25_top_kUn backend BM25Le score BM25
hybrid_top_kUn embedder et un backend BM25La valeur RRF fusionnée
  • k est un entier d’au moins 1, 10 par défaut.
  • La fonction récupère plus de résultats que demandé (3 fois k par défaut, 1000 au plus ; l’option overfetch de barrel:query/3 le change), joint chaque résultat à son document, applique WHERE, et renvoie jusqu’à k lignes. Un filtre sélectif peut en renvoyer moins.
  • _score et _distance peuvent être sélectionnés ou triés, jamais filtrés dans WHERE.

Requêtes en direct

Ajoutez SUBSCRIBE pour recevoir les lignes qui correspondent, puis un message pour chaque ligne ajoutée, modifiée ou sortante.

{ok, #{ref := Ref}} = barrel:subscribe_query(Db,
    <<"SELECT title FROM kb WHERE status = 'published' "
      "SUBSCRIBE">>).

Le propriétaire reçoit {bql_rows, Ref, Rows}, {bql_ready, Ref, #{count, last_seq}}, puis {bql_change, Ref, #{action, id, rev, row}} où action vaut add, change ou remove. SUBSCRIBE ne se combine pas avec une fonction de table, UNNEST, ORDER BY ou OFFSET.

Pagination

Les requêtes sans ORDER BY, UNNEST ni LIMIT sont diffusées en flux : passez chunk_size, puis la continuation des métadonnées du résultat pour obtenir le bloc suivant. Les métadonnées portent has_more, instance_id, last_seq, et count quand la requête est matérialisée.

Instructions refusées

Celles-ci ne figurent pas du tout dans la grammaire, ce sont donc des erreurs de syntaxe : les agrégats comme COUNT(*), GROUP BY, les jointures, DISTINCT, les sous-requêtes et les fonctions dans la liste de sélection.

Le compilateur refuse celles-ci avec {error, {invalid_query, {Line, Col}, Code}} :

CodeInstruction
{unsupported, wildcard_path, use_unnest}Un chemin [*] ; utilisez UNNEST
{unsupported, multi_key_order_by}ORDER BY avec plus d’une clé
{unsupported, id_in_disjunction}, {unsupported, id_condition}Une condition sur id à l’intérieur d’un OR, ou autre que =, un intervalle ou un LIKE par préfixe
score_in_where_score ou _distance dans WHERE
path_to_path_comparison, path_between_boundLa comparaison de deux champs
{use_is_null, _}= NULL ; utilisez IS NULL
constant_predicateUn prédicat sans champ
{reserved_field, F}Un champ _ de premier niveau, comme _rev
{unbound_param, N}, {invalid_param, N}Un paramètre manquant ou non scalaire
{alias_required, _}Une fonction de table ou une projection indexée sans AS
duplicate_alias, duplicate_output_nameDeux noms qui entrent en collision
unknown_table_function, invalid_table_fn_argUne fonction de table ou un argument invalide
invalid_unnest_path, invalid_order_keyUn chemin UNNEST ou une clé ORDER BY invalide
{unsupported_with_subscribe, _}SUBSCRIBE avec une fonction de table, UNNEST, ORDER BY ou OFFSET

barrel_bql:format_error/1 transforme une erreur en texte renvoyé par REST, comme line 1 column 13: syntax error: syntax error before: '('.

Traduit de la page anglaise: /docs/reference/bql/ Modifier cette page Voir en Markdown

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