docs: add caveat about unpaged SELECTs' drawbacks

We shouldn't encourage users to perform unpaged SELECTs. Normally,
SELECTs should be paged, therefore caveat about that is added in two
relevant places in docs.

docs/source/queries/result.md

@@ -3,6 +3,21 @@
 `Session::query_unpaged`, `Session::query_single_page`, `Session::execute_unpaged` and `Session::execute_single_page`
 return a `QueryResult` with rows represented as `Option<Vec<Row>>`.
 
+> ***Note***\
+> Using unpaged queries for SELECTs is discouraged in general.
+> Query results may be so big that it is not preferable to fetch them all at once.
+> However, `query_unpaged` will return all results in one, possibly giant, piece
+> (unless a timeout occurs due to high load incurred by the cluster).
+> This:
+> - increases latency,
+> - has large memory footprint,
+> - puts high load on the cluster,
+> - is more likely to time out (because big work takes more time than little work,
+>   and returning one large piece of data is more work than returning one chunk of data).
+
+> To sum up, for SELECTs that may return return a lot of data prefer paged queries,
+> e.g. with `Session::query_iter()` (see [Paged queries](paged.md)).
+
 ### Basic representation
 `Row` is a basic representation of a received row. It can be used by itself, but it's a bit awkward to use:
 ```rust

docs/source/queries/simple.md

@@ -18,7 +18,7 @@ session
 > ***Warning***\
 > Don't use simple query to receive large amounts of data.\
 > By default the query is unpaged and might cause heavy load on the cluster.\
-> In such cases set a page size and use [paged query](paged.md) instead.\
+> In such cases use [paged query](paged.md) instead.\
 > 
 > `query_unpaged` will return all results in one, possibly giant, piece
 > (unless a timeout occurs due to high load incurred by the cluster).
@@ -84,6 +84,19 @@ Each row can be parsed as a tuple of rust types using `rows_typed`:
 # async fn check_only_compiles(session: &Session) -> Result<(), Box<dyn Error>> {
 use scylla::IntoTypedRows;
 
+// NOTE: using unpaged queries for SELECTs is discouraged in general.
+// Query results may be so big that it is not preferable to fetch them all at once.
+// However, `query_unpaged` will return all results in one, possibly giant, piece
+// (unless a timeout occurs due to high load incurred by the cluster).
+// This:
+// - increases latency,
+// - has large memory footprint,
+// - puts high load on the cluster,
+// - is more likely to time out (because big work takes more time than little work,
+//   and returning one large piece of data is more work than returning one chunk of data).
+// To sum up, for SELECTs that may return return a lot of data prefer paged queries,
+// e.g. with `Session::query_iter()`.
+
 // Query rows from the table and print them
 let result = session.query_unpaged("SELECT a FROM ks.tab", &[]).await?;
 let mut iter = result.rows_typed::<(i32,)>()?;