evalhub_query/ir.rs
1//! The backend-independent query tree.
2//!
3//! [`Query`] is what the type check produces and what
4//! `evalhub_store::query_sql` consumes. Every path in it has been resolved
5//! to a [`Column`] that names *where* the value lives (a generated column, a
6//! fingerprint row, a side table, a JSON expression) so the SQL compiler
7//! needs no knowledge of the schema — it only needs to know how to render
8//! each `Column` kind. That split keeps the SQL compiler small and keeps
9//! this crate free of SQL.
10//!
11//! ```text
12//! Query { record_type, filter, sort, limit, cursor, expand, version }
13//! Filter := And(Vec) | Or(Vec) | Not(Box) | Cmp { column, op, value }
14//! | Exists { column } | Any { table, conditions: Vec<Cmp> }
15//! Column := Generated(name) | Fingerprint(facet) | Ext { path, ty } | Body(json_path)
16//! Cursor := { keys: Vec<Value>, version_id } // decoded; encoding is the server's
17//! ```
18//!
19//! The IR is `serde`-serialisable so a query can be snapshot-tested end to
20//! end: JSON in, IR out, without a database.
21//!
22//! # Why the column kinds are closed
23//!
24//! Each variant of [`Column`] corresponds to one storage decision made in
25//! the migration: a generated column, the `fingerprints` table, an
26//! expression index over a registered `ext` path, or the GIN index over the
27//! whole body. A path the type check cannot place in one of them is not a
28//! query the hub can serve, and saying so (`422 not_indexed`) is better
29//! than a sequential scan that looks like a feature until the table grows.
30//!
31//! # Values
32//!
33//! Literals travel as `serde_json::Value` and are bound as parameters, never
34//! rendered into SQL text. The type check has already confirmed that a
35//! literal matches its column's type, so the compiler binds by
36//! [`ValueType`] rather than by inspecting the JSON again.
37
38use serde::{Deserialize, Serialize};
39use serde_json::Value;
40
41/// A checked, resolved query ready for a backend to compile.
42#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
43pub struct Query {
44 /// Which record kind is being searched. The compiler adds
45 /// `records.type = …`.
46 pub record_type: RecordType,
47 /// The predicate. `None` matches every visible record.
48 pub filter: Option<Filter>,
49 /// Sort keys, most significant first. Empty means the backend's
50 /// default order (newest version first).
51 pub sort: Vec<Sort>,
52 /// Page size the caller asked for, already clamped by the server.
53 pub limit: u32,
54 /// Where the previous page stopped, decoded and verified by the server.
55 pub cursor: Option<Cursor>,
56 /// What to include alongside each record.
57 pub expand: Vec<Expand>,
58 /// Whether to consider every version or only the latest live one.
59 pub version: VersionSelector,
60}
61
62/// The record kind a query searches.
63#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
64#[serde(rename_all = "snake_case")]
65pub enum RecordType {
66 /// Cards: what was measured, how, and what the score was.
67 Card,
68 /// Evals: the material a Card was measured from.
69 Eval,
70}
71
72/// Which versions a query considers.
73#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
74#[serde(rename_all = "snake_case")]
75pub enum VersionSelector {
76 /// Only the highest non-tombstoned `seq` of each name.
77 #[default]
78 Latest,
79 /// Every non-tombstoned version.
80 All,
81}
82
83/// What to include alongside each matched record.
84#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
85#[serde(rename_all = "snake_case")]
86pub enum Expand {
87 /// The version's outgoing relations.
88 Relations,
89 /// The badges awarded at ingest.
90 Badges,
91 /// The seven per-facet fingerprints.
92 Fingerprints,
93 /// The top-level keys that differ from the previous version.
94 Changed,
95}
96
97/// The predicate tree. `And`/`Or` with no children are the identity of
98/// their operation, which is what an empty `{"and": []}` means.
99#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
100#[serde(rename_all = "snake_case")]
101pub enum Filter {
102 /// Every child must match.
103 And(Vec<Filter>),
104 /// At least one child must match.
105 Or(Vec<Filter>),
106 /// The child must not match.
107 Not(Box<Filter>),
108 /// A scalar comparison against one column.
109 Cmp(Cmp),
110 /// The column has a value, `null` included.
111 Exists {
112 /// Where the value lives.
113 column: Column,
114 },
115 /// At least one row of a side table satisfies every condition.
116 Any {
117 /// The table to look in.
118 table: ArrayTable,
119 /// Conditions on that table's columns; all must hold of one row.
120 conditions: Vec<Cmp>,
121 },
122}
123
124/// One scalar comparison.
125#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
126pub struct Cmp {
127 /// Where the value lives.
128 pub column: Column,
129 /// How to compare.
130 pub op: Op,
131 /// What to compare against. `In` carries an array; every other
132 /// operator carries a scalar.
133 pub value: Value,
134}
135
136/// The comparison operators, after the type check has confirmed each one
137/// suits its column.
138#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
139#[serde(rename_all = "snake_case")]
140pub enum Op {
141 /// Equal.
142 Eq,
143 /// Not equal.
144 Ne,
145 /// Greater than.
146 Gt,
147 /// Greater than or equal.
148 Gte,
149 /// Less than.
150 Lt,
151 /// Less than or equal.
152 Lte,
153 /// One of a list.
154 In,
155 /// Starts with (strings).
156 Prefix,
157 /// Contains (strings).
158 Contains,
159}
160
161/// A side table an `any` condition ranges over. Each has its own columns,
162/// listed in [`ArrayColumn`].
163#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
164#[serde(rename_all = "snake_case")]
165pub enum ArrayTable {
166 /// `results (metric, aggregation, value, n)`.
167 Results,
168 /// `relations (type, to_version_id, to_external)`.
169 Relations,
170 /// `attachment_refs (path, sha256)`.
171 Attachments,
172}
173
174/// Where a value lives, in terms the storage layer can render directly.
175#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
176#[serde(rename_all = "snake_case")]
177pub enum Column {
178 /// A generated column on `versions`, named by the migration.
179 Generated(String),
180 /// A facet's fingerprint, matched against the `fingerprints` table.
181 Fingerprint(String),
182 /// A registered `ext` path, served by an expression index. The
183 /// compiler must render the *same* expression text the index was
184 /// created with, which is why the path and the type travel together.
185 Ext {
186 /// JSON path segments below the document root, `ext` included.
187 path: Vec<String>,
188 /// The registered type, which picks the cast helper.
189 ty: ValueType,
190 },
191 /// Any other path, served by the GIN index over the whole body.
192 /// Only equality and existence are allowed here, which is what that
193 /// index answers.
194 Body(Vec<String>),
195 /// A column of the side table an `any` condition ranges over.
196 Array(ArrayColumn),
197}
198
199/// The columns an `any` condition may compare, one set per table.
200#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
201#[serde(rename_all = "snake_case")]
202pub enum ArrayColumn {
203 /// `results.metric`
204 ResultMetric,
205 /// `results.aggregation`
206 ResultAggregation,
207 /// `results.value`
208 ResultValue,
209 /// `results.n`
210 ResultN,
211 /// `relations.type`
212 RelationType,
213 /// The relation's target, resolved or textual.
214 RelationTo,
215 /// `attachment_refs.path`
216 AttachmentPath,
217 /// `attachment_refs.sha256`
218 AttachmentSha256,
219}
220
221impl ArrayColumn {
222 /// The table this column belongs to, so a compiler can reject a
223 /// condition that strayed into another one.
224 pub fn table(self) -> ArrayTable {
225 match self {
226 Self::ResultMetric | Self::ResultAggregation | Self::ResultValue | Self::ResultN => {
227 ArrayTable::Results
228 }
229 Self::RelationType | Self::RelationTo => ArrayTable::Relations,
230 Self::AttachmentPath | Self::AttachmentSha256 => ArrayTable::Attachments,
231 }
232 }
233}
234
235/// The scalar types the query language distinguishes. They decide the cast
236/// helper for an `ext` path and the binding a literal gets.
237#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
238#[serde(rename_all = "snake_case")]
239pub enum ValueType {
240 /// IEEE 754 double, as every JSON number is.
241 Number,
242 /// UTF-8 text.
243 String,
244 /// `true` or `false`.
245 Boolean,
246}
247
248/// One sort key.
249#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
250pub struct Sort {
251 /// What to sort by.
252 pub key: SortKey,
253 /// Which way.
254 pub dir: Dir,
255}
256
257/// What a sort orders by.
258#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
259#[serde(rename_all = "snake_case")]
260pub enum SortKey {
261 /// A column of `versions`, or a registered `ext` path.
262 Column(Column),
263 /// The value of one metric, which is a lateral join on `results`.
264 Metric(String),
265 /// When the version was stored.
266 CreatedAt,
267}
268
269/// Sort direction.
270#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
271#[serde(rename_all = "snake_case")]
272pub enum Dir {
273 /// Smallest first.
274 Asc,
275 /// Largest first.
276 Desc,
277}
278
279/// Where the previous page stopped: the sort keys of its last row and that
280/// row's `version_id`, which breaks ties and makes the tuple unique.
281///
282/// The server signs and encodes this; the store only compares against it.
283#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
284pub struct Cursor {
285 /// One value per entry of [`Query::sort`], in the same order.
286 pub keys: Vec<Value>,
287 /// The last row's version id.
288 pub version_id: uuid::Uuid,
289}