relate_parser/ast/search.rs
1//! The `SEARCH` clause nodes.
2
3use super::*;
4
5/// `<search clause>`: the `SEARCH ... IN (<source specification
6/// clause>) [SCORE AS ...]` subclause of `MatchClause`.
7///
8/// `binding_var`/`score_var` (and each nested `index_name`) are plain
9/// identifiers (never a general expression, a parameter, or a property
10/// access -- Rules 1, 4, 5) rather than `Expr`, matching the grammar's own
11/// `<binding variable reference>` / `<index name specification>` /
12/// `<binding variable>` productions.
13#[derive(Debug, Clone, PartialEq)]
14pub struct SearchClause {
15 /// `<binding variable reference>`: must name a variable declared by the
16 /// same `<match statement>`'s own pattern.
17 pub binding_var: SmallName,
18 /// `<source specification clause>`: one index search, or a
19 /// `COMBINE` of two or more weighted sources fused with WRRF.
20 pub spec: SearchSpec,
21 /// `[SCORE AS <binding variable>]` -- `None` when the score column is
22 /// omitted (results are still ordered by descending score either way).
23 pub score_var: Option<SmallName>,
24}
25
26/// `<source specification clause>`:
27/// `<index specification clause> | <combined specification clause>`.
28#[derive(Debug, Clone, PartialEq)]
29pub enum SearchSpec {
30 Index(SearchIndexSpec),
31 Combine(SearchCombineSpec),
32}
33
34/// `<index specification clause>`: `{ VECTOR | FULLTEXT } INDEX
35/// <index name> <index for and control clause>`.
36#[derive(Debug, Clone, PartialEq)]
37pub struct SearchIndexSpec {
38 /// CIP-225: which index kind the specification names.
39 pub kind: SearchKind,
40 /// `<index name specification>`: the literal name of an existing index.
41 pub index_name: SmallName,
42 /// `<for clause>`'s `<value expression>` -- the search query.
43 pub for_expr: Expr,
44 /// `WITH ANALYZER <expr>` (fulltext only).
45 pub analyzer: Option<Expr>,
46 /// CIP-240 "Vector Search with Single-stage Filtering": the optional
47 /// inner `WHERE <search condition>` between `FOR <expr>` and `LIMIT
48 /// <expr>`. Its `<search condition>` must decompose into one or more
49 /// `<binding variable reference> <static property reference> <simple
50 /// comp op> <arithmetic value expression>` predicates joined by `AND`
51 /// (or a form rewritable into that, e.g. `NOT x.prop` or flipped
52 /// operands) -- enforced by `relate_front::search_filter`, not here;
53 /// the parser accepts any general `<expression>` here, exactly like
54 /// `MatchClause.where_expr`.
55 pub inner_where: Option<Expr>,
56 /// `<offset clause>` (`SKIP`/`OFFSET`).
57 pub offset_expr: Option<Expr>,
58 /// `<limit clause>`'s `<value expression>` (mandatory for an index
59 /// source, in and out of a COMBINE).
60 pub limit_expr: Expr,
61}
62
63/// `<index specification clause>`: `{ VECTOR | FULLTEXT } INDEX`.
64#[derive(Debug, Clone, Copy, PartialEq, Eq)]
65pub enum SearchKind {
66 Vector,
67 Fulltext,
68}
69
70/// `<combined specification clause>`: `COMBINE ( <weighted source
71/// clause>, ... ) USING WRRF [ WITH CONSTANT <expr> ] [ LIMIT <expr> ]`.
72///
73/// `sources` holds two or more weighted source clauses (fewer is a
74/// parse error, raised where the list is parsed). A source may itself be a
75/// nested `<combined specification clause>`.
76#[derive(Debug, Clone, PartialEq)]
77pub struct SearchCombineSpec {
78 pub sources: Vec<SearchWeightedSource>,
79 /// `<constant specification clause>`'s `<value expression>` -- the WRRF
80 /// dampening constant; `None` means the default 60.
81 pub constant_expr: Option<Expr>,
82 /// The optional `<limit clause>` of the combined specification -- the n
83 /// highest-scoring results kept; `None` keeps all.
84 pub limit_expr: Option<Expr>,
85}
86
87/// `<weighted source clause>`:
88/// `<source specification clause> [ WEIGHT <value expression> ]`.
89#[derive(Debug, Clone, PartialEq)]
90pub struct SearchWeightedSource {
91 pub spec: SearchSpec,
92 /// `None` means the default weight 1.
93 pub weight_expr: Option<Expr>,
94}