This is an automated email from the ASF dual-hosted git repository.
alamb pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/main by this push:
new 2b0427559d GH-37720: [Format][Docs][FlightSQL] Document stateless
prepared statements (#40243)
2b0427559d is described below
commit 2b0427559d94fb25ce61672c1ed17fc245d0a546
Author: Adam Curtis <[email protected]>
AuthorDate: Mon Mar 25 07:03:49 2024 -0400
GH-37720: [Format][Docs][FlightSQL] Document stateless prepared statements
(#40243)
documents changes for stateless management of FlightSQL prepared
statement handles based on the design proposal described in
apache/arrow#37720
* GitHub Issue: #37720
PRs for language implementations:
* Rust: apache/arrow-rs#5433
* Go: apache/arrow#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]>
---
docs/source/format/FlightSql.rst | 15 +++++++++++++++
.../FlightSql/CommandPreparedStatementQuery.mmd | 2 ++
.../FlightSql/CommandPreparedStatementQuery.mmd.svg | 2 +-
format/FlightSql.proto | 20 ++++++++++++++++++++
4 files changed, 38 insertions(+), 1 deletion(-)
diff --git a/docs/source/format/FlightSql.rst b/docs/source/format/FlightSql.rst
index 6bb9172713..5573c00407 100644
--- 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
index cb50522eb5..cbd1eb6014 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 96a5bc3688..cbf6a78e9a 100644
--- a/docs/source/format/FlightSql/CommandPreparedStatementQuery.mmd.svg
+++ b/docs/source/format/FlightSql/CommandPreparedStatementQuery.mmd.svg
@@ -1 +1 @@
-<svg id="mermaid-1647978322142" width="100%"
xmlns="http://www.w3.org/2000/svg"; height="721" style="max-width: 686px;
background-color: white;" viewBox="-50 -10 686
721"><style>#mermaid-1647978322142 {font-family:"trebuchet
ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}#mermaid-1647978322142
.error-icon{fill:#552222;}#mermaid-1647978322142
.error-text{fill:#552222;stroke:#552222;}#mermaid-1647978322142
.edge-thickness-normal{stroke-width:2px;}#mermaid-1647978322142 .edge-thickne
[...]
\ No newline at end of file
+<svg aria-roledescription="sequence" role="graphics-document document"
viewBox="-50 -10 651 836" style="max-width: 651px; background-color: white;"
xmlns:xlink="http://www.w3.org/1999/xlink"; xmlns="http://www.w3.org/2000/svg";
width="100%" id="my-svg"><g><rect class="actor actor-bottom" ry="3" rx="3"
height="65" width="150" stroke="#666" fill="#eaeaea" y="750" x="401"/><text
style="text-anchor: middle; font-size: 16px; font-weight: 400;" class="actor"
alignment-baseline="central" dominant [...]
\ No newline at end of file
diff --git a/format/FlightSql.proto b/format/FlightSql.proto
index 581cf1f76d..3282ee4f47 100644
--- a/format/FlightSql.proto
+++ b/format/FlightSql.proto
@@ -1797,6 +1797,26 @@ message DoPutUpdateResult {
int64 record_count = 1;
}
+/* An *optional* response returned when `DoPut` is called with
`CommandPreparedStatementQuery`.
+ *
+ * *Note on legacy behavior*: previous versions of the protocol did not return
any result for
+ * this command, and that behavior should still be supported by clients. In
that case, the client
+ * can continue as though the fields in this message were not provided or set
to sensible default values.
+ */
+message DoPutPreparedStatementResult {
+ option (experimental) = true;
+
+ // Represents a (potentially updated) opaque handle for the prepared
statement on the server.
+ // Because the handle could potentially be updated, any previous handles for
this prepared
+ // statement should be considered invalid, and all subsequent requests for
this prepared
+ // statement must use this new handle.
+ // The updated handle allows implementing query parameters with stateless
services.
+ //
+ // When an updated handle is not provided by the server, clients should
contiue
+ // using the previous handle provided by
`ActionCreatePreparedStatementResonse`.
+ optional bytes prepared_statement_handle = 1;
+}
+
/*
* Request message for the "CancelQuery" action.
*
