Documentation
¶
Overview ¶
Package uerr is ursus's error type.
Error message quality is a feature, not a courtesy. A dataframe library is used interactively; the difference between
unknown column
and
ursus: select: unknown column "reveune" did you mean: "revenue"? available: id, ts, revenue, region, units
is the difference between a library people enjoy and one they tolerate. Every error that names a column MUST list the available columns and offer near matches; the helpers here make that the path of least resistance.
Index ¶
- Variables
- func Annotate(err error, op, node string) error
- func NearMatches(want string, candidates []string, n int) []string
- type Error
- func DuplicateColumn(op, name string, firstAt, secondAt int) *Error
- func Internalf(format string, args ...any) *Error
- func New(kind Kind, op, format string, args ...any) *Error
- func UnknownColumn(op, name string, available []string) *Error
- func Wrap(err error, kind Kind, op, format string, args ...any) *Error
- type Kind
Constants ¶
This section is empty.
Variables ¶
var ( ErrInternal error = &kindSentinel{KindInternal} ErrSchema error = &kindSentinel{KindSchema} ErrType error = &kindSentinel{KindType} ErrValue error = &kindSentinel{KindValue} ErrUnsupported error = &kindSentinel{KindUnsupported} ErrIO error = &kindSentinel{KindIO} ErrResource error = &kindSentinel{KindResource} )
Sentinels for errors.Is. Use as: errors.Is(err, uerr.ErrSchema).
Functions ¶
func Annotate ¶
Annotate applies WithOp/WithNode to err if it is an *Error, and otherwise leaves it alone. Plan nodes call this as errors propagate outward.
func NearMatches ¶
NearMatches returns up to n candidates that are plausible typos of want, best first.
Two signals, because they catch different mistakes:
- Edit distance catches transpositions and single-character slips ("reveune" → "revenue"), which are what people actually type.
- Case-insensitive equality and prefix containment catch the other common failure, which is not a typo at all but a naming-convention mismatch ("userid" → "user_id", "TS" → "ts").
The distance budget scales with length: one edit for short names, up to three for long ones. A fixed budget either floods short-name suggestions or misses long-name typos.
Types ¶
type Error ¶
type Error struct {
Kind Kind
Op string // "select", "filter", "with_columns"
Msg string // the one-line statement of what is wrong
Node string // plan node attribution, e.g. "Project#3"; set by WithNode
Hints []string // one per line, indented under Msg
Err error // wrapped cause, if any
}
Error is ursus's error type.
Op is the user-facing operation ("select", "filter", "cast"), not the Go function name. Node is set by the plan layer as the error propagates outward, so a user learns *where* in their query the failure was — something a bare error string cannot express.
func DuplicateColumn ¶
DuplicateColumn reports a name collision, naming both positions.
func UnknownColumn ¶
UnknownColumn is the single most common error in a dataframe library, so it has a dedicated constructor that always produces the full diagnostic.
type Kind ¶
type Kind uint8
Kind classifies an error so callers can branch without string matching.
const ( // KindInternal is a bug in ursus. Users should never legitimately see one. KindInternal Kind = iota // KindSchema is an unknown, duplicate, or ambiguous column. KindSchema // KindType is a dtype mismatch: an operation not defined for the given types. KindType // KindValue is a bad literal, an out-of-range cast, an unparseable pattern. KindValue // KindUnsupported is a well-formed request ursus cannot yet serve. KindUnsupported // KindIO is a failure reading or writing a data source. KindIO // KindResource is a limit ursus refused to exceed rather than a request it // could not understand: the query is well-formed and would have worked with // more memory or more spill space. // // It is its own kind because it is the one class of failure where the right // response is to change a knob and retry, and a caller should be able to // detect that without matching on a message. KindResource )
Source Files