ARROW-14698: [Docs][FlightRPC] Add API docs for Flight SQL #12616
Conversation
Rendered (new protocol docs section)
The API docs are a little too large to render. |
|
CC @jduo if you'd like to take a look |
cpp/src/arrow/flight/sql/server.h
Outdated
| @@ -33,113 +33,143 @@ namespace arrow { | |||
| namespace flight { | |||
| namespace sql { | |||
|
|
|||
| /// \defgroup flight-sql-protocol-messages Flight SQL Protocol Messages | |||
| /// POD wrappers for various protocol messages, used to avoid exposing | |||
There was a problem hiding this comment.
Spell out "POD" in full (or use an equivalent term)?
docs/source/cpp/api/flightsql.rst
Outdated
|
|
||
| .. doxygentypedef:: arrow::flight::sql::SqlInfoResultMap | ||
|
|
||
| .. doxygenenum:: arrow::flight::sql::SqlInfoOptions::SqlInfo |
There was a problem hiding this comment.
Perhaps you want to define a doxygen group encompassing these typedefs and enums?
| @@ -0,0 +1,26 @@ | |||
| %% Licensed to the Apache Software Foundation (ASF) under one | |||
There was a problem hiding this comment.
For the record, how are the corresponding SVGs generated? (do you want to add a comment as to that?)
| participant Server | ||
| Client->>Server: GetFlightInfo(CommandStatementQuery) | ||
| Server->>Client: FlightInfo{…Ticket…} | ||
| loop for each Ticket in FlightInfo |
There was a problem hiding this comment.
Is this the case? I though all returned tickets were equivalent and only one of them needed to be fetched, am I misremembering?
There was a problem hiding this comment.
Ah yes, this should be "for each FlightEndpoint in FlightInfo"
cpp/src/arrow/flight/sql/types.h
Outdated
| * The possible values are listed in | ||
| * `arrow.flight.protocol.sql.SqlSupportedCaseSensitivity`. | ||
| */ | ||
| /// Retrieves a uint32 value representing the enu uint32 ordinal |
cpp/src/arrow/flight/sql/types.h
Outdated
| /// - return 2 (0b10) => [SQL_UNION_ALL]; | ||
| /// - return 3 (0b11) => [SQL_UNION, SQL_UNION_ALL]. | ||
| /// | ||
| /// Valid SQL positioned commands are described under |
| Client->>Server: GetFlightInfo(CommandGetTables) | ||
| Server->>Client: FlightInfo{…Ticket…} | ||
| Client->>Server: DoGet(Ticket) | ||
| Server->>Client: stream of FlightData |
|
Hey @lidavidm ! uint32 values are not returned by CommandGetSqlInfo, just int64 ones. Is it better to address this in another PR or in this one? Thanks! |
|
I think if it's just clarifications/fixes, we can address them here. |
|
Thank you all for the suggestions, I've cleaned up the reST markup a bit, tweaked the charts, and fixed up the types in the Protobuf and C++ header |
|
Any final comments? We can open another issue to address anything else we see |
|
Benchmark runs are scheduled for baseline = b285350 and contender = dd52b38. dd52b38 is a master commit associated with this PR. Results will be available as each benchmark for each run completes. |
This improves the protocol docs and adds C++ API documentation. Java already has Javadocs so this PR doesn't touch anything there. Closes apache#12616 from lidavidm/arrow-14698 Authored-by: David Li <li.davidm96@gmail.com> Signed-off-by: David Li <li.davidm96@gmail.com>
This improves the protocol docs and adds C++ API documentation. Java already has Javadocs so this PR doesn't touch anything there.