icydb-core 0.144.13

IcyDB — A schema-first typed query engine and persistence runtime for Internet Computer canisters
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

//! Module: query::trace
//! Responsibility: lightweight, deterministic trace projections for planned queries.
//! Does not own: query semantics, plan hashing primitives, or executor routing policy.
//! Boundary: read-only diagnostics surface assembled at query/session boundaries.

use crate::db::query::explain::ExplainPlan;

///
/// TraceExecutionFamily
///
/// TraceExecutionFamily is the query-facing execution-family label derived at
/// the session boundary after executor route selection.
/// It keeps high-level trace shape visible without making query diagnostics
/// depend on executor-owned route types.
///
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum TraceExecutionFamily {
    PrimaryKey,
    Ordered,
    Grouped,
}

///
/// TraceReuseArtifactClass
///
/// Trace-surface label for the planner-owned artifact class reused for this
/// query identity.
/// `0.109.0` ships one explicit reuse class: the shared prepared query plan.
///
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum TraceReuseArtifactClass {
    SharedPreparedQueryPlan,
}

///
/// TraceReuseEvent
///
/// Trace-surface semantic reuse result for one query planning attempt.
/// This keeps the shipped `0.109.0` reuse boundary explicit: one artifact
/// class and one exact-match hit or miss outcome.
///
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct TraceReuseEvent {
    pub(in crate::db) artifact_class: TraceReuseArtifactClass,
    pub(in crate::db) hit: bool,
}

impl TraceReuseEvent {
    /// Construct one reuse-hit event for the shipped artifact class.
    #[must_use]
    pub const fn hit(artifact_class: TraceReuseArtifactClass) -> Self {
        Self {
            artifact_class,
            hit: true,
        }
    }

    /// Construct one reuse-miss event for the shipped artifact class.
    #[must_use]
    pub const fn miss(artifact_class: TraceReuseArtifactClass) -> Self {
        Self {
            artifact_class,
            hit: false,
        }
    }

    /// Return the shipped artifact class this event describes.
    #[must_use]
    pub const fn artifact_class(self) -> TraceReuseArtifactClass {
        self.artifact_class
    }

    /// Return true when this event represents a semantic-reuse hit.
    #[must_use]
    pub const fn is_hit(self) -> bool {
        self.hit
    }
}

///
/// QueryTracePlan
///
/// Lightweight trace payload for one planned query.
/// Includes plan hash, selected access strategy summary, reuse attribution,
/// and logical explain output.
///
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct QueryTracePlan {
    pub(in crate::db) plan_hash: String,
    pub(in crate::db) access_strategy: String,
    pub(in crate::db) execution_family: Option<TraceExecutionFamily>,
    pub(in crate::db) reuse: TraceReuseEvent,
    pub(in crate::db) explain: ExplainPlan,
}

impl QueryTracePlan {
    /// Construct one query trace payload.
    #[must_use]
    pub const fn new(
        plan_hash: String,
        access_strategy: String,
        execution_family: Option<TraceExecutionFamily>,
        reuse: TraceReuseEvent,
        explain: ExplainPlan,
    ) -> Self {
        Self {
            plan_hash,
            access_strategy,
            execution_family,
            reuse,
            explain,
        }
    }

    /// Borrow the canonical explain fingerprint hash.
    #[must_use]
    pub const fn plan_hash(&self) -> &str {
        self.plan_hash.as_str()
    }

    /// Borrow the rendered access strategy summary.
    #[must_use]
    pub const fn access_strategy(&self) -> &str {
        self.access_strategy.as_str()
    }

    /// Return the selected execution family classification.
    #[must_use]
    pub const fn execution_family(&self) -> Option<TraceExecutionFamily> {
        self.execution_family
    }

    /// Return semantic-reuse attribution for this trace build.
    #[must_use]
    pub const fn reuse(&self) -> TraceReuseEvent {
        self.reuse
    }

    /// Borrow planner explain output carried in this trace payload.
    #[must_use]
    pub const fn explain(&self) -> &ExplainPlan {
        &self.explain
    }
}