panbingkun commented on code in PR #44902: URL: https://github.com/apache/spark/pull/44902#discussion_r1568713831
########## common/utils/src/main/resources/error/README.md: ########## @@ -1,77 +1,132 @@ -# Guidelines +# Guidelines for Throwing User-Facing Errors -To throw a standardized user-facing error or exception, developers should specify the error class, a SQLSTATE, -and message parameters rather than an arbitrary error message. +To throw a user-facing error or exception, developers should specify a standardized SQLSTATE, an error condition, and message parameters rather than an arbitrary error message. + +This guide will describe how to do this. + +## Error Hierarchy and Terminology + +The error hierarchy is as follows: +1. Error state / SQLSTATE +2. Error condition +3. Error sub-condition + +The error state / SQLSTATE itself is comprised of two parts: +1. Error class +2. Error sub-class + +Acceptable values for these various error parts are defined in the following files: +* `error-classes.json` +* `error-states.json` +* `error-conditions.json` + +The terms error class, state, and condition come from the SQL standard. + +### Illustrative Example +* Error state / SQLSTATE: `42K01` (Class: `42`; Sub-class: `K01`) + * Error condition: `DATATYPE_MISSING_SIZE` + * Error condition: `INCOMPLETE_TYPE_DEFINITION` + * Error sub-condition: `ARRAY` + * Error sub-condition: `MAP` + * Error sub-condition: `STRUCT` +* Error state / SQLSTATE: `42604` (Class: `42`; Sub-class: `604`) + * Error condition: `INVALID_ESCAPE_CHAR` + * Error condition: `AS_OF_JOIN` + * Error sub-condition: `TOLERANCE_IS_NON_NEGATIVE` + * Error sub-condition: `TOLERANCE_IS_UNFOLDABLE` + +### Inconsistent Use of the Term "Error Class" + +Unfortunately, we have historically used the term "error class" inconsistently to refer both to a proper error class like `42` and also to an error condition like `DATATYPE_MISSING_SIZE`. + +Fixing this will require renaming `SparkException.errorClass` to `SparkException.errorCondition` and making similar changes to `ErrorClassesJsonReader` and other parts of the codebase. We will address this in [SPARK-47429]. Until that is complete, we will have to live with the fact that a string like `DATATYPE_MISSING_SIZE` is called an "error condition" in our user-facing documentation but an "error class" in the code. + +For more details, please see [SPARK-46810][SPARK-46810]. Review Comment: Why do we need to write `[SPARK-46810]` twice here? Is it because of the special syntax for `markdown`? Or do we actually want to write: `[SPARK-46810]` `[SPARK-47429]` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
