Skip to main content

evalhub_schema/
query.rs

1//! The query request and response envelope.
2//!
3//! The grammar of a query, its type rules, and its compilation live in
4//! `evalhub_query`; this module holds only the JSON shape that crosses the
5//! wire, so that it appears in the OpenAPI document next to the records.
6//!
7//! ```text
8//! POST /cards/query   (or /evals/query)
9//! {
10//!   "where":   <filter>,                 // and / or / not / leaf
11//!   "sort":    [{ "path": "...", "dir": "asc" | "desc" }],
12//!   "limit":   50,
13//!   "cursor":  null | "<opaque>",
14//!   "expand":  ["relations", "badges", "fingerprints", "changed"],
15//!   "version": "latest" | "all"
16//! }
17//! ```
18//!
19//! A leaf is `{ path, op, value }` or, for array fields, `{ path, op: "any",
20//! match: { ... } }`. The set of legal paths and their types is not written
21//! down here or anywhere else by hand: it is projected from the record
22//! schema in this crate by `evalhub_query::typecheck`. If the schema gains a
23//! key, the query language gains a path.
24//!
25//! The response is a page: `{ items: [...], next_cursor: string | null }`.
26//! Cursors are keyset-based (sort key plus `version_id`), opaque and signed;
27//! there is no offset pagination, because offsets over a live index skip and
28//! repeat rows.
29
30use schemars::JsonSchema;
31use serde::{Deserialize, Serialize};
32
33/// The body of `POST /cards/query` and `POST /evals/query`.
34#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize, JsonSchema)]
35#[serde(deny_unknown_fields)]
36pub struct QueryRequest {
37    /// The filter: `and` / `or` / `not` / leaf. Grammar and legal paths are
38    /// defined by the query language; see `GET /schemas/query`.
39    #[serde(default, rename = "where", skip_serializing_if = "Option::is_none")]
40    pub where_: Option<serde_json::Value>,
41    /// Sort keys, applied in order.
42    #[serde(default, skip_serializing_if = "Vec::is_empty")]
43    pub sort: Vec<Sort>,
44    /// Page size. The server clamps it to its maximum.
45    #[serde(default, skip_serializing_if = "Option::is_none")]
46    pub limit: Option<u32>,
47    /// Opaque cursor from a previous page's `next_cursor`.
48    #[serde(default, skip_serializing_if = "Option::is_none")]
49    pub cursor: Option<String>,
50    /// Extra fields to include on each item.
51    #[serde(default, skip_serializing_if = "Vec::is_empty")]
52    pub expand: Vec<Expand>,
53    /// Which versions to search. Defaults to `latest`.
54    #[serde(default, skip_serializing_if = "Option::is_none")]
55    pub version: Option<VersionSelector>,
56}
57
58/// One sort key.
59#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
60#[serde(deny_unknown_fields)]
61pub struct Sort {
62    /// A query path (for example `results[core/pass_rate].value`).
63    pub path: String,
64    /// Direction.
65    pub dir: Dir,
66}
67
68/// Sort direction.
69#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
70#[serde(rename_all = "snake_case")]
71pub enum Dir {
72    /// Ascending.
73    Asc,
74    /// Descending.
75    Desc,
76}
77
78/// Optional parts of a version that a read can include.
79#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
80#[serde(rename_all = "snake_case")]
81pub enum Expand {
82    /// The version's edges.
83    Relations,
84    /// The version's badges.
85    Badges,
86    /// The seven facet fingerprints.
87    Fingerprints,
88    /// The top-level keys that changed from the previous version.
89    Changed,
90}
91
92/// Which versions a query considers.
93#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
94#[serde(rename_all = "snake_case")]
95pub enum VersionSelector {
96    /// Only the latest non-tombstoned version of each name.
97    Latest,
98    /// Every non-tombstoned version.
99    All,
100}
101
102/// One page of results.
103///
104/// The schema name carries the item type (`Page_for_VersionEnvelope`), so a
105/// generated client gets one page type per item type instead of `Page` and
106/// `Page2`.
107#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
108#[serde(deny_unknown_fields)]
109#[schemars(rename = "Page_for_{T}")]
110pub struct Page<T> {
111    /// The items on this page.
112    pub items: Vec<T>,
113    /// Cursor for the next page, or `null` on the last page.
114    #[serde(default)]
115    pub next_cursor: Option<String>,
116}