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}