icydb_core/db/query/
trace.rs

1//! Module: query::trace
2//! Responsibility: lightweight, deterministic trace projections for planned queries.
3//! Does not own: query semantics, plan hashing primitives, or executor routing policy.
4//! Boundary: read-only diagnostics surface assembled at query/session boundaries.
5
6use crate::db::{executor::ExecutionFamily, query::explain::ExplainPlan};
7
8///
9/// TraceExecutionFamily
10///
11/// Trace-surface execution-family label derived from executor family selection.
12/// Keeps high-level route shape visible without exposing executor internals.
13///
14pub type TraceExecutionFamily = ExecutionFamily;
15
16///
17/// TraceReuseArtifactClass
18///
19/// Trace-surface label for the planner-owned artifact class reused for this
20/// query identity.
21/// `0.109.0` ships one explicit reuse class: the shared prepared query plan.
22///
23#[derive(Clone, Copy, Debug, Eq, PartialEq)]
24pub enum TraceReuseArtifactClass {
25    SharedPreparedQueryPlan,
26}
27
28///
29/// TraceReuseEvent
30///
31/// Trace-surface semantic reuse result for one query planning attempt.
32/// This keeps the shipped `0.109.0` reuse boundary explicit: one artifact
33/// class and one exact-match hit or miss outcome.
34///
35#[derive(Clone, Copy, Debug, Eq, PartialEq)]
36pub struct TraceReuseEvent {
37    pub(crate) artifact_class: TraceReuseArtifactClass,
38    pub(crate) hit: bool,
39}
40
41impl TraceReuseEvent {
42    /// Construct one reuse-hit event for the shipped artifact class.
43    #[must_use]
44    pub const fn hit(artifact_class: TraceReuseArtifactClass) -> Self {
45        Self {
46            artifact_class,
47            hit: true,
48        }
49    }
50
51    /// Construct one reuse-miss event for the shipped artifact class.
52    #[must_use]
53    pub const fn miss(artifact_class: TraceReuseArtifactClass) -> Self {
54        Self {
55            artifact_class,
56            hit: false,
57        }
58    }
59
60    /// Return the shipped artifact class this event describes.
61    #[must_use]
62    pub const fn artifact_class(self) -> TraceReuseArtifactClass {
63        self.artifact_class
64    }
65
66    /// Return true when this event represents a semantic-reuse hit.
67    #[must_use]
68    pub const fn is_hit(self) -> bool {
69        self.hit
70    }
71}
72
73///
74/// QueryTracePlan
75///
76/// Lightweight trace payload for one planned query.
77/// Includes plan hash, selected access strategy summary, reuse attribution,
78/// and logical explain output.
79///
80#[derive(Clone, Debug, Eq, PartialEq)]
81pub struct QueryTracePlan {
82    pub(crate) plan_hash: String,
83    pub(crate) access_strategy: String,
84    pub(crate) execution_family: Option<TraceExecutionFamily>,
85    pub(crate) reuse: TraceReuseEvent,
86    pub(crate) explain: ExplainPlan,
87}
88
89impl QueryTracePlan {
90    /// Construct one query trace payload.
91    #[must_use]
92    pub const fn new(
93        plan_hash: String,
94        access_strategy: String,
95        execution_family: Option<TraceExecutionFamily>,
96        reuse: TraceReuseEvent,
97        explain: ExplainPlan,
98    ) -> Self {
99        Self {
100            plan_hash,
101            access_strategy,
102            execution_family,
103            reuse,
104            explain,
105        }
106    }
107
108    /// Borrow the canonical explain fingerprint hash.
109    #[must_use]
110    pub const fn plan_hash(&self) -> &str {
111        self.plan_hash.as_str()
112    }
113
114    /// Borrow the rendered access strategy summary.
115    #[must_use]
116    pub const fn access_strategy(&self) -> &str {
117        self.access_strategy.as_str()
118    }
119
120    /// Return the selected execution family classification.
121    #[must_use]
122    pub const fn execution_family(&self) -> Option<TraceExecutionFamily> {
123        self.execution_family
124    }
125
126    /// Return semantic-reuse attribution for this trace build.
127    #[must_use]
128    pub const fn reuse(&self) -> TraceReuseEvent {
129        self.reuse
130    }
131
132    /// Borrow planner explain output carried in this trace payload.
133    #[must_use]
134    pub const fn explain(&self) -> &ExplainPlan {
135        &self.explain
136    }
137}
icydb_core/db/query/trace.rs

icydb_core/db/query/
trace.rs
