From 2a3d64f87d55a3f8c6b49725e538631dd63515d9 Mon Sep 17 00:00:00 2001 From: Jiawei Zhao Date: Fri, 13 Nov 2026 23:47:39 +0800 Subject: [PATCH] feat(flight)!: expose prepared statement is_update Clients need the server's execution hint to choose the query or update path without inferring it from the result schema. BREAKING CHANGE: ActionCreatePreparedStatementResult gains is_update. Downstream struct literals must initialize this field, e.g. with None. CLOSES #10082 --- arrow-flight/examples/flight_sql_server.rs | 2 + .../src/sql/arrow.flight.protocol.sql.rs | 5 +++ arrow-flight/src/sql/client.rs | 41 +++++++++++++++++++ arrow-flight/tests/flight_sql_client.rs | 35 ++++++++++++++-- arrow-flight/tests/flight_sql_client_cli.rs | 1 + format/FlightSql.proto | 5 +++ 6 files changed, 86 insertions(+), 3 deletions(-) diff --git a/arrow-flight/examples/flight_sql_server.rs b/arrow-flight/examples/flight_sql_server.rs index 8419ff8dbc50..d61de1f2346d 100644 --- a/arrow-flight/examples/flight_sql_server.rs +++ b/arrow-flight/examples/flight_sql_server.rs @@ -657,6 +657,7 @@ impl FlightSqlService for FlightSqlServiceImpl { prepared_statement_handle: FAKE_HANDLE.into(), dataset_schema: schema_bytes, parameter_schema: Default::default(), // TODO: parameters + is_update: Some(false), }; Ok(res) } @@ -952,6 +953,7 @@ mod tests { auth_client(&mut client).await; let mut stmt = client.prepare("select 1;".to_string(), None).await.unwrap(); + assert_eq!(stmt.is_update(), Some(false)); let flight_info = stmt.execute().await.unwrap(); diff --git a/arrow-flight/src/sql/arrow.flight.protocol.sql.rs b/arrow-flight/src/sql/arrow.flight.protocol.sql.rs index 47a4cdaee5ce..65e4fe8998ee 100644 --- a/arrow-flight/src/sql/arrow.flight.protocol.sql.rs +++ b/arrow-flight/src/sql/arrow.flight.protocol.sql.rs @@ -497,6 +497,11 @@ pub struct ActionCreatePreparedStatementResult { /// schema of the expected parameters. It should be an IPC-encapsulated Schema, as described in Schema.fbs. #[prost(bytes = "bytes", tag = "3")] pub parameter_schema: ::prost::bytes::Bytes, + /// When set to true, the query should be executed with CommandPreparedStatementUpdate, + /// when set to false, the query should be executed with CommandPreparedStatementQuery. + /// If not set, the client can choose how to execute the query. + #[prost(bool, optional, tag = "4")] + pub is_update: ::core::option::Option, } /// /// Request message for the "ClosePreparedStatement" action on a Flight SQL enabled backend. diff --git a/arrow-flight/src/sql/client.rs b/arrow-flight/src/sql/client.rs index 3ef5487c594b..4f527b5c05f5 100644 --- a/arrow-flight/src/sql/client.rs +++ b/arrow-flight/src/sql/client.rs @@ -401,6 +401,7 @@ where prepared_result.prepared_statement_handle, dataset_schema, parameter_schema, + prepared_result.is_update, )) } @@ -491,6 +492,7 @@ pub struct PreparedStatement { handle: Bytes, dataset_schema: Schema, parameter_schema: Schema, + is_update: Option, } impl PreparedStatement @@ -505,6 +507,7 @@ where handle: impl Into, dataset_schema: Schema, parameter_schema: Schema, + is_update: Option, ) -> Self { PreparedStatement { flight_sql_client: flight_client, @@ -512,6 +515,7 @@ where handle: handle.into(), dataset_schema, parameter_schema, + is_update, } } @@ -562,6 +566,43 @@ where Ok(&self.dataset_schema) } + /// Returns the server's indication of how this statement should be executed. + /// + /// `Some(true)` indicates [`Self::execute_update`], `Some(false)` indicates + /// [`Self::execute`], and `None` means the server did not provide this information. + /// + /// When the field is absent, the caller chooses an execution method based on + /// its knowledge of the statement. This example falls back to query execution + /// because it prepares a `SELECT` statement. + /// + /// ```no_run + /// # use arrow_flight::error::FlightError; + /// # use arrow_flight::sql::client::FlightSqlServiceClient; + /// # use tonic::transport::Channel; + /// # async fn example(mut client: FlightSqlServiceClient) -> Result<(), FlightError> { + /// let mut statement = client.prepare("SELECT 1".to_string(), None).await?; + /// match statement.is_update() { + /// Some(true) => { + /// let affected_rows = statement.execute_update().await?; + /// println!("{affected_rows} rows affected"); + /// } + /// Some(false) => { + /// let flight_info = statement.execute().await?; + /// println!("{flight_info:?}"); + /// } + /// None => { + /// // The application knows this statement returns a result set. + /// let flight_info = statement.execute().await?; + /// println!("{flight_info:?}"); + /// } + /// } + /// # Ok(()) + /// # } + /// ``` + pub fn is_update(&self) -> Option { + self.is_update + } + /// Set a RecordBatch that contains the parameters that will be bind. pub fn set_parameters(&mut self, parameter_binding: RecordBatch) -> Result<()> { self.parameter_binding = Some(parameter_binding); diff --git a/arrow-flight/tests/flight_sql_client.rs b/arrow-flight/tests/flight_sql_client.rs index cbea67b10e40..d5fa87046afd 100644 --- a/arrow-flight/tests/flight_sql_client.rs +++ b/arrow-flight/tests/flight_sql_client.rs @@ -5,6 +5,7 @@ mod common; use crate::common::fixture::TestFixture; +use crate::common::server::TestFlightServer; use crate::common::utils::make_primitive_batch; use arrow_array::RecordBatch; @@ -15,9 +16,10 @@ use arrow_flight::flight_service_server::FlightServiceServer; use arrow_flight::sql::client::FlightSqlServiceClient; use arrow_flight::sql::server::{FlightSqlService, PeekableFlightDataStream}; use arrow_flight::sql::{ - ActionBeginTransactionRequest, ActionBeginTransactionResult, ActionEndTransactionRequest, - CommandStatementIngest, EndTransaction, FallibleRequestStream, ProstMessageExt, - TableDefinitionOptions, TableExistsOption, TableNotExistOption, + ActionBeginTransactionRequest, ActionBeginTransactionResult, + ActionCreatePreparedStatementResult, ActionEndTransactionRequest, CommandStatementIngest, + EndTransaction, FallibleRequestStream, ProstMessageExt, TableDefinitionOptions, + TableExistsOption, TableNotExistOption, }; use arrow_flight::{Action, FlightData, FlightDescriptor}; use futures::{StreamExt, TryStreamExt}; @@ -28,6 +30,33 @@ use tokio::sync::Mutex; use tonic::{IntoStreamingRequest, Request, Status}; use uuid::Uuid; +#[tokio::test] +pub async fn test_prepare_is_update() { + let test_server = TestFlightServer::new(); + let fixture = TestFixture::new(test_server.service()).await; + let channel = fixture.channel().await; + let mut flight_sql_client = FlightSqlServiceClient::new(channel); + + for is_update in [Some(true), Some(false), None] { + let response = ActionCreatePreparedStatementResult { + prepared_statement_handle: "handle".into(), + is_update, + ..Default::default() + }; + test_server.set_do_action_response(vec![Ok(arrow_flight::Result::new( + response.as_any().encode_to_vec(), + ))]); + + let statement = flight_sql_client + .prepare("SELECT 1".to_string(), None) + .await + .unwrap(); + assert_eq!(statement.is_update(), is_update); + } + + fixture.shutdown_and_wait().await; +} + #[tokio::test] pub async fn test_begin_end_transaction() { let test_server = FlightSqlServiceImpl::new(); diff --git a/arrow-flight/tests/flight_sql_client_cli.rs b/arrow-flight/tests/flight_sql_client_cli.rs index 6125e85ac9c1..b518078c31b8 100644 --- a/arrow-flight/tests/flight_sql_client_cli.rs +++ b/arrow-flight/tests/flight_sql_client_cli.rs @@ -406,6 +406,7 @@ impl FlightSqlServiceImpl { prepared_statement_handle: handle.into(), dataset_schema: serialize_schema(&schema)?, parameter_schema: serialize_schema(¶meter_schema)?, + is_update: None, }) } diff --git a/format/FlightSql.proto b/format/FlightSql.proto index 90e6e5baeb21..ea55dcef5a1a 100644 --- a/format/FlightSql.proto +++ b/format/FlightSql.proto @@ -1550,6 +1550,11 @@ message ActionCreatePreparedStatementResult { // If the query provided contained parameters, parameter_schema contains the // schema of the expected parameters. It should be an IPC-encapsulated Schema, as described in Schema.fbs. bytes parameter_schema = 3; + + // When set to true, the query should be executed with CommandPreparedStatementUpdate, + // when set to false, the query should be executed with CommandPreparedStatementQuery. + // If not set, the client can choose how to execute the query. + optional bool is_update = 4; } /*