Enum SqlError 

pub enum SqlError {
    Parse {
        detail: String,
    },
    UnknownTable {
        name: String,
    },
    UndefinedFunction {
        name: String,
    },
    SequencePerRowUnsupported {
        name: String,
    },
    SearchFunctionOutsideSearch {
        name: String,
    },
    UndefinedObject {
        kind: &'static str,
        name: String,
    },
    ObjectNotInPrerequisiteState {
        object: String,
        detail: String,
    },
    WrongObjectType {
        detail: String,
    },
    UnknownColumn {
        table: String,
        column: String,
    },
    TextColumn {
        function: String,
        collection: String,
        column: String,
        fault: TextColumnFault,
    },
    AmbiguousColumn {
        column: String,
    },
    TypeMismatch {
        detail: String,
    },
    VectorElementNotNumeric {
        column: String,
        dim: usize,
        element: String,
    },
    Arity {
        detail: String,
    },
    DivisionByZero,
    DataException {
        detail: String,
    },
    InvalidLimitValue {
        clause: &'static str,
        value: String,
    },
    ConstantOverflow {
        detail: String,
    },
    NumericLiteralOutOfRange {
        literal: String,
    },
    IntegerOutOfRange {
        column: String,
        value: i64,
        declared_type: &'static str,
    },
    FloatOutOfRange {
        column: String,
        value: f64,
        declared_type: &'static str,
    },
    DecimalOutOfRange {
        column: String,
        source: DecimalOutOfRange,
    },
    Unsupported {
        detail: String,
    },
    UnevaluableDefault {
        column: String,
        expr: String,
    },
    SetvalInColumnDefault {
        column: String,
    },
    InvalidFunction {
        detail: String,
    },
    InvalidWindowFrame {
        detail: String,
    },
    MissingField {
        field: String,
        context: String,
    },
    InsertColumnArityMismatch {
        collection: String,
        given: usize,
        declared: usize,
    },
    PositionalKvInsertUnsupported {
        collection: String,
    },
    RetryableSchemaChanged {
        descriptor: String,
    },
    InvalidIdentifier {
        name: String,
        reason: &'static str,
    },
    ReservedIdentifier {
        name: String,
        reason: &'static str,
    },
    UnsupportedConstraint {
        feature: String,
        hint: String,
    },
    ConflictingEngineClause {
        with_engine: String,
        suffix_engine: String,
    },
    InvalidRecursiveSetOp {
        op: String,
    },
    InvalidRecursiveSelfRef {
        cte_name: String,
        reason: String,
    },
    RecursiveColumnMismatch {
        cte_name: String,
        anchor_cols: usize,
        declared_cols: usize,
    },
    DuplicateRecursiveColumn {
        cte_name: String,
        column: String,
    },
    RecursionDepthExceeded {
        cte_name: String,
        max_depth: usize,
    },
    CollectionDeactivated {
        name: String,
        retention_expires_at_ns: u64,
        undrop_hint: String,
    },
}

Errors produced during SQL parsing, resolution, or planning.

Variants

Parse

Fields

detail: String

UnknownTable

Fields

name: String

UndefinedFunction

A function call in an expression names no scalar, aggregate, or window function registered in the FunctionRegistry. Caught at plan time in the resolver so the whole statement is rejected instead of the call silently evaluating to NULL for every row at runtime.

Fields

name: String

SequencePerRowUnsupported

A sequence accessor appeared in a row-scope clause the row evaluator runs: WHERE, ORDER BY, GROUP BY, HAVING, JOIN ON, SET, an aggregate or window argument, or a subquery.

Rendered as SQLSTATE 0A000 (feature_not_supported). Constant contexts evaluate the call for real: a FROM-less SELECT, a column DEFAULT, a VALUES list. A SELECT-list item over a FROM relation is evaluated by the Control Plane once per output row. The refusal keeps every other per-row call from reaching the row evaluator, which has no sequence state and would return NULL for every row.

Fields

name: String

SearchFunctionOutsideSearch

An index-owned search function (bm25_score, text_match, rrf_score, sparse_score, …) sits in a position the row evaluator runs: the planner could not lower it into its search plan. The function reads a search index and has no per-row value.

Rendered as SQLSTATE 0A000 (feature_not_supported).

Fields

name: String

UndefinedObject

A statement names a database object that does not exist — a sequence, most commonly. Distinct from SqlError::UndefinedFunction: the function exists, the object it names does not. PostgreSQL rejects the same input with SQLSTATE 42704 (undefined_object).

Fields

kind: &'static str

name: String

ObjectNotInPrerequisiteState

An object exists but a prerequisite step has not run, such as currval before this session called nextval. PostgreSQL rejects the same input with SQLSTATE 55000 (object_not_in_prerequisite_state).

Fields

object: String

detail: String

WrongObjectType

A statement the named object’s kind does not take, such as a write to a read-only continuous aggregate. PostgreSQL rejects the same input with SQLSTATE 42809 (wrong_object_type).

Fields

detail: String

UnknownColumn

Fields

table: String

column: String

TextColumn

The column argument of text_match / bm25_score cannot serve a full-text search. fault names why and carries the SQLSTATE.

Fields

function: String

collection: String

column: String

fault: TextColumnFault

AmbiguousColumn

Fields

column: String

TypeMismatch

Fields

detail: String

VectorElementNotNumeric

An element of an array bound for a declared VECTOR(dim) column is not a number. Rendered as SQLSTATE 42804 (datatype_mismatch). element names the refused element’s kind, and its text for a string.

Fields

column: String

dim: usize

element: String

Arity

A statement lists a different number of targets than expressions, such as an INSERT whose target column list does not match its SELECT list.

Fields

detail: String

DivisionByZero

A constant expression divided by zero at plan time. Distinct from the folder declining to fold: the expression was constant and evaluating it failed, so the statement must raise rather than yield NULL.

DataException

A constant function call received an argument it cannot compute on: vectors of different dimensions, an argument of the wrong type, a malformed JSONPath. Same distinction as SqlError::DivisionByZero. Rendered as SQLSTATE 22000 (data_exception).

Fields

detail: String

InvalidLimitValue

A LIMIT, OFFSET, or FETCH FIRST clause resolved to a value outside [0, usize::MAX], or to an expression the planner cannot read as a literal. PostgreSQL rejects the same input with SQLSTATE 2201W.

Fields

clause: &'static str

value: String

ConstantOverflow

A constant expression overflowed at plan time. Same distinction as SqlError::DivisionByZero.

Fields

detail: String

NumericLiteralOutOfRange

An integer literal past the exact numeric range (the 96-bit Decimal mantissa). Rounding it to a float would store another number than the one written. PostgreSQL rejects an out-of-range numeric with SQLSTATE 22003.

Fields

literal: String

IntegerOutOfRange

A write supplied an integer wider than the column’s declared type.

nodedb stores every integer as an i64, so this is not a storage limit — it is the constraint that makes the column’s advertised wire type honest. A column declared INTEGER reports OID 23, and a pgwire client reading it in binary format decodes exactly four bytes; letting a wider value in would mean either truncating it on read or lying about the type. PostgreSQL rejects the same write with the same message.

Fields

column: String

value: i64

declared_type: &'static str

FloatOutOfRange

A write supplied a finite float that overflows to infinity when narrowed to the column’s declared REAL width.

Narrowing an f64 to f32 normally rounds — 1.1 becoming 1.10000002 is correct PostgreSQL real behaviour, never an error — so this is not the float mirror of SqlError::IntegerOutOfRange’s full-range check. The single case rejected is a finite value beyond f32’s range, which would otherwise silently become Infinity. PostgreSQL rejects the same write with the same message.

Fields

column: String

value: f64

declared_type: &'static str

DecimalOutOfRange

A write supplied a decimal whose rounded integer part has more digits than the column’s declared DECIMAL(p,s) holds. PostgreSQL refuses the same write with SQLSTATE 22003.

Fields

column: String

source: DecimalOutOfRange

Unsupported

Fields

detail: String

UnevaluableDefault

A declared column DEFAULT the server cannot evaluate to a value.

The column is never omitted instead. A DEFAULT that disappears stores NULL where the declaration promised a value, and nothing reports it.

Fields

column: String

expr: String

SetvalInColumnDefault

setval appeared inside a column DEFAULT.

A DEFAULT runs once per row, so evaluating setval there will move the sequence’s position on every inserted row. PostgreSQL reports a function used in a context that forbids it as SQLSTATE 42601 (syntax_error), and this refusal carries the same code.

Fields

column: String

InvalidFunction

Fields

detail: String

InvalidWindowFrame

Fields

detail: String

MissingField

Fields

field: String

context: String

InsertColumnArityMismatch

A positional INSERT/UPSERT VALUES row (no explicit column list) supplied more values than the target collection has declared columns. Binding the overflow value(s) to a synthetic col{N} name would silently store them under an unaddressable column, so this is rejected rather than guessed at.

Fields

collection: String

given: usize

declared: usize

PositionalKvInsertUnsupported

A positional INSERT/UPSERT into a Key-Value collection supplied no explicit column list. The KV path splits key/value by matching column names against pk_col/"key"/"ttl", so without a column list there is no principled key/value split — binding positionally would silently write an empty-keyed, empty-valued row (all such rows collide). Rejected rather than guessed at, mirroring [InsertColumnArityMismatch].

Fields

collection: String

RetryableSchemaChanged

A descriptor the planner depends on is being drained by an in-flight DDL. Callers (pgwire handlers) should retry the whole statement after a short backoff. Propagated from SqlCatalogError::RetryableSchemaChanged.

Fields

descriptor: String

InvalidIdentifier

Identifier violates NodeDB’s canonical identifier rules.

Fields

name: String

reason: &'static str

ReservedIdentifier

Identifier is a NodeDB reserved keyword. Use a quoted identifier to bypass.

Fields

name: String

reason: &'static str

UnsupportedConstraint

An unsupported SQL constraint was used in a DDL statement.

Rendered as SQLSTATE 0A000 (feature_not_supported). The feature field names the constraint keyword and hint points to the NodeDB equivalent.

Fields

feature: String

hint: String

ConflictingEngineClause

Both a WITH (engine='...') clause and a trailing ENGINE = ... suffix were given on the same CREATE COLLECTION / CREATE TABLE statement, naming different engines.

Rendered as SQLSTATE 0A000 (feature_not_supported), matching the existing duplicate-axis rejection precedent for WITH (profile=...).

Fields

with_engine: String

suffix_engine: String

InvalidRecursiveSetOp

WITH RECURSIVE used a set operator other than UNION or UNION ALL.

Only UNION and UNION ALL are permitted in the recursive term of a WITH RECURSIVE CTE. INTERSECT and EXCEPT are rejected because they cannot guarantee termination in standard iterative evaluation.

Fields

op: String

InvalidRecursiveSelfRef

The recursive self-reference is absent, appears more than once, or appears inside a subquery, aggregate, or the nullable side of an outer join.

Fields

cte_name: String

reason: String

RecursiveColumnMismatch

The anchor SELECT produces a different number of columns than the column list declared on the CTE (or the recursive arm).

Fields

cte_name: String

anchor_cols: usize

declared_cols: usize

DuplicateRecursiveColumn

Two of the CTE’s columns carry the same name, either from a repeated entry in the declared column list or from two anchor items that infer the same output name. Rows are keyed by column name, so a duplicate drops one column’s values instead of returning both.

Fields

cte_name: String

column: String

RecursionDepthExceeded

The recursive CTE exceeded the configured max_recursion_depth.

This is a runtime error produced by the executor, not the planner.

Fields

cte_name: String

max_depth: usize

CollectionDeactivated

Collection is soft-deleted (within retention window). Propagated from SqlCatalogError::CollectionDeactivated; the pgwire layer renders this as sqlstate 42P01 with an UNDROP COLLECTION <name> hint in the message.

Fields

name: String

retention_expires_at_ns: u64

undrop_hint: String

Trait Implementations

impl Debug for SqlError

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

Formats the value using the given formatter.

impl Display for SqlError

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

Formats the value using the given formatter.

impl Error for SqlError

fn source(&self) -> Option<&(dyn Error + '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.

impl From<ExprParseError> for SqlError

fn from(e: ExprParseError) -> Self

Converts to this type from the input type.

impl From<ParserError> for SqlError

fn from(e: ParserError) -> Self

Converts to this type from the input type.

impl From<SqlCatalogError> for SqlError

fn from(e: SqlCatalogError) -> Self

Converts to this type from the input type.

impl PartialEq for SqlError

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for SqlError