diff --git a/arrow-flight/src/lib.rs b/arrow-flight/src/lib.rs index 7aebd92e2ba2..a80358ff00c5 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] 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..df828c9c08af 100644 --- a/arrow-flight/src/sql/mod.rs +++ b/arrow-flight/src/sql/mod.rs @@ -15,6 +15,27 @@ // 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 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. [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; @@ -90,8 +111,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};