Clarify transactions

format/FlightSql.proto

@@ -103,14 +103,14 @@ enum SqlInfo {
   FLIGHT_SQL_TRANSACTION = 5;
 
   /*
-   * Retrieves an int32 indicating the timeout for prepared statement handles.
+   * Retrieves an int32 indicating the timeout (in milliseconds) for prepared statement handles.
    *
    * If 0, there is no timeout.
    */
   FLIGHT_SQL_STATEMENT_TIMEOUT = 6;
 
   /*
-   * Retrieves an int32 indicating the timeout for transactions, since transactions are not tied to a connection.
+   * Retrieves an int32 indicating the timeout (in milliseconds) for transactions, since transactions are not tied to a connection.
    *
    * If 0, there is no timeout.
    */
@@ -1502,26 +1502,31 @@ message ActionClosePreparedStatementRequest {
 
 /*
  * Request message for the "BeginTransaction" action.
- * Begins a transaction or creates a savepoint within a transaction.
+ * Begins a transaction.
  */
 message ActionBeginTransactionRequest {
-  // The transaction to which a savepoint belongs, if applicable.
-  //
-  // To begin a transaction, leave this field empty.
-  //
-  // Only supported if FLIGHT_SQL_TRANSACTION is
-  // FLIGHT_SQL_TRANSACTION_SUPPORT_SAVEPOINT.
+}
+
+/*
+ * Request message for the "BeginTransaction" action.
+ * Creates a savepoint within a transaction.
+ *
+ * Only supported if FLIGHT_SQL_TRANSACTION is
+ * FLIGHT_SQL_TRANSACTION_SUPPORT_SAVEPOINT.
+ */
+message ActionBeginSavepointRequest {
+  // The transaction to which a savepoint belongs.
   bytes transaction_id = 1;
-  // Name for the savepoint, if applicable.
+  // Name for the savepoint.
   string name = 2;
 }
 
 /*
- * The result of a "BeginTransaction" action.
+ * The result of a "BeginTransaction" or "BeginSavepoint" action.
  *
- * The transaction/savepoint can be manipulated with the "EndTransaction"
- * action, or automatically via server timeout. If the transaction times out,
- * then it is automatically rolled back.
+ * The transaction can be manipulated with the "EndTransaction" action, or
+ * automatically via server timeout. If the transaction times out, then it is
+ * automatically rolled back.
  */
 message ActionBeginTransactionResult {
   // Opaque handle for the transaction or savepoint on the server.
@@ -1572,7 +1577,7 @@ message CommandStatementQuery {
 
   // The SQL syntax.
   string query = 1;
-  // Include the query as part of this transaction (by default queries are auto-committed).
+  // Include the query as part of this transaction (if unset, the query is auto-committed).
   bytes transaction_id = 2;
 }
 
@@ -1599,7 +1604,7 @@ message CommandStatementSubstraitPlan {
 
   // A serialized substrait.Plan
   bytes plan = 1;
-  // Include the query as part of this transaction (by default queries are auto-committed).
+  // Include the query as part of this transaction (if unset, the query is auto-committed).
   bytes transaction_id = 2;
 }
 
@@ -1637,7 +1642,7 @@ message CommandPreparedStatementQuery {
 
   // Opaque handle for the prepared statement on the server.
   bytes prepared_statement_handle = 1;
-  // Include the query as part of this transaction (by default queries are auto-committed).
+  // Include the query as part of this transaction (if unset, the query is auto-committed).
   bytes transaction_id = 2;
 }
 
@@ -1650,7 +1655,7 @@ message CommandStatementUpdate {
 
   // The SQL syntax.
   string query = 1;
-  // Include the query as part of this transaction (by default queries are auto-committed).
+  // Include the query as part of this transaction (if unset, the query is auto-committed).
   bytes transaction_id = 2;
 }
 
@@ -1664,7 +1669,7 @@ message CommandPreparedStatementUpdate {
 
   // Opaque handle for the prepared statement on the server.
   bytes prepared_statement_handle = 1;
-  // Include the query as part of this transaction (by default queries are auto-committed).
+  // Include the query as part of this transaction (if unset, the query is auto-committed).
   bytes transaction_id = 2;
 }