Skip to main content

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}