icydb_core/db/query/
diagnostics.rs

1//! Public, read-only diagnostics for query planning and execution.
2//!
3//! Diagnostics contract:
4//! - `ExplainPlan` is deterministic for equivalent queries and plans.
5//! - `PlanFingerprint` is stable within a major version (inputs are normalized).
6//! - Execution trace events are best-effort diagnostics and may evolve.
7//! - Diagnostics never execute queries unless explicitly requested.
8//! - Diagnostics are observational only; they are not correctness proofs.
9
10pub use crate::db::executor::trace::{QueryTraceEvent, TraceAccess, TraceExecutorKind, TracePhase};
11use crate::db::query::plan::{ExplainPlan, PlanFingerprint};
12
13///
14/// QueryDiagnostics
15///
16/// Read-only planning diagnostics derived from a `Query`.
17///
18
19#[derive(Clone, Debug, Eq, PartialEq)]
20pub struct QueryDiagnostics {
21    pub explain: ExplainPlan,
22    pub fingerprint: PlanFingerprint,
23}
24
25impl From<ExplainPlan> for QueryDiagnostics {
26    fn from(explain: ExplainPlan) -> Self {
27        let fingerprint = explain.fingerprint();
28        Self {
29            explain,
30            fingerprint,
31        }
32    }
33}
34
35///
36/// QueryExecutionDiagnostics
37///
38/// Read-only execution diagnostics emitted for a single query execution.
39///
40
41#[derive(Clone, Debug, Eq, PartialEq)]
42pub struct QueryExecutionDiagnostics {
43    pub fingerprint: PlanFingerprint,
44    pub events: Vec<QueryTraceEvent>,
45}
46
47/// Public alias for trace access kinds in query diagnostics.
48pub type QueryTraceAccess = TraceAccess;
49
50/// Public alias for trace executor kinds in query diagnostics.
51pub type QueryTraceExecutorKind = TraceExecutorKind;
52
53/// Public alias for trace phase kinds in query diagnostics.
54pub type QueryTracePhase = TracePhase;
55
56#[must_use]
57pub const fn start_event(
58    fingerprint: PlanFingerprint,
59    access: Option<TraceAccess>,
60    executor: TraceExecutorKind,
61) -> QueryTraceEvent {
62    QueryTraceEvent::Start {
63        fingerprint,
64        executor,
65        access,
66    }
67}
68
69#[must_use]
70pub const fn finish_event(
71    fingerprint: PlanFingerprint,
72    access: Option<TraceAccess>,
73    executor: TraceExecutorKind,
74    rows: u64,
75) -> QueryTraceEvent {
76    QueryTraceEvent::Finish {
77        fingerprint,
78        executor,
79        access,
80        rows,
81    }
82}
icydb_core/db/query/diagnostics.rs

icydb_core/db/query/
diagnostics.rs
