Skip to main content

uqa_sql/result/
explain.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Typed diagnostic properties retain construction leases until the final renderer releases them.
8
9use crate::SQLError;
10use uqa_core::memory::{Produced, ProductionControl, ProductionVec};
11
12#[cfg(test)]
13mod tests;
14
15/// Native optimizer estimates, independent of measurements from an invocation.
16#[derive(Debug, Clone, Copy, PartialEq)]
17pub struct ExplainPlanEstimate {
18    pub startup: f64,
19    pub total: f64,
20    pub rows: f64,
21    pub width: Option<u64>,
22}
23
24/// One native query or source estimate from the root's original lexical traversal. Parent indices describe this captured plan, not a runtime operator identity.
25#[derive(Debug)]
26pub struct ExplainNodeEstimate {
27    pub parent: Option<usize>,
28    pub kind: &'static str,
29    pub relation: Option<String>,
30    pub estimate: ExplainPlanEstimate,
31}
32
33/// Accumulated work at an executed native plan boundary. Renderers divide rows and durations by completed loops; an unexecuted boundary retains zero loops.
34#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
35pub struct ExplainNodeMetrics {
36    pub rows: u64,
37    pub loops: u64,
38    pub startup: std::time::Duration,
39    pub total: std::time::Duration,
40}
41
42/// One physical source or pipeline instance observed by the invocation. Its display index is independent of the cost tree.
43#[derive(Debug, Clone, Copy)]
44pub struct ExplainNodeExecution {
45    pub kind: &'static str,
46    pub io: uqa_core::io_usage::IOUsage,
47    pub metrics: ExplainNodeMetrics,
48}
49
50/// Actual `DataRow` payload construction, excluding transport headers and network I/O.
51#[derive(Debug, Clone, Copy, Default)]
52pub struct ExplainSerializationMetrics {
53    pub bytes: u64,
54    pub elapsed: std::time::Duration,
55    pub io: uqa_core::io_usage::IOUsage,
56}
57
58/// Native planning work captured before execution, with the session clock policy at its completion boundary.
59#[derive(Debug, Clone, Copy, Default)]
60pub struct ExplainPlanningMetrics {
61    pub io: uqa_core::io_usage::IOUsage,
62    pub io_timing: bool,
63    pub memory: Option<ExplainPlanningMemory>,
64}
65
66/// Live exposed executable and resident constant storage before execution. Used bytes exclude unused container capacity; allocated bytes include it. Separately owned analysis/catalog and spill-file services, opaque dependency allocations and allocator bookkeeping are outside this observation. Neither quantity is a process total, execution peak or estimate.
67#[derive(Debug, Clone, Copy, PartialEq, Eq)]
68pub struct ExplainPlanningMemory {
69    pub used_bytes: usize,
70    pub allocated_bytes: usize,
71}
72
73/// Physical diagnostic values keep numeric primitives inline and retain only admitted containers and copied text. Field names and fixed labels borrow static definitions.
74#[derive(Debug)]
75pub enum ExplainValue {
76    Null,
77    Bool(bool),
78    Unsigned(u64),
79    Float(f64),
80    Label(&'static str),
81    Text(Produced<String>),
82    Object(Produced<Vec<(&'static str, Self)>>),
83}
84
85pub struct ExplainObject<'a> {
86    fields: ProductionVec<'a, (&'static str, ExplainValue)>,
87    control: ProductionControl<'a>,
88}
89
90impl<'a> ExplainObject<'a> {
91    pub fn new(control: ProductionControl<'a>) -> Self {
92        Self {
93            fields: ProductionVec::new(control),
94            control,
95        }
96    }
97
98    pub fn insert(&mut self, key: &'static str, value: ExplainValue) -> Result<(), SQLError> {
99        self.fields.push_produced(
100            self.control
101                .finish((key, value), self.control.empty_reservation())?,
102        )?;
103        Ok(())
104    }
105
106    pub fn text(&mut self, key: &'static str, value: &str) -> Result<(), SQLError> {
107        self.insert(key, ExplainValue::Text(self.control.copy_text(value)?))
108    }
109
110    pub fn label(&mut self, key: &'static str, value: &'static str) -> Result<(), SQLError> {
111        self.insert(key, ExplainValue::Label(value))
112    }
113
114    pub fn number(&mut self, key: &'static str, value: u64) -> Result<(), SQLError> {
115        self.insert(key, ExplainValue::Unsigned(value))
116    }
117
118    pub fn optional_number(
119        &mut self,
120        key: &'static str,
121        value: Option<u64>,
122    ) -> Result<(), SQLError> {
123        self.insert(
124            key,
125            value.map_or(ExplainValue::Null, ExplainValue::Unsigned),
126        )
127    }
128
129    pub fn float(&mut self, key: &'static str, value: f64) -> Result<(), SQLError> {
130        self.insert(key, ExplainValue::Float(value))
131    }
132
133    pub fn boolean(&mut self, key: &'static str, value: bool) -> Result<(), SQLError> {
134        self.insert(key, ExplainValue::Bool(value))
135    }
136
137    pub fn null(&mut self, key: &'static str) -> Result<(), SQLError> {
138        self.insert(key, ExplainValue::Null)
139    }
140
141    pub fn finish(self) -> Result<ExplainValue, SQLError> {
142        let (mut fields, memory) = self.fields.finish()?.into_parts();
143        fields.sort_unstable_by_key(|(key, _)| *key);
144        Ok(ExplainValue::Object(self.control.finish(fields, memory)?))
145    }
146}