Skip to main content

evalhub_query/
grammar.rs

1//! The `dsl-kit` grammar of a query and the parser derived from it.
2//!
3//! ```text
4//! query   := { where?: filter, sort?: [sort], limit?: int, cursor?: string,
5//!              expand?: [expand], version?: "latest" | "all" }
6//! filter  := { and: [filter+] } | { or: [filter+] } | { not: filter } | leaf
7//! leaf    := { path, op: scalar_op, value }
8//!          | { path, op: "exists" }
9//!          | { path, op: "any", match: { key: (value | { op, value }) ... } }
10//! scalar_op := eq | ne | gt | gte | lt | lte | in | prefix | contains
11//! sort    := { path, dir: "asc" | "desc" }
12//! expand  := relations | badges | fingerprints | changed
13//! ```
14//!
15//! The filter AST is declared once, as the `dsl-kit` enum [`Filter`], and
16//! from it come the conformance check, the typed builder, and the JSON
17//! Schema of the `where` value that `evalhub_schema::query` leaves open.
18//! `path` is a string at this stage; its meaning is assigned in
19//! [`crate::typecheck`].
20//!
21//! `any` with `match` is the one non-trivial construct. It applies to the
22//! array paths of a record (`results`, `relations`, `attachments`) and
23//! matches if any element satisfies every key in `match`; a key's value is
24//! either a literal (implicit `eq`) or `{ op, value }`. This is how
25//! `results` is filtered by metric and value at once without exposing array
26//! indices. An Eval's runs are not an array path: they are rows of their
27//! own, read through the run projection, whose table has no array paths
28//! (see [`crate::typecheck`]).
29//!
30//! The grammar is the same for both targets, record queries and the run
31//! projection; only the path table a request is checked against differs.
32//!
33//! # Two shapes of vocabulary, and which one is hand-written
34//!
35//! `dsl-kit`'s JSON front end reads the internally-tagged convention
36//! (`{"type": "And", "children": […]}`), while the wire format above is
37//! key-tagged (`{"and": […]}`). [`parse`] therefore lowers the wire JSON
38//! into the tagged shape before handing it to
39//! `dsl_kit_parse::serde_bridge`, and the lowering is the only place in the
40//! workspace that names a construct by hand. It distinguishes exactly five
41//! shapes — `and`, `or`, `not`, and the two leaf forms that carry no scalar
42//! value (`exists`, `any`) — because each is a different *node shape*, and
43//! a node shape is what a `dsl-kit` variant is.
44//!
45//! The **operator vocabulary** is not hand-written anywhere: `op` is a
46//! payload field of type [`ScalarOp`], which the derived builder
47//! deserialises through `serde`. Adding `matches` or `between` to the
48//! language is one variant on that enum plus its row in the type table;
49//! no parser arm changes. That is the property the crate doc claims, and
50//! it is worth stating precisely rather than loosely, because the looser
51//! claim ("no hand-written match anywhere") is not true of the lowering.
52//!
53//! # Why the payloads are `serde_json::Value`
54//!
55//! A leaf's `value` is any JSON scalar (or an array, for `in`), and a
56//! `match` term's value likewise. `dsl-kit` payload fields convert through
57//! `serde`, so [`serde_json::Value`] is a legal field type and keeps the
58//! grammar honest about what it does *not* decide: whether `0.2` suits
59//! `generation.temperature` is a question for the type check, which has the
60//! schema. The grammar's job is shape.
61
62use std::collections::BTreeMap;
63use std::fmt;
64use std::str::FromStr;
65
66use dsl_kit_core::{IdGen, NodeId};
67use dsl_kit_macros::{DslBuild, DslNode, DslSchema};
68use dsl_kit_parse::DslBuild as _;
69use dsl_kit_parse::serde_bridge;
70use dsl_kit_schema::DslSchema as _;
71use evalhub_schema::error::{ErrorCode, ErrorEntry};
72use serde::{Deserialize, Serialize};
73use serde_json::{Map, Value, json};
74
75/// The filter AST: what a `where` clause means, before any path has been
76/// given a meaning.
77///
78/// Every variant carries the `id: NodeId` that `dsl-kit` mints, which is
79/// what lets a diagnostic point at a node rather than at a byte range.
80#[derive(Debug, Clone, PartialEq, DslNode, DslSchema, DslBuild)]
81pub enum Filter {
82    /// Every child must match. `{"and": [...]}`.
83    And {
84        /// Node identity, minted by the builder.
85        id: NodeId,
86        /// The conjuncts.
87        children: Vec<Filter>,
88    },
89    /// At least one child must match. `{"or": [...]}`.
90    Or {
91        /// Node identity, minted by the builder.
92        id: NodeId,
93        /// The disjuncts.
94        children: Vec<Filter>,
95    },
96    /// The child must not match. `{"not": {...}}`.
97    Not {
98        /// Node identity, minted by the builder.
99        id: NodeId,
100        /// The negated filter.
101        child: Box<Filter>,
102    },
103    /// A scalar comparison. `{"path": …, "op": …, "value": …}`.
104    Compare {
105        /// Node identity, minted by the builder.
106        id: NodeId,
107        /// The query path, uninterpreted here.
108        path: String,
109        /// The operator.
110        op: ScalarOp,
111        /// The literal to compare against; an array for `in`.
112        value: Value,
113    },
114    /// The path has a value, `null` included. `{"path": …, "op": "exists"}`.
115    Exists {
116        /// Node identity, minted by the builder.
117        id: NodeId,
118        /// The query path, uninterpreted here.
119        path: String,
120    },
121    /// At least one element of an array path satisfies every term.
122    /// `{"path": …, "op": "any", "match": {…}}`.
123    Any {
124        /// Node identity, minted by the builder.
125        id: NodeId,
126        /// The array path, uninterpreted here.
127        path: String,
128        /// The terms, keyed by the element field they constrain.
129        terms: BTreeMap<String, MatchTerm>,
130    },
131}
132
133/// The scalar operators, declared once.
134///
135/// This enum *is* the operator vocabulary: the builder deserialises `op`
136/// into it, [`request_schema`] lists its spellings in the published JSON
137/// Schema, and [`crate::typecheck`] decides which types each one suits.
138#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
139#[serde(rename_all = "snake_case")]
140pub enum ScalarOp {
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.
156    Prefix,
157    /// Contains.
158    Contains,
159}
160
161impl ScalarOp {
162    /// Every operator, in declaration order. Used to publish the
163    /// vocabulary without a second list.
164    pub const ALL: [ScalarOp; 9] = [
165        ScalarOp::Eq,
166        ScalarOp::Ne,
167        ScalarOp::Gt,
168        ScalarOp::Gte,
169        ScalarOp::Lt,
170        ScalarOp::Lte,
171        ScalarOp::In,
172        ScalarOp::Prefix,
173        ScalarOp::Contains,
174    ];
175
176    /// The wire spelling.
177    pub const fn as_str(self) -> &'static str {
178        match self {
179            ScalarOp::Eq => "eq",
180            ScalarOp::Ne => "ne",
181            ScalarOp::Gt => "gt",
182            ScalarOp::Gte => "gte",
183            ScalarOp::Lt => "lt",
184            ScalarOp::Lte => "lte",
185            ScalarOp::In => "in",
186            ScalarOp::Prefix => "prefix",
187            ScalarOp::Contains => "contains",
188        }
189    }
190}
191
192impl fmt::Display for ScalarOp {
193    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
194        f.write_str(self.as_str())
195    }
196}
197
198impl FromStr for ScalarOp {
199    type Err = UnknownOperator;
200
201    fn from_str(s: &str) -> Result<Self, Self::Err> {
202        ScalarOp::ALL
203            .into_iter()
204            .find(|op| op.as_str() == s)
205            .ok_or_else(|| UnknownOperator(s.to_string()))
206    }
207}
208
209/// A spelling that names no operator.
210#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
211#[error("unknown operator `{0}`")]
212pub struct UnknownOperator(pub String);
213
214/// One term of an `any` match: an operator (`eq` when the wire form was a
215/// bare literal) and the value to compare against.
216#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
217#[serde(deny_unknown_fields)]
218pub struct MatchTerm {
219    /// How to compare. Absent on the wire means `eq`.
220    #[serde(default = "MatchTerm::default_op")]
221    pub op: ScalarOp,
222    /// The literal to compare against.
223    pub value: Value,
224}
225
226impl MatchTerm {
227    const fn default_op() -> ScalarOp {
228        ScalarOp::Eq
229    }
230}
231
232impl FromStr for MatchTerm {
233    type Err = serde_json::Error;
234
235    /// Present so the term satisfies `dsl-kit`'s payload bound, which asks
236    /// for both `serde` and `FromStr` so the JSON and canonical-text front
237    /// ends cannot diverge. evalhub only uses the JSON one.
238    fn from_str(s: &str) -> Result<Self, Self::Err> {
239        serde_json::from_str(s)
240    }
241}
242
243/// The operators that change a leaf's *shape* rather than its comparison,
244/// and therefore name a `dsl-kit` variant instead of a [`ScalarOp`].
245const EXISTS_OP: &str = "exists";
246/// See [`EXISTS_OP`].
247const ANY_OP: &str = "any";
248
249/// Parse a `where` value into the filter AST.
250///
251/// Returns every structural problem it found, not just the first: a
252/// caller fixing a query should see the whole bag. Paths in the returned
253/// entries are JSON pointers into the *request* (`/where/and/1/op`), which
254/// this function tracks itself — `dsl-kit`'s JSON front end reports no
255/// position, because it reads a [`serde_json::Value`] and there is no byte
256/// offset left to report by then.
257pub fn parse(value: &Value) -> Result<Filter, Vec<ErrorEntry>> {
258    let mut errors = Vec::new();
259    let tagged = lower(value, "/where", &mut errors);
260    if !errors.is_empty() {
261        return Err(errors);
262    }
263
264    let schema = Filter::schema();
265    let tree = serde_bridge::from_json_value(&tagged, &schema)
266        .map_err(|e| diagnostics_to_entries(&e, "/where"))?;
267    Filter::from_parse_tree(&tree, &IdGen::new()).map_err(|e| diagnostics_to_entries(&e, "/where"))
268}
269
270/// Turn `dsl-kit` diagnostics into error entries. The location is always
271/// the clause as a whole, for the reason given on [`parse`]; the code is
272/// `schema`, because every one of them is a shape violation.
273fn diagnostics_to_entries(error: &dsl_kit_parse::BuildError, pointer: &str) -> Vec<ErrorEntry> {
274    error
275        .diagnostics
276        .iter()
277        .map(|d| ErrorEntry {
278            path: pointer.to_string(),
279            code: ErrorCode::Schema,
280            hint: Some(d.message.clone()),
281        })
282        .collect()
283}
284
285fn shape_error(pointer: &str, hint: impl Into<String>) -> ErrorEntry {
286    ErrorEntry {
287        path: pointer.to_string(),
288        code: ErrorCode::Schema,
289        hint: Some(hint.into()),
290    }
291}
292
293/// Lower one wire-shaped filter into `dsl-kit`'s tagged convention,
294/// recording shape problems against their JSON pointer.
295///
296/// On error the returned value is a placeholder; [`parse`] checks the
297/// error list before looking at it.
298fn lower(value: &Value, pointer: &str, errors: &mut Vec<ErrorEntry>) -> Value {
299    let Some(object) = value.as_object() else {
300        errors.push(shape_error(
301            pointer,
302            "a filter is an object: {\"and\": [...]}, {\"or\": [...]}, {\"not\": {...}} \
303             or {\"path\": ..., \"op\": ..., \"value\": ...}",
304        ));
305        return Value::Null;
306    };
307
308    // The three connectives are keyed by their name.
309    for (key, variant) in [("and", "And"), ("or", "Or")] {
310        if let Some(children) = object.get(key) {
311            if object.len() > 1 {
312                errors.push(shape_error(
313                    pointer,
314                    format!("`{key}` is the only key a `{key}` filter may carry"),
315                ));
316                return Value::Null;
317            }
318            let Some(items) = children.as_array() else {
319                errors.push(shape_error(
320                    &format!("{pointer}/{key}"),
321                    format!("`{key}` takes an array of filters"),
322                ));
323                return Value::Null;
324            };
325            let lowered: Vec<Value> = items
326                .iter()
327                .enumerate()
328                .map(|(i, child)| lower(child, &format!("{pointer}/{key}/{i}"), errors))
329                .collect();
330            return json!({ "type": variant, "children": lowered });
331        }
332    }
333    if let Some(child) = object.get("not") {
334        if object.len() > 1 {
335            errors.push(shape_error(
336                pointer,
337                "`not` is the only key a `not` filter may carry",
338            ));
339            return Value::Null;
340        }
341        let lowered = lower(child, &format!("{pointer}/not"), errors);
342        return json!({ "type": "Not", "child": lowered });
343    }
344
345    lower_leaf(object, pointer, errors)
346}
347
348fn lower_leaf(object: &Map<String, Value>, pointer: &str, errors: &mut Vec<ErrorEntry>) -> Value {
349    let Some(path) = object.get("path") else {
350        errors.push(shape_error(
351            pointer,
352            "a leaf filter needs a `path`; a connective needs `and`, `or` or `not`",
353        ));
354        return Value::Null;
355    };
356    let Some(path) = path.as_str() else {
357        errors.push(shape_error(
358            &format!("{pointer}/path"),
359            "`path` is a string",
360        ));
361        return Value::Null;
362    };
363    let Some(op) = object.get("op") else {
364        errors.push(shape_error(
365            pointer,
366            format!(
367                "a leaf filter needs an `op`: one of {}, `{EXISTS_OP}` or `{ANY_OP}`",
368                operator_list()
369            ),
370        ));
371        return Value::Null;
372    };
373    let Some(op) = op.as_str() else {
374        errors.push(shape_error(&format!("{pointer}/op"), "`op` is a string"));
375        return Value::Null;
376    };
377
378    match op {
379        EXISTS_OP => {
380            reject_extra_keys(object, &["path", "op"], pointer, errors);
381            json!({ "type": "Exists", "path": path })
382        }
383        ANY_OP => {
384            reject_extra_keys(object, &["path", "op", "match"], pointer, errors);
385            let Some(terms) = object.get("match") else {
386                errors.push(shape_error(
387                    pointer,
388                    "`any` needs a `match` object naming the element fields to constrain",
389                ));
390                return Value::Null;
391            };
392            let Some(terms) = terms.as_object() else {
393                errors.push(shape_error(
394                    &format!("{pointer}/match"),
395                    "`match` is an object",
396                ));
397                return Value::Null;
398            };
399            let lowered: Map<String, Value> = terms
400                .iter()
401                .map(|(key, term)| {
402                    (
403                        key.clone(),
404                        lower_term(term, &format!("{pointer}/match/{key}"), errors),
405                    )
406                })
407                .collect();
408            json!({ "type": "Any", "path": path, "terms": lowered })
409        }
410        _ => {
411            reject_extra_keys(object, &["path", "op", "value"], pointer, errors);
412            let Some(value) = object.get("value") else {
413                errors.push(shape_error(
414                    pointer,
415                    format!("`{op}` needs a `value`; only `{EXISTS_OP}` stands alone"),
416                ));
417                return Value::Null;
418            };
419            json!({ "type": "Compare", "path": path, "op": op, "value": value })
420        }
421    }
422}
423
424/// A `match` term is either a bare literal (meaning `eq`) or
425/// `{ op, value }`. Both are lowered to the explicit form, which is what
426/// [`MatchTerm`] deserialises from; `dsl-kit` hands each entry of a keyed
427/// scalar slot to `serde` verbatim.
428fn lower_term(term: &Value, pointer: &str, errors: &mut Vec<ErrorEntry>) -> Value {
429    match term.as_object() {
430        Some(object) if object.contains_key("op") || object.contains_key("value") => {
431            reject_extra_keys(object, &["op", "value"], pointer, errors);
432            if !object.contains_key("value") {
433                errors.push(shape_error(
434                    pointer,
435                    "a match term with an `op` also needs a `value`",
436                ));
437                return Value::Null;
438            }
439            json!({
440                "op": object.get("op").cloned().unwrap_or_else(|| json!("eq")),
441                "value": object.get("value"),
442            })
443        }
444        // Any other value — including an object that is plainly a literal —
445        // is the implicit-`eq` form.
446        _ => json!({ "op": "eq", "value": term }),
447    }
448}
449
450fn reject_extra_keys(
451    object: &Map<String, Value>,
452    allowed: &[&str],
453    pointer: &str,
454    errors: &mut Vec<ErrorEntry>,
455) {
456    for key in object.keys() {
457        if !allowed.contains(&key.as_str()) {
458            errors.push(shape_error(
459                &format!("{pointer}/{key}"),
460                format!("unknown key `{key}`; this filter takes {}", list(allowed)),
461            ));
462        }
463    }
464}
465
466fn list(items: &[&str]) -> String {
467    items
468        .iter()
469        .map(|i| format!("`{i}`"))
470        .collect::<Vec<_>>()
471        .join(", ")
472}
473
474fn operator_list() -> String {
475    ScalarOp::ALL
476        .iter()
477        .map(|op| format!("`{op}`"))
478        .collect::<Vec<_>>()
479        .join(", ")
480}
481
482/// The wire key a connective is spelled with, so that the type check can
483/// rebuild the JSON pointer of a nested filter without a second table of
484/// shape names. Leaves have no key of their own: they sit where their
485/// parent put them.
486pub(crate) fn wire_key(filter: &Filter) -> &'static str {
487    match filter {
488        Filter::And { .. } => "and",
489        Filter::Or { .. } => "or",
490        Filter::Not { .. } => "not",
491        Filter::Compare { .. } | Filter::Exists { .. } | Filter::Any { .. } => "",
492    }
493}
494
495/// The JSON Schema of a `where` value, for the OpenAPI document.
496///
497/// `evalhub_schema::query::QueryRequest` leaves `where` open because the
498/// filter's shape belongs to this crate; the server splices this schema in
499/// so a generated client sees the real thing.
500///
501/// The schema describes the *wire* shape, which is the inverse of the
502/// lowering in [`parse`]: `dsl-kit`'s [`dsl_kit_schema::NodeSchema`]
503/// describes the tagged shape, so it is read for the variant and field
504/// names rather than copied. What it cannot express is carried here
505/// instead: which keys pair with which operator. The operator list comes
506/// from [`ScalarOp::ALL`], so the published vocabulary cannot drift from
507/// the one the parser accepts.
508pub fn request_schema() -> schemars::Schema {
509    let node = Filter::schema();
510    // Read the leaf field names off the declared schema rather than
511    // spelling them again; if a variant is renamed the schema follows.
512    let compare = node
513        .variant("Compare")
514        .map(|v| v.fields.iter().map(|f| f.name.clone()).collect::<Vec<_>>())
515        .unwrap_or_default();
516    let path_key = compare
517        .iter()
518        .find(|f| *f == "path")
519        .cloned()
520        .unwrap_or_else(|| "path".to_string());
521    let value_key = compare
522        .iter()
523        .find(|f| *f == "value")
524        .cloned()
525        .unwrap_or_else(|| "value".to_string());
526    let ops: Vec<Value> = ScalarOp::ALL.iter().map(|op| json!(op.as_str())).collect();
527
528    let filter_ref = json!({ "$ref": "#/$defs/filter" });
529    let term = json!({
530        "description": "A literal (meaning `eq`), or an operator and a literal.",
531        "oneOf": [
532            { "type": ["string", "number", "boolean", "null"] },
533            {
534                "type": "object",
535                "properties": {
536                    "op": { "enum": ops.clone() },
537                    &value_key: true,
538                },
539                "required": [&value_key],
540                "additionalProperties": false,
541            },
542        ],
543    });
544
545    let document = json!({
546        "$ref": "#/$defs/filter",
547        "$defs": {
548            "filter": {
549                "description": "A filter: a connective or a leaf.",
550                "oneOf": [
551                    {
552                        "type": "object",
553                        "properties": { "and": { "type": "array", "items": filter_ref } },
554                        "required": ["and"],
555                        "additionalProperties": false,
556                    },
557                    {
558                        "type": "object",
559                        "properties": { "or": { "type": "array", "items": filter_ref } },
560                        "required": ["or"],
561                        "additionalProperties": false,
562                    },
563                    {
564                        "type": "object",
565                        "properties": { "not": filter_ref },
566                        "required": ["not"],
567                        "additionalProperties": false,
568                    },
569                    {
570                        "description": "A scalar comparison.",
571                        "type": "object",
572                        "properties": {
573                            &path_key: { "type": "string" },
574                            "op": { "enum": ops },
575                            &value_key: true,
576                        },
577                        "required": [&path_key, "op", &value_key],
578                        "additionalProperties": false,
579                    },
580                    {
581                        "description": "The path has a value, `null` included.",
582                        "type": "object",
583                        "properties": {
584                            &path_key: { "type": "string" },
585                            "op": { "const": EXISTS_OP },
586                        },
587                        "required": [&path_key, "op"],
588                        "additionalProperties": false,
589                    },
590                    {
591                        "description": "At least one element of an array path satisfies every term.",
592                        "type": "object",
593                        "properties": {
594                            &path_key: { "type": "string" },
595                            "op": { "const": ANY_OP },
596                            "match": { "type": "object", "additionalProperties": term },
597                        },
598                        "required": [&path_key, "op", "match"],
599                        "additionalProperties": false,
600                    },
601                ],
602            },
603        },
604    });
605    // `json!` of an object literal is always an object, and schemars builds
606    // a schema from one directly.
607    match document {
608        Value::Object(map) => schemars::Schema::from(map),
609        _ => schemars::Schema::default(),
610    }
611}