worryg0d commented on code in PR #1901:
URL:
https://github.com/apache/cassandra-gocql-driver/pull/1901#discussion_r2384201429
##########
doc.go:
##########
@@ -326,24 +559,129 @@
// With single-partition batches you can send the batch directly to the node
for the partition without incurring the
// additional network hop.
//
-// It is also possible to pass entire BEGIN BATCH .. APPLY BATCH statement to
Query.Exec.
+// It is also possible to pass entire BEGIN BATCH .. APPLY BATCH statement to
[Query.Exec].
// There are differences how those are executed.
// BEGIN BATCH statement passed to Query.Exec is prepared as a whole in a
single statement.
// Batch.Exec prepares individual statements in the batch.
// If you have variable-length batches using the same statement, using
Batch.Exec is more efficient.
//
// See Example_batch for an example.
//
+// The [Batch] API provides a fluent interface for building and executing
batch operations:
+//
+// // Create and execute a batch using fluent API
+// err := session.Batch(LoggedBatch).
+// Query("INSERT INTO table1 (id, name) VALUES (?, ?)", id1,
name1).
+// Query("INSERT INTO table2 (id, value) VALUES (?, ?)", id2,
value2).
+// Exec()
+//
+// // Lightweight transactions with batches
+// applied, iter, err := session.Batch(LoggedBatch).
+// Query("INSERT INTO users (id, name) VALUES (?, ?) IF NOT
EXISTS", id, name).
+// ExecCAS()
+// if err != nil {
+// // handle error
+// }
+// if !applied {
+// // handle conditional failure
+// }
+//
// # Lightweight transactions
//
-// Query.ScanCAS or Query.MapScanCAS can be used to execute a single-statement
lightweight transaction (an
+// [Query.ScanCAS] or [Query.MapScanCAS] can be used to execute a
single-statement lightweight transaction (an
// INSERT/UPDATE .. IF statement) and reading its result. See example for
Query.MapScanCAS.
//
// Multiple-statement lightweight transactions can be executed as a logged
batch that contains at least one conditional
-// statement. All the conditions must return true for the batch to be applied.
You can use Batch.ExecCAS and
-// Batch.MapExecCAS when executing the batch to learn about the result of the
LWT. See example for
+// statement. All the conditions must return true for the batch to be applied.
You can use [Batch.ExecCAS] and
+// [Batch.MapExecCAS] when executing the batch to learn about the result of
the LWT. See example for
// Batch.MapExecCAS.
//
+// # SERIAL Consistency for Reads
+//
+// The driver supports SERIAL and LOCAL_SERIAL consistency levels on SELECT
statements.
+// These special consistency levels are designed for reading data that may
have been written using
+// lightweight transactions (LWT) with IF conditions, providing linearizable
consistency guarantees.
+//
+// When to use SERIAL consistency levels:
+//
+// Use SERIAL or LOCAL_SERIAL consistency when you need to:
+// - Read the most recent committed value after lightweight transactions
+// - Ensure linearizable consistency (stronger than eventual consistency)
+// - Read data that might have uncommitted lightweight transactions in
progress
+//
+// Important considerations:
+//
+// - SERIAL reads have higher latency and resource usage than normal reads
+// - Only use when you specifically need linearizable consistency
+// - If a SERIAL read finds an uncommitted transaction, it will commit that
transaction
+// - Most applications should use regular consistency levels (ONE, QUORUM,
etc.)
+//
+// # Immutable Execution
+//
+// [Query] and [Batch] objects follow an immutable execution model that
enables safe reuse and concurrent
+// execution without object mutation.
+//
+// Query and Batch Object Reusability:
Review Comment:
Cool. Thanks! Anyway, I think it is better to explicitly note that query
pooling is no longer handled by the driver side, even if the impact is not
significant
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
