Docs: Add warnings about performance of query

docs/source/queries/paged.md

@@ -5,6 +5,14 @@ allow to receive the whole result page by page.
 `Session::query_iter` and `Session::execute_iter` take a [simple query](simple.md) or a [prepared query](prepared.md)
 and return an `async` iterator over result `Rows`.
 
+> ***Warning***\
+> In case of unprepared variant (`Session::query_iter`) if the values are not empty
+> driver will first fully prepare a query (which means issuing additional request to each
+> node in a cluster). This will have a performance penalty - how big it is depends on
+> the size of your cluster (more nodes - more requests) and the size of returned
+> result (more returned pages - more amortized penalty). In any case, it is preferable to
+> use `Session::execute_iter`.
+
 ### Examples
 Use `query_iter` to perform a [simple query](simple.md) with paging:
 ```rust
@@ -119,6 +127,11 @@ let res2 = session
 # }
 ```
 
+> ***Warning***\
+> If the values are not empty, driver first needs to send a `PREPARE` request
+> in order to fetch information required to serialize values. This will affect
+> performance because 2 round trips will be required instead of 1.
+
 On a `PreparedStatement`:
 ```rust
 # extern crate scylla;

docs/source/queries/simple.md

@@ -22,6 +22,11 @@ session
 > 
 > When page size is set, `query` will return only the first page of results.
 
+> ***Warning***\
+> If the values are not empty, driver first needs to send a `PREPARE` request
+> in order to fetch information required to serialize values. This will affect
+> performance because 2 round trips will be required instead of 1.
+
 ### First argument - the query
 As the first argument `Session::query` takes anything implementing `Into<Query>`.\
 You can create a query manually to set custom options. For example to change query consistency:

scylla/src/transport/session.rs

@@ -558,6 +558,10 @@ impl Session {
     ///
     /// This is the easiest way to make a query, but performance is worse than that of prepared queries.
     ///
+    /// It is discouraged to use this method with non-empty values argument (`is_empty()` method from `SerializeRow`
+    /// trait returns false). In such case, query first needs to be prepared (on a single connection), so
+    /// driver will perform 2 round trips instead of 1. Please use [`Session::execute()`] instead.
+    ///
     /// See [the book](https://rust-driver.docs.scylladb.com/stable/queries/simple.html) for more information
     /// # Arguments
     /// * `query` - query to perform, can be just a `&str` or the [Query] struct.
@@ -608,6 +612,11 @@ impl Session {
     }
 
     /// Queries the database with a custom paging state.
+    ///
+    /// It is discouraged to use this method with non-empty values argument (`is_empty()` method from `SerializeRow`
+    /// trait returns false). In such case, query first needs to be prepared (on a single connection), so
+    /// driver will perform 2 round trips instead of 1. Please use [`Session::execute_paged()`] instead.
+    ///
     /// # Arguments
     ///
     /// * `query` - query to be performed
@@ -749,6 +758,10 @@ impl Session {
     /// Returns an async iterator (stream) over all received rows\
     /// Page size can be specified in the [Query] passed to the function
     ///
+    /// It is discouraged to use this method with non-empty values argument (`is_empty()` method from `SerializeRow`
+    /// trait returns false). In such case, query first needs to be prepared (on a single connection), so
+    /// driver will initially perform 2 round trips instead of 1. Please use [`Session::execute_iter()`] instead.
+    ///
     /// See [the book](https://rust-driver.docs.scylladb.com/stable/queries/paged.html) for more information
     ///
     /// # Arguments
@@ -1128,6 +1141,11 @@ impl Session {
     ///
     /// Batch values must contain values for each of the queries
     ///
+    /// Avoid using non-empty values (`SerializeRow::is_empty()` return false) for simple queries
+    /// inside the batch. Such queries will first need to be prepared, so the driver will need to
+    /// send (numer_of_unprepared_queries_with_values + 1) requests instead of 1 request, severly
+    /// affecting performance.
+    ///
     /// See [the book](https://rust-driver.docs.scylladb.com/stable/queries/batch.html) for more information
     ///
     /// # Arguments