From 3061d9d9d532852d6c6adeddfc0662c64cc6eb35 Mon Sep 17 00:00:00 2001 From: Adam Curtis Date: Tue, 13 Feb 2024 14:17:25 -0500 Subject: [PATCH] GH-37720: [Format][Docs][FlightSQL] Document FlightSQL stateless prepared statements --- docs/source/format/FlightSql.rst | 3 +++ .../format/FlightSql/CommandPreparedStatementQuery.mmd | 2 ++ .../FlightSql/CommandPreparedStatementQuery.mmd.svg | 2 +- format/FlightSql.proto | 9 +++++++++ 4 files changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/source/format/FlightSql.rst b/docs/source/format/FlightSql.rst index add044c2d3621..9013afaa453d5 100644 --- a/docs/source/format/FlightSql.rst +++ b/docs/source/format/FlightSql.rst @@ -141,6 +141,9 @@ the ``type`` should be ``ClosePreparedStatement``). Execute a previously created prepared statement and get the results. When used with DoPut: binds parameter values to the prepared statement. + The server may optionally respond with an updated handle. The client + should use this updated handle for all subsequent requests for this + prepared statement. When used with GetFlightInfo: execute the prepared statement. The prepared statement can be reused after fetching results. diff --git a/docs/source/format/FlightSql/CommandPreparedStatementQuery.mmd b/docs/source/format/FlightSql/CommandPreparedStatementQuery.mmd index cb50522eb5a32..cbd1eb6014bca 100644 --- a/docs/source/format/FlightSql/CommandPreparedStatementQuery.mmd +++ b/docs/source/format/FlightSql/CommandPreparedStatementQuery.mmd @@ -28,6 +28,8 @@ Server->>Client: ActionCreatePreparedStatementResult{handle} loop for each invocation of the prepared statement Client->>Server: DoPut(CommandPreparedStatementQuery) Client->>Server: stream of FlightData +Server-->>Client: DoPutPreparedStatementResult{handle} +Note over Client,Server: optional response with updated handle Client->>Server: GetFlightInfo(CommandPreparedStatementQuery) Server->>Client: FlightInfo{endpoints: [FlightEndpoint{…}, …]} loop for each endpoint in FlightInfo.endpoints diff --git a/docs/source/format/FlightSql/CommandPreparedStatementQuery.mmd.svg b/docs/source/format/FlightSql/CommandPreparedStatementQuery.mmd.svg index 96a5bc3688297..cbf6a78e9a5ce 100644 --- a/docs/source/format/FlightSql/CommandPreparedStatementQuery.mmd.svg +++ b/docs/source/format/FlightSql/CommandPreparedStatementQuery.mmd.svg @@ -1 +1 @@ -ClientServerDoAction(ActionCreatePreparedStatementRequest)1ActionCreatePreparedStatementResult{handle}2DoPut(CommandPreparedStatementQuery)3stream of FlightData4GetFlightInfo(CommandPreparedStatementQuery)5FlightInfo{endpoints: [FlightEndpoint{…}, …]}6DoGet(endpoint.ticket)7stream of FlightData8loop[for each endpoint in FlightInfo.endpoints]loop[for each invocation of the prepared statement]DoAction(ActionClosePreparedStatementRequest)9ActionClosePreparedStatementRequest{}10ClientServer \ No newline at end of file +ServerClientServerClientoptional response with updated handleloop[for each endpoint in FlightInfo.endpoints]loop[for each invocation of the prepared statement]DoAction(ActionCreatePreparedStatementRequest)1ActionCreatePreparedStatementResult{handle}2DoPut(CommandPreparedStatementQuery)3stream of FlightData4DoPutPreparedStatementResult{handle}5GetFlightInfo(CommandPreparedStatementQuery)6FlightInfo{endpoints: [FlightEndpoint{…}, …]}7DoGet(endpoint.ticket)8stream of FlightData9DoAction(ActionClosePreparedStatementRequest)10ActionClosePreparedStatementRequest{}11 \ No newline at end of file diff --git a/format/FlightSql.proto b/format/FlightSql.proto index 581cf1f76d57c..406af9d3e0aa2 100644 --- a/format/FlightSql.proto +++ b/format/FlightSql.proto @@ -1797,6 +1797,15 @@ message DoPutUpdateResult { int64 record_count = 1; } +// An optional response returned when `DoPut` is called with `CommandPreparedStatementQuery` +message DoPutPreparedStatementResult { + option (experimental) = true; + + // (potentially updated) opaque handle for the prepared statement on the server. + // All subsequent requests for his prepared statement must use this new handle, if specified + bytes prepared_statement_handle = 1; +} + /* * Request message for the "CancelQuery" action. *