apache / apache/arrow

[Docs][FlightRPC] Document Flight error status mappings

Open
#34,544 4 comments 1 reaction 0 assignees View on GitHub
Component: Documentation Component: FlightRPC Type: enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.