v0.14 to v1 Error Handling Migration
| If there are inaccuracies discovered with this documentation, please submit a GitHub issue. |
This guide is intended to cover the differences between the error handling mechanism in partiql-lang-kotlin v0.14 and partiql-lang-kotlin v1.
Major Changes
Unified Exception Across PartiQL Components
Unified error handling is introduced in the PartiQL v1 system. PRuntimeException will be thrown from all components in the PartiQL system to trap any errors or warnings. PRuntimeException wraps a PError which exposes information for users to write high quality error messages and allows custom and robust error handling.
As mentioned above, the PError exposes information about the error from the PartiQL system. Specifically,
-
code()- Returns the enumerated error code. All possible error codes are defined as static final fields in the PError class (e.g., PError.DIVISION_BY_ZERO, PError.ALWAYS_MISSING, PError.FEATURE_NOT_SUPPORTED). -
kind- A PErrorKind property describes the classification associated with the error. It represents the different phases of the error defined by PErrorKind (e.g., SYNTAX, SEMANTIC , EXECUTION ). -
location- A SourceLocation property indicates the location where the error originates. The property is mostly used for parser and may be null for other components. -
severity- A Severity property indicates the error level:-
Severity.ERROR- Critical errors that you should consider aborting the processing. -
Severity.WARNING- Non-critical issues that allow continued processing, but be aware of the warning to proceed.
-
-
Additional Properties- There may be additional context-specific properties accessible via:-
getOrNull- Returns the error’s property with the corresponding key. -
getListOrNull- This is a type-safe way to get a property that is expected to be a List whose elements are of the same type.
-
Default Error Handling
PartiQLParser is designed to make sure the syntax of the input is correct and can be parsed into AST correctly. Thus, the parser usually does not throw warnings. Instead, it aborts the parsing process by throwing PRuntimeException once it encounters the first error.
PartiQLPlanner is designed to tolerate most errors and warnings so that users can decide actions on those issues later. It is highly recommended that you implement a custom error listener to inspect those errors and warnings. However, in certain circumstances, the planner may still throw PRuntimeException, e.g., for unsupported statements.
In the compilation and execution phases, PartiQL also throws PRuntimeException whenever it encounters an error.
Custom Error Handling
You can now register a custom PErrorListener in the context of major PartiQL components (PartiQLParser, PartiQLPlanner, or PartiQLCompiler). It allows you to inspect each PError and decide the action to take on errors and warnings. For instance, you may treat all warnings as errors, suppress all warnings, delay the error handling, or throw a custom exception with an error message.
Please note:
-
For the execution of compiled statements, PartiQL does not send PError to a custom PErrorListener. It instead immediately throws a PRuntimeException directly.
-
If you choose to delay the error handling, each PartiQL component still returns an object such as PartiQLParser.Result and PartiQLPlanner.Result. The result object may be incorrect or incomplete due to errors or warnings. You may need to discard the result or proceed with awareness of the warnings.
Examples
To use the Error Handling APIs, we’ve provided more examples within the partiql-lang-kotlin library’s migration guide
Included in the code examples are how to