Skip to main content

qql_protocol/
response.rs

1use std::collections::HashMap;
2use std::fmt::Write as _;
3
4use serde::ser::{SerializeMap, Serializer};
5use serde::{Deserialize, Serialize};
6
7use qql_plan::{
8    PlanFacetValue, PlanGroupId, PlanPointId, PlanShardKey, PlanVectorStruct, QuotaConfig,
9};
10
11use crate::schema::CollectionInfo;
12
13use crate::telemetry::{PhaseTimings, ServerTelemetry, ServerUsage};
14
15/// Single-statement execution outcome: status, operation label, message, data,
16/// and optional server telemetry.
17#[derive(Debug, Clone, PartialEq, Serialize)]
18pub struct ExecResponse {
19    /// Whether the statement succeeded.
20    pub ok: bool,
21    /// Operation label (e.g. `QUERY`, `UPSERT`, `PARSE`) for this result.
22    pub operation: String,
23    /// Human-readable summary or error text.
24    pub message: String,
25    /// Typed payload (search hits, count, facet entries, …), when the
26    /// operation returns data.
27    pub data: Option<ExecData>,
28    /// Server telemetry (`time` + hardware/inference `usage`) when the
29    /// backend reported it. `None` where the route/transport carries none
30    /// (batch items, collection DDL over gRPC, mocks without timing).
31    /// `skip_serializing_if` keeps the pre-telemetry JSON shape byte-identical
32    /// when no telemetry was reported.
33    #[serde(skip_serializing_if = "Option::is_none")]
34    pub telemetry: Option<ServerTelemetry>,
35}
36
37/// Canonical cross-SDK execution result. Every `client.execute(…)` call
38/// returns this shape regardless of input type (string / Stmt / array).
39#[derive(Debug, Clone, Serialize)]
40pub struct ExecutionReport {
41    /// Whether every statement succeeded (`failed == 0`).
42    pub ok: bool,
43    /// One `ExecResponse` per statement, in execution order.
44    pub results: Vec<ExecResponse>,
45    /// Number of successful statements.
46    pub succeeded: usize,
47    /// Number of failed statements.
48    pub failed: usize,
49    /// Report-level telemetry totals (server times summed, hardware counters
50    /// summed, per-model tokens summed). `None` when no response reported
51    /// telemetry; omitted from the serialized shape.
52    #[serde(skip_serializing_if = "Option::is_none")]
53    pub telemetry: Option<ServerTelemetry>,
54}
55
56impl ExecutionReport {
57    /// Create from a collection of `ExecResponse`s. `ok` is `failed == 0`;
58    /// `telemetry` aggregates the per-response telemetry (see
59    /// [`ServerTelemetry::aggregate`]).
60    pub fn from_results(results: Vec<ExecResponse>) -> Self {
61        let succeeded = results.iter().filter(|r| r.ok).count();
62        let failed = results.len() - succeeded;
63        let telemetry =
64            ServerTelemetry::aggregate(results.iter().filter_map(|r| r.telemetry.as_ref()));
65        Self {
66            ok: failed == 0,
67            results,
68            succeeded,
69            failed,
70            telemetry,
71        }
72    }
73
74    /// Convenience wrapper for a single `ExecResponse`.
75    pub fn single(resp: ExecResponse) -> Self {
76        let ok = resp.ok;
77        let telemetry = resp.telemetry.clone();
78        Self {
79            ok,
80            results: vec![resp],
81            succeeded: if ok { 1 } else { 0 },
82            failed: if ok { 0 } else { 1 },
83            telemetry,
84        }
85    }
86
87    /// Return the first statement response, if present.
88    pub fn first(&self) -> Option<&ExecResponse> {
89        self.results.first()
90    }
91
92    /// Return typed search hits of statement `stmt`.
93    pub fn hits(&self, stmt: usize) -> Option<Vec<SearchHit>> {
94        self.results.get(stmt).and_then(|r| r.hits())
95    }
96
97    /// Return point IDs from statement `stmt`.
98    pub fn ids(&self, stmt: usize) -> Vec<u64> {
99        self.results.get(stmt).map(|r| r.ids()).unwrap_or_default()
100    }
101
102    /// Return the count integer from statement `stmt`.
103    pub fn count(&self, stmt: usize) -> Option<u64> {
104        self.results.get(stmt).and_then(|r| r.count())
105    }
106
107    /// Return facet entries as `(value, count)` pairs from statement `stmt`.
108    pub fn facet(&self, stmt: usize) -> Option<Vec<(PlanFacetValue, u64)>> {
109        self.results.get(stmt).and_then(|r| r.facet())
110    }
111
112    /// Return the count integer from the first statement.
113    pub fn first_count(&self) -> Option<u64> {
114        self.count(0)
115    }
116
117    /// Return the search hits from the first statement.
118    pub fn first_hits(&self) -> Option<Vec<SearchHit>> {
119        self.hits(0)
120    }
121
122    /// Return the point IDs from the first statement.
123    pub fn first_ids(&self) -> Vec<u64> {
124        self.ids(0)
125    }
126
127    /// Return the facet pairs from the first statement.
128    pub fn first_facet(&self) -> Option<Vec<(PlanFacetValue, u64)>> {
129        self.facet(0)
130    }
131}
132
133/// Structured `EXPLAIN ANALYZE` report: the static plan summary plus the
134/// measured execution. JSON-serializable; returned by the runtime's
135/// `Executor::explain_analyze`.
136#[derive(Debug, Clone, Serialize)]
137pub struct AnalyzeReport {
138    /// Whether the analyzed statement succeeded (errors surface as `Err`).
139    pub ok: bool,
140    /// Static plan summary — the same tree `Executor::explain` renders,
141    /// captured before execution.
142    pub plan: String,
143    /// Per-phase client timings (milliseconds).
144    pub phases: PhaseTimings,
145    /// Total server time in seconds (summed per-response `time`); `None`
146    /// when the backend reported none.
147    #[serde(skip_serializing_if = "Option::is_none")]
148    pub server_time_s: Option<f64>,
149    /// Merged hardware/inference usage; `None` when the backend reported none.
150    #[serde(skip_serializing_if = "Option::is_none")]
151    pub usage: Option<ServerUsage>,
152    /// The statement's execution response(s), in order (one entry: analyze
153    /// is single-statement, like Postgres `EXPLAIN ANALYZE`).
154    pub results: Vec<ExecResponse>,
155}
156
157/// Controls batch-execution behaviour when a statement fails.
158#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
159#[serde(rename_all = "lowercase")]
160pub enum OnError {
161    /// Halt immediately on the first error (default).
162    #[default]
163    Stop,
164    /// Continue executing remaining statements, collecting error
165    /// responses alongside successes.
166    Continue,
167}
168
169/// Normalize a backend f32 score to f64 **once, at ingestion**, through its
170/// shortest round-trip decimal (`0.95f32` becomes `0.95f64`, not
171/// `0.949999988079071`).
172///
173/// Every transport parses scores through this helper (REST `parse_hit` via
174/// `score_from_wire`, gRPC `scored_point_to_hit`, edge
175/// `from_edge_scored_point_to_hit`, cross-rerank dispatch), so the stored
176/// value already carries the shortest decimal and plain
177/// `Serialize`/`pythonize` emit it identically everywhere — JSON text,
178/// `Value`, and the Python `ScoredPoint.score` getter agree with no custom
179/// serializer. The mapping is monotonic over finite values, so sort order
180/// under `partial_cmp` is unchanged.
181///
182/// The shortest decimal renders into a stack-resident `ScoreBuf` through
183/// the same std float formatter as `to_string`, so the decimal is identical
184/// without the per-hit `String` allocation; parsing it back as f64 yields
185/// the same value the old `v.to_string().parse()` round-trip produced.
186///
187/// (`ryu::Buffer` was measured first and rejected: on exact ties such as
188/// `0.494140625f32` it rounds to even — `"0.49414062"` — while std rounds
189/// away — `"0.49414063"`. Same-renderer output is identical by construction.)
190pub fn score_f64(v: f32) -> f64 {
191    let mut buf = ScoreBuf::new();
192    // Infallible in practice: the longest f32 `Display` (47 chars, plus a
193    // sign) fits the buffer with room to spare. A failed write falls back
194    // to the plain widening rather than risk a truncated decimal.
195    if write!(buf, "{v}").is_err() {
196        return v as f64;
197    }
198    buf.as_str().parse().unwrap_or(v as f64)
199}
200
201/// Stack-resident decimal scratch for [`score_f64`]: `write!` renders the
202/// f32 through std's `Display` into inline bytes — no allocator in the path.
203/// 64 bytes covers the longest f32 `Display` (47 chars: subnormal plain
204/// notation like `0.000…001`, plus a sign).
205struct ScoreBuf {
206    buf: [u8; 64],
207    len: usize,
208}
209
210impl ScoreBuf {
211    fn new() -> Self {
212        Self {
213            buf: [0; 64],
214            len: 0,
215        }
216    }
217
218    fn as_str(&self) -> &str {
219        // `Display` for f32 emits ASCII only, so the collected bytes are
220        // always valid UTF-8; fall back to empty (which fails `parse` and
221        // takes the `unwrap_or` plain widening) rather than panicking.
222        std::str::from_utf8(&self.buf[..self.len]).unwrap_or("")
223    }
224}
225
226impl std::fmt::Write for ScoreBuf {
227    fn write_str(&mut self, s: &str) -> std::fmt::Result {
228        let bytes = s.as_bytes();
229        let end = self.len + bytes.len();
230        if end > self.buf.len() {
231            return Err(std::fmt::Error);
232        }
233        self.buf[self.len..end].copy_from_slice(bytes);
234        self.len = end;
235        Ok(())
236    }
237}
238
239/// Normalize a JSON-decoded wire score to the stored f64 in one step.
240///
241/// REST decodes every JSON number as f64, so the wire decimal narrows to f32
242/// and then shortest-expands through [`score_f64`]; fusing both halves here
243/// keeps that double conversion at exactly one call site instead of inline
244/// at every `parse_hit`.
245///
246/// The sole caller is [`crate::rest`], which is the REST boundary.
247pub fn score_from_wire(v: f64) -> f64 {
248    score_f64(v as f32)
249}
250
251/// Normalized search hit returned inside `ExecResponse` data.
252#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
253pub struct SearchHit {
254    /// Point ID (integer or string/UUID).
255    pub id: PlanPointId,
256    /// Similarity or rerank score, rounded once at ingestion via
257    /// [`score_f64`] so it holds the shortest round-trip decimal (`0.95`,
258    /// not `0.949999988079071`): Qdrant's own JSON text and the native Python
259    /// `ScoredPoint.score` getter both use that form, so the JSON report view
260    /// and the typed view agree with plain `Serialize` (no custom
261    /// `serialize_with`).
262    ///
263    /// Deliberate asymmetry with [`PlanVectorStruct`]: scalar scores are
264    /// human-read values worth normalizing, while `vector` stays `Vec<f32>`
265    /// passthrough — exact decimal equality on 128-dim vectors is
266    /// meaningless, and doubling their memory for cosmetics is indefensible.
267    pub score: f64,
268    /// Point payload when requested via `WITH PAYLOAD`.
269    pub payload: Option<HashMap<String, serde_json::Value>>,
270    /// Source collection. Populated by cross-collection operations (e.g.
271    /// CROSS RERANK) so results are unambiguous when multiple collections
272    /// share the same point id.
273    #[serde(skip_serializing_if = "Option::is_none")]
274    pub collection: Option<String>,
275    /// Vector(s) returned when requested via `WITH VECTOR`.
276    #[serde(skip_serializing_if = "Option::is_none")]
277    pub vector: Option<PlanVectorStruct>,
278}
279
280/// Grouped query result: one group key with its ordered hits.
281///
282/// Serializes to Qdrant's group shape `{"id": …, "hits": […]}` so report JSON
283/// and SDK `.groups()` consumers read the same field names as the backend.
284/// `Deserialize` mirrors it for wire round-trips.
285#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
286pub struct GroupedSearchResult {
287    /// Group key value as returned by Qdrant.
288    #[serde(rename = "id")]
289    pub group_id: PlanGroupId,
290    /// Search hits in this group, in backend order.
291    pub hits: Vec<SearchHit>,
292}
293
294/// One facet entry: value + occurrence count.
295#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
296pub struct FacetHit {
297    /// Facet value as returned by Qdrant.
298    pub value: PlanFacetValue,
299    /// Number of points carrying this value.
300    pub count: u64,
301}
302
303/// Transport-neutral typed payload of one operation result. Closed by
304/// construction: every backend response shape the transports can produce has a
305/// variant here — there is no JSON passthrough.
306///
307/// Serialization emits the report JSON shapes SDK consumers already read:
308/// `Hits` → array of [`SearchHit`], `Groups` → `{"groups": [{"id", "hits"}]}`,
309/// `Count` → `{"count": n}`, `Facet` → array of `{"value": …, "count": n}`,
310/// `Mutation { affected: Some(n) }` → `{"count": n}`,
311/// `Mutation { affected: None }` → `null`,
312/// `Collections` → `{"collections": ["name", …]}`,
313/// `Collection` → the [`CollectionInfo`] object,
314/// `ShardKeys` → `{"shard_keys": [key, …]}`,
315/// `Quotas` → the [`QuotaConfig`] object.
316// `CollectionInfo` is the largest variant (nested vector/index schema); the
317// enum stays cloneable and is not hot-path cloned, so boxing it would only add
318// indirection to the public IR shape.
319#[allow(clippy::large_enum_variant)]
320#[derive(Debug, Clone, PartialEq)]
321pub enum ExecData {
322    /// Query / scroll / retrieve hits, in backend order.
323    Hits(Vec<SearchHit>),
324    /// Grouped query results (`QUERY … GROUP BY`).
325    Groups(Vec<GroupedSearchResult>),
326    /// COUNT result.
327    Count(u64),
328    /// FACET entries.
329    Facet(Vec<FacetHit>),
330    /// Write-op outcome: `affected: Some(n)` for upsert (n points written),
331    /// `None` for status-only mutations (delete, payload/vector updates).
332    Mutation {
333        /// Number of points written, when the operation reports one.
334        affected: Option<u64>,
335    },
336    /// Collection names (`SHOW COLLECTIONS`).
337    Collections(Vec<String>),
338    /// Collection metadata (`SHOW COLLECTION`).
339    Collection(CollectionInfo),
340    /// Custom shard keys (`SHOW SHARD KEYS`).
341    ShardKeys(Vec<PlanShardKey>),
342    /// Cluster-wide quota configuration (`SHOW QUOTAS` / `SET QUOTA`).
343    Quotas(QuotaConfig),
344}
345
346impl Serialize for ExecData {
347    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
348        match self {
349            ExecData::Hits(hits) => hits.serialize(serializer),
350            ExecData::Groups(groups) => {
351                let mut map = serializer.serialize_map(Some(1))?;
352                map.serialize_entry("groups", groups)?;
353                map.end()
354            }
355            ExecData::Count(count) => {
356                let mut map = serializer.serialize_map(Some(1))?;
357                map.serialize_entry("count", count)?;
358                map.end()
359            }
360            ExecData::Facet(hits) => hits.serialize(serializer),
361            ExecData::Mutation {
362                affected: Some(count),
363            } => {
364                let mut map = serializer.serialize_map(Some(1))?;
365                map.serialize_entry("count", count)?;
366                map.end()
367            }
368            ExecData::Mutation { affected: None } => serializer.serialize_none(),
369            ExecData::Collections(collections) => {
370                let mut map = serializer.serialize_map(Some(1))?;
371                map.serialize_entry("collections", collections)?;
372                map.end()
373            }
374            ExecData::Collection(info) => info.serialize(serializer),
375            ExecData::ShardKeys(keys) => {
376                let mut map = serializer.serialize_map(Some(1))?;
377                map.serialize_entry("shard_keys", keys)?;
378                map.end()
379            }
380            ExecData::Quotas(config) => config.serialize(serializer),
381        }
382    }
383}
384
385impl ExecData {
386    /// Borrow hits when this is a [`ExecData::Hits`] payload. A query that
387    /// found nothing still yields `Some(&[])`, matching the pre-typing
388    /// `hits()` contract.
389    pub fn hits(&self) -> Option<&[SearchHit]> {
390        match self {
391            ExecData::Hits(hits) => Some(hits),
392            _ => None,
393        }
394    }
395
396    /// Borrow grouped results when this is an [`ExecData::Groups`] payload.
397    pub fn groups(&self) -> Option<&[GroupedSearchResult]> {
398        match self {
399            ExecData::Groups(groups) => Some(groups),
400            _ => None,
401        }
402    }
403
404    /// The integer when this is a [`ExecData::Count`] payload, or the affected
405    /// point count of an upsert [`ExecData::Mutation`].
406    pub fn count(&self) -> Option<u64> {
407        match self {
408            ExecData::Count(count) => Some(*count),
409            ExecData::Mutation { affected } => *affected,
410            _ => None,
411        }
412    }
413
414    /// The affected-point count of an [`ExecData::Mutation`]: `Some(Some(n))`
415    /// for an upsert, `Some(None)` for a status-only write, `None` otherwise.
416    pub fn mutation_affected(&self) -> Option<Option<u64>> {
417        match self {
418            ExecData::Mutation { affected } => Some(*affected),
419            _ => None,
420        }
421    }
422
423    /// Borrow facet entries when this is a [`ExecData::Facet`] payload.
424    pub fn facet(&self) -> Option<&[FacetHit]> {
425        match self {
426            ExecData::Facet(hits) => Some(hits),
427            _ => None,
428        }
429    }
430
431    /// Borrow collection names when this is a [`ExecData::Collections`] payload.
432    pub fn collections(&self) -> Option<&[String]> {
433        match self {
434            ExecData::Collections(collections) => Some(collections),
435            _ => None,
436        }
437    }
438
439    /// Borrow collection metadata when this is an [`ExecData::Collection`] payload.
440    pub fn collection(&self) -> Option<&CollectionInfo> {
441        match self {
442            ExecData::Collection(info) => Some(info),
443            _ => None,
444        }
445    }
446
447    /// Borrow custom shard keys when this is an [`ExecData::ShardKeys`] payload.
448    pub fn shard_keys(&self) -> Option<&[PlanShardKey]> {
449        match self {
450            ExecData::ShardKeys(keys) => Some(keys),
451            _ => None,
452        }
453    }
454
455    /// Borrow the quota configuration when this is a [`ExecData::Quotas`] payload.
456    pub fn quotas(&self) -> Option<&QuotaConfig> {
457        match self {
458            ExecData::Quotas(config) => Some(config),
459            _ => None,
460        }
461    }
462
463    /// Whether the payload carries no records: empty
464    /// `Hits`/`Groups`/`Facet`/`Collections`/`ShardKeys`. `Count`, `Mutation`,
465    /// `Collection`, and `Quotas` are never empty (a zero count or an
466    /// unlimited quota config is a result).
467    pub fn is_empty(&self) -> bool {
468        match self {
469            ExecData::Hits(hits) => hits.is_empty(),
470            ExecData::Groups(groups) => groups.is_empty(),
471            ExecData::Count(_)
472            | ExecData::Mutation { .. }
473            | ExecData::Collection(_)
474            | ExecData::Quotas(_) => false,
475            ExecData::Facet(hits) => hits.is_empty(),
476            ExecData::Collections(collections) => collections.is_empty(),
477            ExecData::ShardKeys(keys) => keys.is_empty(),
478        }
479    }
480}
481
482/// Typed backend response: data + telemetry, no transport JSON envelope.
483#[derive(Debug, Clone, Serialize)]
484pub struct BackendResponse {
485    /// Typed operation payload.
486    pub data: ExecData,
487    /// Server telemetry extracted from the transport envelope, when present.
488    #[serde(skip_serializing_if = "Option::is_none")]
489    pub telemetry: Option<ServerTelemetry>,
490}
491
492impl ExecResponse {
493    /// Borrow the typed search hits if this response contains hits data.
494    pub fn hits_ref(&self) -> Option<&[SearchHit]> {
495        self.data.as_ref().and_then(ExecData::hits)
496    }
497
498    /// Typed search hits: cloned from the native typed payload. Non-hits
499    /// payloads (counts, facets, status envelopes) yield `None`.
500    pub fn hits(&self) -> Option<Vec<SearchHit>> {
501        self.hits_ref().map(<[SearchHit]>::to_vec)
502    }
503
504    /// Return point IDs as u64 from hits or scroll results.
505    pub fn ids(&self) -> Vec<u64> {
506        let Some(hits) = self.hits_ref() else {
507            return Vec::new();
508        };
509        hits.iter()
510            .filter_map(|hit| match &hit.id {
511                PlanPointId::Number(id) => Some(*id),
512                PlanPointId::String(id) => id.parse().ok(),
513            })
514            .collect()
515    }
516
517    /// Return the count from a COUNT response, if present.
518    pub fn count(&self) -> Option<u64> {
519        self.data.as_ref().and_then(ExecData::count)
520    }
521
522    /// Return facet entries as `(value, count)` pairs, if present.
523    pub fn facet(&self) -> Option<Vec<(PlanFacetValue, u64)>> {
524        let entries = self.data.as_ref()?.facet()?;
525        Some(
526            entries
527                .iter()
528                .map(|entry| (entry.value.clone(), entry.count))
529                .collect(),
530        )
531    }
532}
533
534#[cfg(test)]
535mod tests {
536    use super::*;
537
538    /// Scores are rounded once at ingestion ([`score_f64`]), so the stored
539    /// f64 already holds the shortest decimal — plain `Serialize` emits it
540    /// (`0.95`, not `0.949999988079071`), keeping the JSON report view and
541    /// every native view (`pythonize`, `ScoredPoint.score`) in agreement.
542    #[test]
543    fn score_f64_rounds_once_at_ingestion() {
544        assert_eq!(score_f64(0.95f32), 0.95f64);
545        let hit = SearchHit {
546            id: PlanPointId::Number(1),
547            score: score_f64(0.95f32),
548            payload: None,
549            collection: None,
550            vector: None,
551        };
552        let value = serde_json::to_value(&hit).expect("hit serializes");
553        assert_eq!(value["score"], serde_json::json!(0.95));
554    }
555
556    /// The stack-buffer shortest repr must stay byte-identical to the old
557    /// heap round-trip: pin a table of tricky values (short decimals,
558    /// exponent boundaries, subnormals, extremes, non-finite) against
559    /// `to_string().parse()`. NaN compares unequal to itself, so it asserts
560    /// NaN-ness on both sides.
561    #[test]
562    fn score_f64_matches_heap_round_trip() {
563        for v in [
564            0.95f32,
565            0.75,
566            0.1,
567            0.99,
568            1.0,
569            -1.0,
570            0.0,
571            -0.0,
572            1e-5,
573            1e-4,
574            1e21,
575            12345.67,
576            0.30000004,
577            f32::MIN_POSITIVE,
578            f32::EPSILON,
579            3.4028235e38,
580            1.1754944e-38,
581            1e-45,
582            2.5e-7,
583            std::f32::consts::PI,
584            100.0,
585            f32::INFINITY,
586            f32::NEG_INFINITY,
587        ] {
588            let expected: f64 = v.to_string().parse().unwrap_or(v as f64);
589            assert_eq!(score_f64(v), expected, "score_f64({v}) diverged");
590        }
591        assert!(score_f64(f32::NAN).is_nan());
592        let expected: f64 = f32::NAN.to_string().parse().unwrap_or(f32::NAN as f64);
593        assert!(expected.is_nan());
594    }
595
596    /// The wire decimal normalizes once: the exact f32 expansion
597    /// `0.949999988079071` narrows back to the same stored `0.95`.
598    #[test]
599    fn score_from_wire_narrows_once() {
600        assert_eq!(super::score_from_wire(0.95), 0.95f64);
601        assert_eq!(super::score_from_wire(0.949999988079071), 0.95f64);
602    }
603}