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}