Merge pull request #1068 from wprzytula/eradicate-unpaged-selects-fro…

…m-docs

docs: Eradicate unpaged SELECTs and warn about their drawbacks

README.md

@@ -15,13 +15,15 @@ The [documentation book](https://rust-driver.docs.scylladb.com/stable/index.html
 
 ## Examples
 ```rust
+use futures::TryStreamExt;
+
 let uri = "127.0.0.1:9042";
 
 let session: Session = SessionBuilder::new().known_node(uri).build().await?;
 
-let result = session.query_unpaged("SELECT a, b, c FROM ks.t", &[]).await?;
-let mut iter = result.rows_typed::<(i32, i32, String)>()?;
-while let Some((a, b, c)) = iter.next().transpose()? {
+let raw_iter = session.query_iter("SELECT a, b, c FROM ks.t", &[]).await?;
+let mut iter = raw_iter.into_typed::<(i32, i32, String)>();
+while let Some((a, b, c)) = iter.try_next().await? {
     println!("a, b, c: {}, {}, {}", a, b, c);
 }
 ```

docs/source/data-types/blob.md

@@ -4,10 +4,11 @@
 
 ```rust
 # extern crate scylla;
+# extern crate futures;
 # use scylla::Session;
 # use std::error::Error;
 # async fn check_only_compiles(session: &Session) -> Result<(), Box<dyn Error>> {
-use scylla::IntoTypedRows;
+use futures::TryStreamExt;
 
 // Insert some blob into the table as a Vec<u8>
 // We can insert it by reference to not move the whole blob
@@ -17,9 +18,8 @@ session
     .await?;
 
 // Read blobs from the table
-let result = session.query_unpaged("SELECT a FROM keyspace.table", &[]).await?;
-let mut iter = result.rows_typed::<(Vec<u8>,)>()?;
-while let Some((blob_value,)) = iter.next().transpose()? {
+let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[]).await?.into_typed::<(Vec<u8>,)>();
+while let Some((blob_value,)) = iter.try_next().await? {
     println!("{:?}", blob_value);
 }
 # Ok(())

docs/source/data-types/collections.md

@@ -5,10 +5,11 @@
 
 ```rust
 # extern crate scylla;
+# extern crate futures;
 # use scylla::Session;
 # use std::error::Error;
 # async fn check_only_compiles(session: &Session) -> Result<(), Box<dyn Error>> {
-use scylla::IntoTypedRows;
+use futures::TryStreamExt;
 
 // Insert a list of ints into the table
 let my_list: Vec<i32> = vec![1, 2, 3, 4, 5];
@@ -17,9 +18,8 @@ session
     .await?;
 
 // Read a list of ints from the table
-let result = session.query_unpaged("SELECT a FROM keyspace.table", &[]).await?;
-let mut iter = result.rows_typed::<(Vec<i32>,)>()?;
-while let Some((list_value,)) = iter.next().transpose()? {
+let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[]).await?.into_typed::<(Vec<i32>,)>();
+while let Some((list_value,)) = iter.try_next().await? {
     println!("{:?}", list_value);
 }
 # Ok(())
@@ -31,10 +31,11 @@ while let Some((list_value,)) = iter.next().transpose()? {
 
 ```rust
 # extern crate scylla;
+# extern crate futures;
 # use scylla::Session;
 # use std::error::Error;
 # async fn check_only_compiles(session: &Session) -> Result<(), Box<dyn Error>> {
-use scylla::IntoTypedRows;
+use futures::TryStreamExt;
 
 // Insert a set of ints into the table
 let my_set: Vec<i32> = vec![1, 2, 3, 4, 5];
@@ -43,21 +44,23 @@ session
     .await?;
 
 // Read a set of ints from the table
-let result = session.query_unpaged("SELECT a FROM keyspace.table", &[]).await?;
-let mut iter = result.rows_typed::<(Vec<i32>,)>()?;
-while let Some((list_value,)) = iter.next().transpose()? {
-    println!("{:?}", list_value);
+let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
+    .await?
+    .into_typed::<(Vec<i32>,)>();
+while let Some((set_value,)) = iter.try_next().await? {
+    println!("{:?}", set_value);
 }
 # Ok(())
 # }
 ```
 
 ```rust
 # extern crate scylla;
+# extern crate futures;
 # use scylla::Session;
 # use std::error::Error;
 # async fn check_only_compiles(session: &Session) -> Result<(), Box<dyn Error>> {
-use scylla::IntoTypedRows;
+use futures::TryStreamExt;
 use std::collections::HashSet;
 
 // Insert a set of ints into the table
@@ -67,21 +70,23 @@ session
     .await?;
 
 // Read a set of ints from the table
-let result = session.query_unpaged("SELECT a FROM keyspace.table", &[]).await?;
-let mut iter = result.rows_typed::<(HashSet<i32>,)>()?;
-while let Some((list_value,)) = iter.next().transpose()? {
-    println!("{:?}", list_value);
+let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
+    .await?
+    .into_typed::<(HashSet<i32>,)>();
+while let Some((set_value,)) = iter.try_next().await? {
+    println!("{:?}", set_value);
 }
 # Ok(())
 # }
 ```
 
 ```rust
 # extern crate scylla;
+# extern crate futures;
 # use scylla::Session;
 # use std::error::Error;
 # async fn check_only_compiles(session: &Session) -> Result<(), Box<dyn Error>> {
-use scylla::IntoTypedRows;
+use futures::TryStreamExt;
 use std::collections::BTreeSet;
 
 // Insert a set of ints into the table
@@ -91,10 +96,11 @@ session
     .await?;
 
 // Read a set of ints from the table
-let result = session.query_unpaged("SELECT a FROM keyspace.table", &[]).await?;
-let mut iter = result.rows_typed::<(BTreeSet<i32>,)>()?;
-while let Some((list_value,)) = iter.next().transpose()? {
-    println!("{:?}", list_value);
+let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
+    .await?
+    .into_typed::<(BTreeSet<i32>,)>();
+while let Some((set_value,)) = iter.try_next().await? {
+    println!("{:?}", set_value);
 }
 # Ok(())
 # }
@@ -105,10 +111,11 @@ while let Some((list_value,)) = iter.next().transpose()? {
 
 ```rust
 # extern crate scylla;
+# extern crate futures;
 # use scylla::Session;
 # use std::error::Error;
 # async fn check_only_compiles(session: &Session) -> Result<(), Box<dyn Error>> {
-use scylla::IntoTypedRows;
+use futures::TryStreamExt;
 use std::collections::HashMap;
 
 // Insert a map of text and int into the table
@@ -120,9 +127,10 @@ session
     .await?;
 
 // Read a map from the table
-let result = session.query_unpaged("SELECT a FROM keyspace.table", &[]).await?;
-let mut iter = result.rows_typed::<(HashMap<String, i32>,)>()?;
-while let Some((map_value,)) = iter.next().transpose()? {
+let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
+    .await?
+    .into_typed::<(HashMap<String, i32>,)>();
+while let Some((map_value,)) = iter.try_next().await? {
     println!("{:?}", map_value);
 }
 # Ok(())
@@ -131,10 +139,11 @@ while let Some((map_value,)) = iter.next().transpose()? {
 
 ```rust
 # extern crate scylla;
+# extern crate futures;
 # use scylla::Session;
 # use std::error::Error;
 # async fn check_only_compiles(session: &Session) -> Result<(), Box<dyn Error>> {
-use scylla::IntoTypedRows;
+use futures::TryStreamExt;
 use std::collections::BTreeMap;
 
 // Insert a map of text and int into the table
@@ -146,9 +155,10 @@ session
     .await?;
 
 // Read a map from the table
-let result = session.query_unpaged("SELECT a FROM keyspace.table", &[]).await?;
-let mut iter = result.rows_typed::<(BTreeMap<String, i32>,)>()?;
-while let Some((map_value,)) = iter.next().transpose()? {
+let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
+    .await?
+    .into_typed::<(BTreeMap<String, i32>,)>();
+while let Some((map_value,)) = iter.try_next().await? {
     println!("{:?}", map_value);
 }
 # Ok(())

docs/source/data-types/counter.md

@@ -4,16 +4,18 @@
 
 ```rust
 # extern crate scylla;
+# extern crate futures;
 # use scylla::Session;
 # use std::error::Error;
 # async fn check_only_compiles(session: &Session) -> Result<(), Box<dyn Error>> {
-use scylla::IntoTypedRows;
+use futures::TryStreamExt;
 use scylla::frame::value::Counter;
 
 // Read counter from the table
-let result = session.query_unpaged("SELECT c FROM keyspace.table", &[]).await?;
-let mut iter = result.rows_typed::<(Counter,)>()?;
-while let Some((counter_value,)) = iter.next().transpose()? {
+let mut iter = session.query_iter("SELECT c FROM keyspace.table", &[])
+    .await?
+    .into_typed::<(Counter,)>();
+while let Some((counter_value,)) = iter.try_next().await? {
     let counter_int_value: i64 = counter_value.0;
     println!("{}", counter_int_value);
 }

docs/source/data-types/date.md

@@ -14,11 +14,12 @@ However, for most use cases other types are more practical. See following sectio
 
 ```rust
 # extern crate scylla;
+# extern crate futures;
 # use scylla::Session;
 # use std::error::Error;
 # async fn check_only_compiles(session: &Session) -> Result<(), Box<dyn Error>> {
 use scylla::frame::value::CqlDate;
-use scylla::IntoTypedRows;
+use futures::TryStreamExt;
 
 // 1970-01-08
 let to_insert = CqlDate((1 << 31) + 7);
@@ -29,14 +30,11 @@ session
     .await?;
 
 // Read raw Date from the table
-if let Some(rows) = session
-    .query_unpaged("SELECT a FROM keyspace.table", &[])
+let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .rows
-{
-    for row in rows.into_typed::<(CqlDate,)>() {
-        let (date_value,): (CqlDate,) = row?;
-    }
+    .into_typed::<(CqlDate,)>();
+while let Some((date_value,)) = iter.try_next().await? {
+    // ...
 }
 # Ok(())
 # }
@@ -52,11 +50,12 @@ If full range is not required and `chrono` feature is enabled,
 ```rust
 # extern crate chrono;
 # extern crate scylla;
+# extern crate futures;
 # use scylla::Session;
 # use std::error::Error;
 # async fn check_only_compiles(session: &Session) -> Result<(), Box<dyn Error>> {
 use chrono::NaiveDate;
-use scylla::IntoTypedRows;
+use futures::TryStreamExt;
 
 // 2021-03-24
 let to_insert = NaiveDate::from_ymd_opt(2021, 3, 24).unwrap();
@@ -67,10 +66,11 @@ session
     .await?;
 
 // Read NaiveDate from the table
-let result = session.query_unpaged("SELECT a FROM keyspace.table", &[]).await?;
-let mut iter = result.rows_typed::<(NaiveDate,)>()?;
-while let Some((date_value,)) = iter.next().transpose()? {
-    println!("{:?}", date_value);
+let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
+    .await?
+    .into_typed::<(NaiveDate,)>();
+while let Some((date_value,)) = iter.try_next().await? {
+    // ...
 }
 # Ok(())
 # }
@@ -86,10 +86,11 @@ documentation to get more info.
 ```rust
 # extern crate scylla;
 # extern crate time;
+# extern crate futures;
 # use scylla::Session;
 # use std::error::Error;
 # async fn check_only_compiles(session: &Session) -> Result<(), Box<dyn Error>> {
-use scylla::IntoTypedRows;
+use futures::TryStreamExt;
 use time::{Date, Month};
 
 // 2021-03-24
@@ -101,10 +102,11 @@ session
     .await?;
 
 // Read Date from the table
-let result = session.query_unpaged("SELECT a FROM keyspace.table", &[]).await?;
-let mut iter = result.rows_typed::<(Date,)>()?;
-while let Some((date_value,)) = iter.next().transpose()? {
-    println!("{:?}", date_value);
+let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
+    .await?
+    .into_typed::<(Date,)>();
+while let Some((date_value,)) = iter.try_next().await? {
+    // ...
 }
 # Ok(())
 # }

docs/source/data-types/decimal.md

@@ -7,10 +7,11 @@ Without any feature flags, the user can interact with `decimal` type by making u
 
 ```rust
 # extern crate scylla;
+# extern crate futures;
 # use scylla::Session;
 # use std::error::Error;
 # async fn check_only_compiles(session: &Session) -> Result<(), Box<dyn Error>> {
-use scylla::IntoTypedRows;
+use futures::TryStreamExt;
 use scylla::frame::value::CqlDecimal;
 use std::str::FromStr;
 
@@ -22,10 +23,11 @@ session
     .await?;
 
 // Read a decimal from the table
-if let Some(rows) = session.query_unpaged("SELECT a FROM keyspace.table", &[]).await?.rows {
-    for row in rows.into_typed::<(CqlDecimal,)>() {
-        let (decimal_value,): (CqlDecimal,) = row?;
-    }
+let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
+    .await?
+    .into_typed::<(CqlDecimal,)>();
+while let Some((decimal_value,)) = iter.try_next().await? {
+    println!("{:?}", decimal_value);
 }
 # Ok(())
 # }
@@ -38,10 +40,11 @@ To make use of `bigdecimal::Bigdecimal` type, user should enable `bigdecimal-04`
 ```rust
 # extern crate scylla;
 # extern crate bigdecimal;
+# extern crate futures;
 # use scylla::Session;
 # use std::error::Error;
 # async fn check_only_compiles(session: &Session) -> Result<(), Box<dyn Error>> {
-use scylla::IntoTypedRows;
+use futures::TryStreamExt;
 use bigdecimal::BigDecimal;
 use std::str::FromStr;
 
@@ -52,9 +55,10 @@ session
     .await?;
 
 // Read a decimal from the table
-let result = session.query_unpaged("SELECT a FROM keyspace.table", &[]).await?;
-let mut iter = result.rows_typed::<(BigDecimal,)>()?;
-while let Some((decimal_value,)) = iter.next().transpose()? {
+let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
+    .await?
+    .into_typed::<(BigDecimal,)>();
+while let Some((decimal_value,)) = iter.try_next().await? {
     println!("{:?}", decimal_value);
 }
 # Ok(())