Minor: add more FlightSQL docs to arrow-flight crates

apache · Apr 3, 2023 · 4a34d30 · 4a34d30
1 parent 2fa3542
commit 4a34d30
Show file tree

Hide file tree

Showing 4 changed files with 31 additions and 2 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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};