GH-37720: [Format][Docs][FlightSQL] Document stateless prepared state…

…ments (#40243) documents changes for stateless management of FlightSQL prepared statement handles based on the design proposal described in #37720 * GitHub Issue: #37720 PRs for language implementations: * Rust: apache/arrow-rs#5433 * Go: #40311 Mailing list discussion: https://lists.apache.org/thread/3kb82ypx99q96g84qv555l6x8r0bppyq --------- Co-authored-by: David Li <[email protected]> Co-authored-by: Andrew Lamb <[email protected]> Co-authored-by: Sutou Kouhei <[email protected]>
apache · Mar 25, 2024 · 2b04275 · 2b04275
1 parent d236cea
commit 2b04275
Show file tree

Hide file tree

Showing 4 changed files with 38 additions and 1 deletion.
diff --git a/docs/source/format/FlightSql.rst b/docs/source/format/FlightSql.rst
@@ -141,6 +141,21 @@ 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 provide an updated handle in the response.
+    Updating the handle allows the client to supply all state required to
+    execute the query in an ActionPreparedStatementExecute message.
+    For example, stateless servers can encode the bound parameter values into
+    the new handle, and the client will send that new handle with parameters
+    back to the server.
+
+    Note that a handle returned from a DoPut call with
+    CommandPreparedStatementQuery can itself be passed to a subsequent DoPut
+    call with CommandPreparedStatementQuery to bind a new set of parameters.
+    The subsequent call itself may return an updated handle which again should
+    be used for subsequent requests.
+
+    The server is responsible for detecting the case where the client does not
+    use the updated handle and should return an error.
 
     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
@@ -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