Struct QueryError 

pub struct QueryError(/* private fields */);

Structured native-engine error with stable classification and facts.

Implementations

impl QueryError

pub fn new( code: QueryErrorCode, operation: &'static str, message: impl Into<String>, ) -> Self

Creates a native-engine error with a stable operation id and message.

operation should be a stable dotted identifier such as query_engine.plan.execute. message is human-facing diagnostic text. Add machine-readable context with Self::with_fact.

Panics

Panics when operation or message is empty. Construction-time identity must be present; later decoration (Self::with_fact, Self::with_source) never panics and keeps the first value.

pub fn with_fact(self, key: &'static str, value: impl ToString) -> Self

Adds one machine-readable fact.

key must be a non-empty static string and should be treated as part of the diagnostic contract once exposed. value is stringified with ToString. A duplicate or empty key never panics and never replaces the primary error’s facts. The first value wins, and the rejected key is recorded under the fact_collision_keys fact. Layered with_fact calls must therefore use distinct keys per layer; wrapping an error must not re-emit a key the wrapped error already owns.

pub fn context(&self) -> &FailureContext

Returns the typed failure evidence that decisions read.

pub fn with_memory_failure(self, memory: MemoryFailure) -> Self

Records the budget scope the failure passed through. The innermost scope wins; a different later scope is reported as a fact collision.

pub fn with_resource_boundary(self, boundary: ResourceBoundary) -> Self

Records the execution boundary that owned the failed work. The first complete boundary wins as a unit, so an outer scope never pairs its node or side with an inner failure location.

pub fn wire_facts(&self) -> impl Iterator<Item = (&'static str, Cow<'_, str>)>

Stored diagnostic facts plus the typed context rendered under its wire keys, sorted by key.

The typed value wins over a stored fact with the same key; a stored fact that disagrees is reported under fact_collision_keys.

pub fn wire_fact(&self, key: &str) -> Option<Cow<'_, str>>

One value of Self::wire_facts.

pub fn with_query_id(self, query_id: impl Into<QueryId>) -> Self

Assigns a query-wide diagnostic correlation id and mirrors it into facts.

pub fn with_trace_id(self, trace_id: impl Into<TraceId>) -> Self

Assigns an optional parent trace id and mirrors it into facts.

pub fn with_source<E>(self, source: E) -> Self

where E: StdError + Send + Sync + 'static,

Attaches the source error when no source is already present.

A second source is discarded so error decoration cannot replace the original causal chain. Layers that need to add context wrap the error in a new QueryError and do not re-attach a source.

pub fn code(&self) -> QueryErrorCode

Returns the stable machine-readable error code.

pub fn kind(&self) -> QueryErrorKind

Returns the coarse category derived from Self::code.

pub fn status(&self) -> QueryErrorStatus

Returns the retry/remediation status derived from Self::code.

pub fn query_id(&self) -> Option<&QueryId>

Returns the query-wide diagnostic correlation id, when assigned.

pub fn trace_id(&self) -> Option<&TraceId>

Returns the optional parent trace id, when assigned.

pub fn operation(&self) -> &'static str

Returns the stable dotted operation id that produced the error.

pub fn message(&self) -> &str

Returns the human-facing diagnostic message.

pub fn facts(&self) -> &Facts

Returns the sorted machine-readable fact set.

pub fn fact_value(&self, key: &str) -> Option<&str>

Returns a stored fact by name. Typed failure-context projections are available through Self::wire_facts.

pub fn source_error(&self) -> Option<&(dyn StdError + 'static)>

Returns the underlying source error when one was attached.

pub fn to_json(&self) -> Value

Serializes this error as a structured diagnostic JSON object.

impl QueryError

pub fn triage_summary(&self) -> TriageSummary

Builds a compact triage summary for this error.

Structured context takes precedence over facts. The error’s own query id and boundary node id are used first, and the query_id and node_id facts fill in only when the context lacks them. The compiled_task_id fact is used whenever it is present.

Trait Implementations

impl Clone for QueryError

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for QueryError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for QueryError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for QueryError

fn source(&self) -> Option<&(dyn StdError + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.