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::query::explain::ExplainPlan;
7
8///
9/// TraceExecutionFamily
10///
11/// TraceExecutionFamily is the query-facing execution-family label derived at
12/// the session boundary after executor route selection.
13/// It keeps high-level trace shape visible without making query diagnostics
14/// depend on executor-owned route types.
15///
16#[derive(Clone, Copy, Debug, Eq, PartialEq)]
17pub enum TraceExecutionFamily {
18    PrimaryKey,
19    Ordered,
20    Grouped,
21}
22
23///
24/// TraceReuseEvent
25///
26/// Trace-surface semantic reuse result for one query planning attempt.
27/// Reuse always refers to the shared prepared query plan, so the event owns
28/// only the exact-match hit or miss outcome.
29///
30#[derive(Clone, Copy, Debug, Eq, PartialEq)]
31pub enum TraceReuseEvent {
32    /// The shared prepared query plan matched the current semantic identity.
33    Hit,
34    /// No shared prepared query plan matched the current semantic identity.
35    Miss,
36}
37
38impl TraceReuseEvent {
39    /// Return true when this event represents a semantic-reuse hit.
40    #[must_use]
41    pub const fn is_hit(self) -> bool {
42        matches!(self, Self::Hit)
43    }
44}
45
46///
47/// QueryTracePlan
48///
49/// Lightweight trace payload for one planned query.
50/// Includes plan hash, selected access strategy summary, reuse attribution,
51/// and logical explain output.
52///
53#[derive(Clone, Debug, Eq, PartialEq)]
54pub struct QueryTracePlan {
55    plan_hash: String,
56    access_strategy: String,
57    execution_family: Option<TraceExecutionFamily>,
58    reuse: TraceReuseEvent,
59    explain: ExplainPlan,
60}
61
62impl QueryTracePlan {
63    /// Construct one query trace payload.
64    #[must_use]
65    pub const fn new(
66        plan_hash: String,
67        access_strategy: String,
68        execution_family: Option<TraceExecutionFamily>,
69        reuse: TraceReuseEvent,
70        explain: ExplainPlan,
71    ) -> Self {
72        Self {
73            plan_hash,
74            access_strategy,
75            execution_family,
76            reuse,
77            explain,
78        }
79    }
80
81    /// Borrow the canonical explain fingerprint hash.
82    #[must_use]
83    pub const fn plan_hash(&self) -> &str {
84        self.plan_hash.as_str()
85    }
86
87    /// Borrow the rendered access strategy summary.
88    #[must_use]
89    pub const fn access_strategy(&self) -> &str {
90        self.access_strategy.as_str()
91    }
92
93    /// Return the selected execution family classification.
94    #[must_use]
95    pub const fn execution_family(&self) -> Option<TraceExecutionFamily> {
96        self.execution_family
97    }
98
99    /// Return semantic-reuse attribution for this trace build.
100    #[must_use]
101    pub const fn reuse(&self) -> TraceReuseEvent {
102        self.reuse
103    }
104
105    /// Borrow planner explain output carried in this trace payload.
106    #[must_use]
107    pub const fn explain(&self) -> &ExplainPlan {
108        &self.explain
109    }
110}
icydb_core/db/query/trace.rs

icydb_core/db/query/
trace.rs
