From 880d7b099592bc73893fac39a56d54c606a1aadf Mon Sep 17 00:00:00 2001
From: muzarski <mikolaj.uzarski@scylladb.com>
Date: Thu, 25 Apr 2024 14:01:35 +0200
Subject: [PATCH] book: mention benefits of prepared statements

---
 docs/source/queries/prepared.md | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/docs/source/queries/prepared.md b/docs/source/queries/prepared.md
index f8230b6a5f..ae7f002098 100644
--- a/docs/source/queries/prepared.md
+++ b/docs/source/queries/prepared.md
@@ -1,8 +1,12 @@
 # Prepared query
 
-Prepared queries provide much better performance than simple queries,
+Prepared queries provide much better performance than unprepared queries,
 but they need to be prepared before use.
 
+There are other benefits that prepared queries have to offer:
+- Increased type-safety - thanks to metadata provided by the server, the driver can verify bound values' types before serialization. This way, we can be always sure that the Rust type provided by the user is compatible (and if not, the error is returned) with the destined native type. The same applies for deserialization.
+- Improved load-balancing - using the statement metadata, the driver can compute a set of destined replicas for current statement execution. These replicas will be preferred when choosing the node (and shard) to send the request to. For more insight on this, see [performance section](#performance).
+
 ```rust
 # extern crate scylla;
 # use scylla::Session;
@@ -15,7 +19,7 @@ let prepared: PreparedStatement = session
     .prepare("INSERT INTO ks.tab (a) VALUES(?)")
     .await?;
 
-// Run the prepared query with some values, just like a simple query
+// Run the prepared query with some values, just like an unprepared query
 let to_insert: i32 = 12345;
 session.execute(&prepared, (to_insert,)).await?;
 # Ok(())
@@ -39,7 +43,7 @@ If at least one succeeds returns success.
 
 ### `Session::execute`
 `Session::execute` takes a prepared query and bound values and runs the query.
-Passing values and the result is the same as in [simple query](simple.md).
+Passing values and the result is the same as in [unprepared query](simple.md).
 
 ### Query options
 
@@ -63,7 +67,7 @@ let mut prepared: PreparedStatement = session
 // This is the consistency with which this query will be executed
 prepared.set_consistency(Consistency::One);
 
-// Run the prepared query with some values, just like a simple query
+// Run the prepared query with some values, just like an unprepared query
 let to_insert: i32 = 12345;
 session.execute(&prepared, (to_insert,)).await?;
 # Ok(())
@@ -80,7 +84,7 @@ for more options.
 
 ### Performance
 
-Prepared queries have good performance, much better than simple queries.
+Prepared queries have good performance, much better than unprepared queries.
 By default they use shard/token aware load balancing.
 
 > **Always** pass partition key values as bound values.