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};