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

[erratic-pattern]

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

[github-actions[bot]]

Thanks for opening a pull request!

If this is not a minor PR. Could you open an issue for this pull request on GitHub? https://github.com/apache/arrow/issues/new/choose

Opening GitHub issues ahead of time contributes to the Openness of the Apache Arrow project.

Then could you also rename the pull request title in the following format?

GH-${GITHUB_ISSUE_ID}: [${COMPONENT}] ${SUMMARY}

or

MINOR: [${COMPONENT}] ${SUMMARY}

In the case of PARQUET issues on JIRA the title also supports:

PARQUET-${JIRA_ISSUE_ID}: [${COMPONENT}] ${SUMMARY}

See also:

• Other pull requests
• Contribution Guidelines - Contributing Overview

[github-actions[bot]]

:warning: GitHub issue #37720 has been automatically assigned in GitHub to PR creator.

[joellubi]

Will we need to extend the schema of the PutResult message in order to encapsulate the DoPutPreparedStatementResult payload?

This is the spec right now:

service FlightService {
  rpc DoPut(stream FlightData) returns (stream PutResult) {}
}

message PutResult {
  bytes app_metadata = 1;
}

I don't think the response would be considered app_metadata.

[lidavidm]

The "app" in this case is Flight SQL. (Someday I would like to fuse Flight SQL/Flight RPC to avoid these odd distinctions, and so that we aren't multiplexing a dozen different calls into the same endpoint...)

[joellubi]

With that framing it makes sense, thanks @lidavidm.

[erratic-pattern]

This proposal was approved on the Arrow dev mailing list. See thread here

[alamb]

Thank you everyone for your feedback and participation in the process

[conbench-apache-arrow[bot]]

After merging your PR, Conbench analyzed the 5 benchmarking runs that have been run so far on merge-commit 2b0427559d94fb25ce61672c1ed17fc245d0a546.

There were no benchmark performance regressions. 🎉

The full Conbench report has more details.