[Docs][FlightRPC] Document Flight error status mappings
- Dominant language
- C++
- Stars
- 17.1k
- Forks
- 4.3k
- Avg merge
- 3d 18h
- Merged PRs (30d)
- 91
Description
### Describe the enhancement requested
We should document which error statuses correspond to which other error statuses in different languages. There's a rough outline here:
Diagram (Arrow C++, Flight, gRPC, ADBC, DBAPI)
```mermaid
flowchart LR
subgraph Arrow
direction TB
ArrowOK[OK]
ArrowOutOfMemory[OutOfMemory]
ArrowKeyError[KeyError]
ArrowTypeError[TypeError]
ArrowInvalid[Invalid]
ArrowIOError[IOError]
ArrowCapacityError[CapacityError]
ArrowIndexError[IndexError]
ArrowCancelled[Cancelled]
ArrowUnknownError[UnknownError]
ArrowNotImplemented[NotImplemented]
ArrowSerializationError[SerializationError]
ArrowRError[RError]
ArrowCodeGenError[CodeGenError]
ArrowExpressionValidationError[ExpressionValidationError]
ArrowExecutionError[ExecutionError]
ArrowAlreadyExists[AlreadyExists]
end
subgraph Flight
direction TB
FlightOk[Ok]
FlightUnknown[Unknown]
FlightInternal[Internal]
FlightInvalidArgument[InvalidArgument]
FlightTimedOut[TimedOut]
FlightNotFound[NotFound]
FlightAlreadyExists[AlreadyExists]
FlightCancelled[Cancelled]
FlightUnauthenticated[Unauthenticated]
FlightUnauthorized[Unauthorized]
FlightUnimplemented[Unimplemented]
FlightUnavailable[Unavailable]
end
subgraph gRPC
direction TB
GrpcOK[OK]
GrpcCANCELLED[CANCELLED]
GrpcUNKNOWN[UNKNOWN]
GrpcINVALID_ARGUMENT[INVALID_ARGUMENT]
GrpcDEADLINE_EXCEEDED[DEADLINE_EXCEEDED]
GrpcNOT_FOUND[NOT_FOUND]
GrpcALREADY_EXISTS[ALREADY_EXISTS]
GrpcPERMISSION_DENIED[PERMISSION_DENIED]
GrpcRESOURCE_EXHAUSTED[RESOURCE_EXHAUSTED]
GrpcFAILED_PRECONDITION[FAILED_PRECONDITION]
GrpcABORTED[ABORTED]
GrpcOUT_OF_RANGE[OUT_OF_RANGE]
GrpcUNIMPLEMENTED[UNIMPLEMENTED]
GrpcINTERNAL[INTERNAL]
GrpcUNAVAILABLE[UNAVAILABLE]
GrpcDATA_LOSS[DATA_LOSS]
GrpcUNAUTHENTICATED[UNAUTHENTICATED]
end
subgraph ADBC
direction TB
AdbcOK[OK]
AdbcUNKNOWN[UNKNOWN]
AdbcNOT_IMPLEMENTED[NOT_IMPLEMENTED]
AdbcNOT_FOUND[NOT_FOUND]
AdbcALREADY_EXISTS[ALREADY_EXISTS]
AdbcINVALID_ARGUMENT[INVALID_ARGUMENT]
AdbcINVALID_STATE[INVALID_STATE]
AdbcINVALID_DATA[INVALID_DATA]
AdbcINTEGRITY[INTEGRITY]
AdbcINTERNAL[INTERNAL]
AdbcIO[IO]
AdbcCANCELLED[CANCELLED]
AdbcTIMEOUT[TIMEOUT]
AdbcUNAUTHENTICATED[UNAUTHENTICATED]
AdbcUNAUTHORIZED[UNAUTHORIZED]
end
subgraph DBAPI
direction TB
DbapiNoError["(no error)"]
DbapiError[Error]
DbapiDataError[DataError]
DbapiOperationalError[OperationalError]
DbapiIntegrityError[IntegrityError]
DbapiInternalError[InternalError]
DbapiProgrammingError[ProgrammingError]
DbapiNotSupportedError[NotSupportedError]
end
ArrowOK --> FlightOk
ArrowOutOfMemory --> FlightUnknown
ArrowKeyError --> FlightNotFound
ArrowInvalid --> FlightInvalidArgument
ArrowCancelled --> FlightCancelled
ArrowNotImplemented --> FlightUnimplemented
ArrowAlreadyExists --> FlightAlreadyExists
ArrowTypeError --> FlightUnknown
ArrowIOError --> FlightUnknown
ArrowCapacityError --> FlightUnknown
ArrowIndexError --> FlightUnknown
ArrowUnknownError --> FlightUnknown
ArrowSerializationError --> FlightUnknown
ArrowRError --> FlightUnknown
ArrowCodeGenError --> FlightUnknown
ArrowExpressionValidationError --> FlightUnknown
ArrowExecutionError --> FlightUnknown
FlightOk --> GrpcOK
FlightUnknown --> GrpcUNKNOWN
FlightInternal --> GrpcINTERNAL
FlightInvalidArgument --> GrpcINVALID_ARGUMENT
FlightTimedOut --> GrpcDEADLINE_EXCEEDED
FlightNotFound --> GrpcNOT_FOUND
FlightAlreadyExists --> GrpcALREADY_EXISTS
FlightCancelled --> GrpcCANCELLED
FlightUnauthenticated --> GrpcUNAUTHENTICATED
FlightUnauthorized --> GrpcPERMISSION_DENIED
FlightUnimplemented --> GrpcUNIMPLEMENTED
FlightUnavailable --> GrpcUNAVAILABLE
GrpcOK --> AdbcOK
GrpcCANCELLED --> AdbcCANCELLED
GrpcUNKNOWN --> AdbcUNKNOWN
GrpcINVALID_ARGUMENT --> AdbcINVALID_ARGUMENT
GrpcDEADLINE_EXCEEDED --> AdbcTIMEOUT
GrpcNOT_FOUND --> AdbcNOT_FOUND
GrpcALREADY_EXISTS --> AdbcALREADY_EXISTS
GrpcPERMISSION_DENIED --> AdbcUNAUTHORIZED
GrpcRESOURCE_EXHAUSTED --> AdbcUNKNOWN
GrpcFAILED_PRECONDITION --> AdbcUNKNOWN
GrpcABORTED --> AdbcUNKNOWN
GrpcOUT_OF_RANGE --> AdbcUNKNOWN
GrpcUNIMPLEMENTED --> AdbcNOT_IMPLEMENTED
GrpcINTERNAL --> AdbcINTERNAL
GrpcUNAVAILABLE --> AdbcIO
GrpcDATA_LOSS --> AdbcUNKNOWN
GrpcUNAUTHENTICATED --> AdbcUNAUTHENTICATED
AdbcOK --> DbapiNoError
AdbcUNKNOWN --> DbapiError
AdbcNOT_IMPLEMENTED --> DbapiNotSupportedError
AdbcNOT_FOUND --> DbapiError
AdbcALREADY_EXISTS --> DbapiProgrammingError
AdbcINVALID_ARGUMENT --> DbapiProgrammingError
AdbcINVALID_STATE --> DbapiProgrammingError
AdbcINVALID_DATA --> DbapiDataError
AdbcINTEGRITY --> DbapiIntegrityError
AdbcINTERNAL --> DbapiInternalError
AdbcIO --> DbapiOperationalError
AdbcCANCELLED --> DbapiOperationalError
AdbcTIMEOUT --> DbapiOperationalError
AdbcUNAUTHENTICATED --> DbapiProgrammingError
AdbcUNAUTHORIZED --> DbapiProgrammingError
```
- Java/Python should be included too
- We should document the semantics of each Flight error status (similar to how gRPC does it)
- We should consider adding an extra error code for Flight to indicate server-internal errors that are not unexpected (as INTERNAL is), possibly like gRPC FAILED_PRECONDITION or ABORTED (I don't think this is a format change?)
### Component(s)
Documentation, FlightRPC
Contributor guide
Research direction
No target files or tests are named. Start from the rough Arrow C++, Flight, gRPC, ADBC, and DBAPI mapping in the issue, then identify the project's existing Flight documentation entry point. Done means documenting cross-language status mappings and the semantics of each Flight status, including Java and Python, while clearly resolving or scoping the proposed additional error code.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp, grpc, java, python
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100