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}
64
65/// Physical diagnostic values keep numeric primitives inline and retain only admitted containers and copied text. Field names and fixed labels borrow static definitions.
66#[derive(Debug)]
67pub enum ExplainValue {
68    Null,
69    Bool(bool),
70    Unsigned(u64),
71    Float(f64),
72    Label(&'static str),
73    Text(Produced<String>),
74    Object(Produced<Vec<(&'static str, Self)>>),
75}
76
77pub struct ExplainObject<'a> {
78    fields: ProductionVec<'a, (&'static str, ExplainValue)>,
79    control: ProductionControl<'a>,
80}
81
82impl<'a> ExplainObject<'a> {
83    pub fn new(control: ProductionControl<'a>) -> Self {
84        Self {
85            fields: ProductionVec::new(control),
86            control,
87        }
88    }
89
90    pub fn insert(&mut self, key: &'static str, value: ExplainValue) -> Result<(), SQLError> {
91        self.fields.push_produced(
92            self.control
93                .finish((key, value), self.control.empty_reservation())?,
94        )?;
95        Ok(())
96    }
97
98    pub fn text(&mut self, key: &'static str, value: &str) -> Result<(), SQLError> {
99        self.insert(key, ExplainValue::Text(self.control.copy_text(value)?))
100    }
101
102    pub fn label(&mut self, key: &'static str, value: &'static str) -> Result<(), SQLError> {
103        self.insert(key, ExplainValue::Label(value))
104    }
105
106    pub fn number(&mut self, key: &'static str, value: u64) -> Result<(), SQLError> {
107        self.insert(key, ExplainValue::Unsigned(value))
108    }
109
110    pub fn optional_number(
111        &mut self,
112        key: &'static str,
113        value: Option<u64>,
114    ) -> Result<(), SQLError> {
115        self.insert(
116            key,
117            value.map_or(ExplainValue::Null, ExplainValue::Unsigned),
118        )
119    }
120
121    pub fn float(&mut self, key: &'static str, value: f64) -> Result<(), SQLError> {
122        self.insert(key, ExplainValue::Float(value))
123    }
124
125    pub fn boolean(&mut self, key: &'static str, value: bool) -> Result<(), SQLError> {
126        self.insert(key, ExplainValue::Bool(value))
127    }
128
129    pub fn null(&mut self, key: &'static str) -> Result<(), SQLError> {
130        self.insert(key, ExplainValue::Null)
131    }
132
133    pub fn finish(self) -> Result<ExplainValue, SQLError> {
134        let (mut fields, memory) = self.fields.finish()?.into_parts();
135        fields.sort_unstable_by_key(|(key, _)| *key);
136        Ok(ExplainValue::Object(self.control.finish(fields, memory)?))
137    }
138}