From b3841e14c29842381c6b6297b2abda4757195800 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Mon, 3 Apr 2023 15:04:09 -0400 Subject: [PATCH 1/4] Add FlightSQL module docs and links to `arrow-flight` crates --- arrow-flight/src/lib.rs | 5 +++++ arrow-flight/src/sql/client.rs | 2 ++ arrow-flight/src/sql/mod.rs | 24 ++++++++++++++++++++++-- arrow-flight/src/sql/server.rs | 2 ++ 4 files changed, 31 insertions(+), 2 deletions(-) diff --git a/arrow-flight/src/lib.rs b/arrow-flight/src/lib.rs index 7aebd92e2ba2..d74ee4a5e1bc 100644 --- a/arrow-flight/src/lib.rs +++ b/arrow-flight/src/lib.rs @@ -30,6 +30,11 @@ //! //! 2. Low level [tonic] generated [`flight_service_client`] and //! [`flight_service_server`]. +//! +//! 3. Experimental support for [Flight SQL]rec in [`sql`]. Requires the +//! `flight-sql-experimental` feature of this crate to be activated. +//! +//! [Flight SQL]: https://arrow.apache.org/docs/format/FlightSql.html #![allow(rustdoc::invalid_html_tags)] use arrow_ipc::{convert, writer, writer::EncodedData, writer::IpcWriteOptions}; diff --git a/arrow-flight/src/sql/client.rs b/arrow-flight/src/sql/client.rs index a8868fba1867..d96c90afa806 100644 --- a/arrow-flight/src/sql/client.rs +++ b/arrow-flight/src/sql/client.rs @@ -15,6 +15,8 @@ // specific language governing permissions and limitations // under the License. +//! A FlightSQL Client [`FlightSqlServiceClient`] + use base64::prelude::BASE64_STANDARD; use base64::Engine; use bytes::Bytes; diff --git a/arrow-flight/src/sql/mod.rs b/arrow-flight/src/sql/mod.rs index 2c26f2bf69b6..7a6ba9ad346e 100644 --- a/arrow-flight/src/sql/mod.rs +++ b/arrow-flight/src/sql/mod.rs @@ -15,6 +15,26 @@ // specific language governing permissions and limitations // under the License. +//! Support for execute SQL queries using [Apache Arrow] [Flight SQL]. +//! +//! [Flight SQL] is built on top of Arrow Flight RPC framework, by +//! defining specific message, encoded using the protobuf format, sent +//! in the +//! [`FlightDescriptor::cmd`](crate::FlightDescriptor::cmd) +//! field to [`FlightService`](crate::flight_service_server::FlightService) endpoints +//! such as +//! [`FlightService::get_flight_info`](crate::flight_service_server::FlightService::get_flight_info) +//! and [`FlightService::do_get`](crate::flight_service_server::FlightService::do_get) +//! +//! This module contains: +//! 1. The [tonic] generated protobuf definitions for FlightSQL messages such as [`CommandStatementQuery`] +//! 2. Helpers for for encoding and decoding such messages: [`Any`] and [`Command`] +//! 3. A [`FlightSqlServiceClient`](client::FlightSqlServiceClient) for interacting with FlightSQL servers. +//! 4. A [`FlightSqlService`](server::FlightSqlService) to help building FlightSQL servers from [`FlightService`](crate::flight_service_server::FlightService). +//! +//! [Flight SQL]: https://arrow.apache.org/docs/format/FlightSql.html +//! [Apache Arrow]: https://arrow.apache.org + use arrow_schema::ArrowError; use bytes::Bytes; use paste::paste; @@ -90,8 +110,8 @@ macro_rules! prost_message_ext { )* as_item! { - /// Helper to convert to/from protobuf [`Any`] - /// to a strongly typed enum. + /// Helper to convert to/from protobuf [`Any`] message + /// to a specific FlightSQL command message. /// /// # Example /// ```rust diff --git a/arrow-flight/src/sql/server.rs b/arrow-flight/src/sql/server.rs index b11fa3e3c3db..f25ddb13db99 100644 --- a/arrow-flight/src/sql/server.rs +++ b/arrow-flight/src/sql/server.rs @@ -15,6 +15,8 @@ // specific language governing permissions and limitations // under the License. +//! Helper trait [`FlightSqlService`] for implementing a [`FlightService`] that implements FlightSQL. + use std::pin::Pin; use crate::sql::{Any, Command}; From 84f2b099b5dd60af4399b555c30c84b1f003d8b9 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Mon, 3 Apr 2023 15:14:12 -0400 Subject: [PATCH 2/4] Updates --- arrow-flight/src/lib.rs | 2 +- arrow-flight/src/sql/mod.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/arrow-flight/src/lib.rs b/arrow-flight/src/lib.rs index d74ee4a5e1bc..a80358ff00c5 100644 --- a/arrow-flight/src/lib.rs +++ b/arrow-flight/src/lib.rs @@ -31,7 +31,7 @@ //! 2. Low level [tonic] generated [`flight_service_client`] and //! [`flight_service_server`]. //! -//! 3. Experimental support for [Flight SQL]rec in [`sql`]. Requires the +//! 3. Experimental support for [Flight SQL] in [`sql`]. Requires the //! `flight-sql-experimental` feature of this crate to be activated. //! //! [Flight SQL]: https://arrow.apache.org/docs/format/FlightSql.html diff --git a/arrow-flight/src/sql/mod.rs b/arrow-flight/src/sql/mod.rs index 7a6ba9ad346e..7cf191c1569b 100644 --- a/arrow-flight/src/sql/mod.rs +++ b/arrow-flight/src/sql/mod.rs @@ -27,7 +27,7 @@ //! and [`FlightService::do_get`](crate::flight_service_server::FlightService::do_get) //! //! This module contains: -//! 1. The [tonic] generated protobuf definitions for FlightSQL messages such as [`CommandStatementQuery`] +//! 1. The [prost] generated structs for FlightSQL messages such as [`CommandStatementQuery`] //! 2. Helpers for for encoding and decoding such messages: [`Any`] and [`Command`] //! 3. A [`FlightSqlServiceClient`](client::FlightSqlServiceClient) for interacting with FlightSQL servers. //! 4. A [`FlightSqlService`](server::FlightSqlService) to help building FlightSQL servers from [`FlightService`](crate::flight_service_server::FlightService). From 9cc49290b6bb92cf8160da05d54b2a37808903e1 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Tue, 4 Apr 2023 15:12:15 -0400 Subject: [PATCH 3/4] Update arrow-flight/src/sql/mod.rs Co-authored-by: Raphael Taylor-Davies <1781103+tustvold@users.noreply.github.com> --- arrow-flight/src/sql/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/arrow-flight/src/sql/mod.rs b/arrow-flight/src/sql/mod.rs index 7cf191c1569b..0ce84cb4b145 100644 --- a/arrow-flight/src/sql/mod.rs +++ b/arrow-flight/src/sql/mod.rs @@ -18,7 +18,7 @@ //! Support for execute SQL queries using [Apache Arrow] [Flight SQL]. //! //! [Flight SQL] is built on top of Arrow Flight RPC framework, by -//! defining specific message, encoded using the protobuf format, sent +//! defining specific messages, encoded using the protobuf format, sent //! in the //! [`FlightDescriptor::cmd`](crate::FlightDescriptor::cmd) //! field to [`FlightService`](crate::flight_service_server::FlightService) endpoints From 7c8f3e17223b09a07fdd367d3ebcd45fe755e143 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Tue, 4 Apr 2023 15:18:06 -0400 Subject: [PATCH 4/4] Copy editing and improve links --- arrow-flight/src/sql/mod.rs | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/arrow-flight/src/sql/mod.rs b/arrow-flight/src/sql/mod.rs index 0ce84cb4b145..df828c9c08af 100644 --- a/arrow-flight/src/sql/mod.rs +++ b/arrow-flight/src/sql/mod.rs @@ -18,23 +18,24 @@ //! Support for execute SQL queries using [Apache Arrow] [Flight SQL]. //! //! [Flight SQL] is built on top of Arrow Flight RPC framework, by -//! defining specific messages, encoded using the protobuf format, sent -//! in the -//! [`FlightDescriptor::cmd`](crate::FlightDescriptor::cmd) -//! field to [`FlightService`](crate::flight_service_server::FlightService) endpoints -//! such as -//! [`FlightService::get_flight_info`](crate::flight_service_server::FlightService::get_flight_info) -//! and [`FlightService::do_get`](crate::flight_service_server::FlightService::do_get) +//! defining specific messages, encoded using the protobuf format, +//! sent in the[`FlightDescriptor::cmd`] field to [`FlightService`] +//! endpoints such as[`get_flight_info`] and [`do_get`]. //! //! This module contains: -//! 1. The [prost] generated structs for FlightSQL messages such as [`CommandStatementQuery`] -//! 2. Helpers for for encoding and decoding such messages: [`Any`] and [`Command`] -//! 3. A [`FlightSqlServiceClient`](client::FlightSqlServiceClient) for interacting with FlightSQL servers. -//! 4. A [`FlightSqlService`](server::FlightSqlService) to help building FlightSQL servers from [`FlightService`](crate::flight_service_server::FlightService). +//! 1. [prost] generated structs for FlightSQL messages such as [`CommandStatementQuery`] +//! 2. Helpers for encoding and decoding FlightSQL messages: [`Any`] and [`Command`] +//! 3. A [`FlightSqlServiceClient`] for interacting with FlightSQL servers. +//! 4. A [`FlightSqlService`] to help building FlightSQL servers from [`FlightService`]. //! //! [Flight SQL]: https://arrow.apache.org/docs/format/FlightSql.html //! [Apache Arrow]: https://arrow.apache.org - +//! [`FlightDescriptor::cmd`]: crate::FlightDescriptor::cmd +//! [`FlightService`]: crate::flight_service_server::FlightService +//! [`get_flight_info`]: crate::flight_service_server::FlightService::get_flight_info +//! [`do_get`]: crate::flight_service_server::FlightService::do_get +//! [`FlightSqlServiceClient`]: client::FlightSqlServiceClient +//! [`FlightSqlService`]: server::FlightSqlService use arrow_schema::ArrowError; use bytes::Bytes; use paste::paste;