book: adjust code examples to the new deserialization API

Examples in the Book are now adjusted to the new deserialization API, and the book finally compile and the tests there pass. Note that this commit does not describe exhaustively the intended way of using the new deserialization framework; this is left for a follow-up. Co-authored-by: Wojciech Przytuła <[email protected]>
scylladb · Nov 12, 2024 · e38486b · e38486b
1 parent e99d697
commit e38486b
Show file tree

Hide file tree

Showing 23 changed files with 138 additions and 155 deletions.
diff --git a/README.md b/README.md
@@ -21,9 +21,9 @@ let uri = "127.0.0.1:9042";
 
 let session: Session = SessionBuilder::new().known_node(uri).build().await?;
 
-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? {
+let query_pager = session.query_iter("SELECT a, b, c FROM ks.t", &[]).await?;
+let mut stream = query_pager.rows_stream::<(i32, i32, String)>()?;
+while let Some((a, b, c)) = stream.try_next().await? {
     println!("a, b, c: {}, {}, {}", a, b, c);
 }
 ```

diff --git a/docs/source/data-types/blob.md b/docs/source/data-types/blob.md
@@ -18,8 +18,10 @@ session
     .await?;
 
 // Read blobs from the table
-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? {
+let mut stream = session.query_iter("SELECT a FROM keyspace.table", &[])
+    .await?
+    .rows_stream::<(Vec<u8>,)>()?;
+while let Some((blob_value,)) = stream.try_next().await? {
     println!("{:?}", blob_value);
 }
 # Ok(())

diff --git a/docs/source/data-types/collections.md b/docs/source/data-types/collections.md
@@ -18,8 +18,10 @@ session
     .await?;
 
 // Read a list of ints from the table
-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? {
+let mut stream = session.query_iter("SELECT a FROM keyspace.table", &[])
+    .await?
+    .rows_stream::<(Vec<i32>,)>()?;
+while let Some((list_value,)) = stream.try_next().await? {
     println!("{:?}", list_value);
 }
 # Ok(())
@@ -44,10 +46,10 @@ session
     .await?;
 
 // Read a set of ints from the table
-let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
+let mut stream = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(Vec<i32>,)>();
-while let Some((set_value,)) = iter.try_next().await? {
+    .rows_stream::<(Vec<i32>,)>()?;
+while let Some((set_value,)) = stream.try_next().await? {
     println!("{:?}", set_value);
 }
 # Ok(())
@@ -72,7 +74,7 @@ session
 // Read a set of ints from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(HashSet<i32>,)>();
+    .rows_stream::<(HashSet<i32>,)>()?;
 while let Some((set_value,)) = iter.try_next().await? {
     println!("{:?}", set_value);
 }
@@ -98,7 +100,7 @@ session
 // Read a set of ints from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(BTreeSet<i32>,)>();
+    .rows_stream::<(BTreeSet<i32>,)>()?;
 while let Some((set_value,)) = iter.try_next().await? {
     println!("{:?}", set_value);
 }
@@ -129,7 +131,7 @@ session
 // Read a map from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(HashMap<String, i32>,)>();
+    .rows_stream::<(HashMap<String, i32>,)>()?;
 while let Some((map_value,)) = iter.try_next().await? {
     println!("{:?}", map_value);
 }
@@ -157,7 +159,7 @@ session
 // Read a map from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(BTreeMap<String, i32>,)>();
+    .rows_stream::<(BTreeMap<String, i32>,)>()?;
 while let Some((map_value,)) = iter.try_next().await? {
     println!("{:?}", map_value);
 }

diff --git a/docs/source/data-types/counter.md b/docs/source/data-types/counter.md
@@ -18,10 +18,10 @@ session
     .await?;
 
 // Read counter from the table
-let mut iter = session.query_iter("SELECT c FROM keyspace.table", &[])
+let mut stream = session.query_iter("SELECT c FROM keyspace.table", &[])
     .await?
-    .into_typed::<(Counter,)>();
-while let Some((counter_value,)) = iter.try_next().await? {
+    .rows_stream::<(Counter,)>()?;
+while let Some((counter_value,)) = stream.try_next().await? {
     let counter_int_value: i64 = counter_value.0;
     println!("{}", counter_int_value);
 }

diff --git a/docs/source/data-types/date.md b/docs/source/data-types/date.md
@@ -32,7 +32,7 @@ session
 // Read raw Date from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(CqlDate,)>();
+    .rows_stream::<(CqlDate,)>()?;
 while let Some((date_value,)) = iter.try_next().await? {
     // ...
 }
@@ -68,7 +68,7 @@ session
 // Read NaiveDate from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(NaiveDate,)>();
+    .rows_stream::<(NaiveDate,)>()?;
 while let Some((date_value,)) = iter.try_next().await? {
     // ...
 }
@@ -104,7 +104,7 @@ session
 // Read Date from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(Date,)>();
+    .rows_stream::<(Date,)>()?;
 while let Some((date_value,)) = iter.try_next().await? {
     // ...
 }

diff --git a/docs/source/data-types/decimal.md b/docs/source/data-types/decimal.md
@@ -25,7 +25,7 @@ session
 // Read a decimal from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(CqlDecimal,)>();
+    .rows_stream::<(CqlDecimal,)>()?;
 while let Some((decimal_value,)) = iter.try_next().await? {
     println!("{:?}", decimal_value);
 }
@@ -57,7 +57,7 @@ session
 // Read a decimal from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(BigDecimal,)>();
+    .rows_stream::<(BigDecimal,)>()?;
 while let Some((decimal_value,)) = iter.try_next().await? {
     println!("{:?}", decimal_value);
 }

diff --git a/docs/source/data-types/duration.md b/docs/source/data-types/duration.md
@@ -19,7 +19,7 @@ session
 // Read duration from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(CqlDuration,)>();
+    .rows_stream::<(CqlDuration,)>()?;
 while let Some((duration_value,)) = iter.try_next().await? {
     println!("{:?}", duration_value);
 }

diff --git a/docs/source/data-types/inet.md b/docs/source/data-types/inet.md
@@ -19,7 +19,7 @@ session
 // Read inet from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(IpAddr,)>();
+    .rows_stream::<(IpAddr,)>()?;
 while let Some((inet_value,)) = iter.try_next().await? {
     println!("{:?}", inet_value);
 }

diff --git a/docs/source/data-types/primitive.md b/docs/source/data-types/primitive.md
@@ -21,7 +21,7 @@ session
 // Read a bool from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(bool,)>();
+    .rows_stream::<(bool,)>()?;
 while let Some((bool_value,)) = iter.try_next().await? {
     println!("{:?}", bool_value);
 }
@@ -50,7 +50,7 @@ session
 // Read a tinyint from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(i8,)>();
+    .rows_stream::<(i8,)>()?;
 while let Some((tinyint_value,)) = iter.try_next().await? {
     println!("{:?}", tinyint_value);
 }
@@ -79,7 +79,7 @@ session
 // Read a smallint from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(i16,)>();
+    .rows_stream::<(i16,)>()?;
 while let Some((smallint_value,)) = iter.try_next().await? {
     println!("{}", smallint_value);
 }
@@ -108,7 +108,7 @@ session
 // Read an int from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(i32,)>();
+    .rows_stream::<(i32,)>()?;
 while let Some((int_value,)) = iter.try_next().await? {
     println!("{}", int_value);
 }
@@ -137,7 +137,7 @@ session
 // Read a bigint from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(i64,)>();
+    .rows_stream::<(i64,)>()?;
 while let Some((bigint_value,)) = iter.try_next().await? {
     println!("{:?}", bigint_value);
 }
@@ -166,7 +166,7 @@ session
 // Read a float from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(f32,)>();
+    .rows_stream::<(f32,)>()?;
 while let Some((float_value,)) = iter.try_next().await? {
     println!("{:?}", float_value);
 }
@@ -195,7 +195,7 @@ session
 // Read a double from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(f64,)>();
+    .rows_stream::<(f64,)>()?;
 while let Some((double_value,)) = iter.try_next().await? {
     println!("{:?}", double_value);
 }

diff --git a/docs/source/data-types/text.md b/docs/source/data-types/text.md
@@ -24,7 +24,7 @@ session
 // Read ascii/text/varchar from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(String,)>();
+    .rows_stream::<(String,)>()?;
 while let Some((text_value,)) = iter.try_next().await? {
     println!("{}", text_value);
 }

diff --git a/docs/source/data-types/time.md b/docs/source/data-types/time.md
@@ -32,7 +32,7 @@ session
 // Read time from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(CqlTime,)>();
+    .rows_stream::<(CqlTime,)>()?;
 while let Some((value,)) = iter.try_next().await? {
     // ...
 }
@@ -68,7 +68,7 @@ session
 // Read time from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(NaiveTime,)>();
+    .rows_stream::<(NaiveTime,)>()?;
 while let Some((time_value,)) = iter.try_next().await? {
     println!("{:?}", time_value);
 }
@@ -102,7 +102,7 @@ session
 // Read time from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(Time,)>();
+    .rows_stream::<(Time,)>()?;
 while let Some((time_value,)) = iter.try_next().await? {
     println!("{:?}", time_value);
 }

diff --git a/docs/source/data-types/timestamp.md b/docs/source/data-types/timestamp.md
@@ -33,7 +33,7 @@ session
 // Read timestamp from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(CqlTimestamp,)>();
+    .rows_stream::<(CqlTimestamp,)>()?;
 while let Some((value,)) = iter.try_next().await? {
     // ...
 }
@@ -73,7 +73,7 @@ session
 // Read timestamp from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(DateTime<Utc>,)>();
+    .rows_stream::<(DateTime<Utc>,)>()?;
 while let Some((timestamp_value,)) = iter.try_next().await? {
     println!("{:?}", timestamp_value);
 }
@@ -114,7 +114,7 @@ session
 // Read timestamp from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(OffsetDateTime,)>();
+    .rows_stream::<(OffsetDateTime,)>()?;
 while let Some((timestamp_value,)) = iter.try_next().await? {
     println!("{:?}", timestamp_value);
 }

diff --git a/docs/source/data-types/timeuuid.md b/docs/source/data-types/timeuuid.md
@@ -24,7 +24,7 @@ session
 // Read Timeuuid from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(CqlTimeuuid, )>();
+    .rows_stream::<(CqlTimeuuid, )>()?;
 
 while let Some((timeuuid,)) = iter.try_next().await? {
     println!("Read a value from row: {}", timeuuid);
@@ -68,7 +68,7 @@ session
 // Read Timeuuid from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(CqlTimeuuid, )>();
+    .rows_stream::<(CqlTimeuuid, )>()?;
 
 while let Some((timeuuid,)) = iter.try_next().await? {
     println!("Read a value from row: {}", timeuuid);

diff --git a/docs/source/data-types/tuple.md b/docs/source/data-types/tuple.md
@@ -19,7 +19,7 @@ session
 // Read a tuple of int and string from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<((i32, String),)>();
+    .rows_stream::<((i32, String),)>()?;
 while let Some((tuple_value,)) = iter.try_next().await? {
     let int_value: i32 = tuple_value.0;
     let string_value: String = tuple_value.1;

diff --git a/docs/source/data-types/udt.md b/docs/source/data-types/udt.md
@@ -10,12 +10,12 @@ CREATE TYPE ks.my_type (int_val int, text_val text)
 
 To use this type in the driver, create a matching struct and derive:
 - `SerializeValue`: in order to be able to use this struct in query parameters. \
-    This macro requires fields of UDT and struct to have matching names, but the order
-    of the fields is not required to be the same. \
-    Note: you can use different name using `rename` attribute - see `SerializeValue` macro documentation.
-- `FromUserType`:  in order to be able to use this struct in query results. \
-    This macro requires fields of UDT and struct to be in the same *ORDER*. \
-    This mismatch between `SerializeValue` and `FromUserType` requirements is a temporary situation - in the future `FromUserType` (or  the macro that replaces it) will also require matching names.
+- `DeserializeValue`: in order to be able to use this struct in query results. \
+
+Both macros require fields of UDT and struct to have matching names, but the order
+of the fields is not required to be the same. \
+Note: you can use different name using `rename` attribute - see `SerializeValue`
+and `DeserializeValue` macros documentation.
 
 ```rust
 # extern crate scylla;
@@ -35,13 +35,9 @@ struct MyType {
 ```
 
 > ***Important***\
-> For deserialization, fields in the Rust struct must be defined in the same order as they are in the database.
-> When receiving values, the driver will (de)serialize fields one after another, without looking at field names.
-
-> ***Important***\
-> For serialization, by default fields in the Rust struct must be defined with the same names as they are in the database.
-> The driver will serialize the fields in the order defined by the UDT, matching Rust fields by name.
-> You can change this behaviour using macro attributes, see `SerializeValue` macro documentation for more information.
+> For (de)serialization, by default fields in the Rust struct must be defined with the same names as they are in the database.
+> The driver will (de)serialize the fields in the order defined by the UDT, matching Rust fields by name.
+> You can change this behaviour using macro attributes, see `SerializeValue`/`DeserializeValue` macro documentation for more information.
 
 Now it can be sent and received just like any other CQL value:
 ```rust
@@ -51,10 +47,10 @@ Now it can be sent and received just like any other CQL value:
 # use std::error::Error;
 # async fn check_only_compiles(session: &Session) -> Result<(), Box<dyn Error>> {
 use futures::TryStreamExt;
-use scylla::macros::{FromUserType, SerializeValue};
+use scylla::macros::{DeserializeValue, SerializeValue};
 use scylla::cql_to_rust::FromCqlVal;
 
-#[derive(Debug, FromUserType, SerializeValue)]
+#[derive(Debug, DeserializeValue, SerializeValue)]
 struct MyType {
     int_val: i32,
     text_val: Option<String>,
@@ -73,7 +69,7 @@ session
 // Read MyType from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(MyType,)>();
+    .rows_stream::<(MyType,)>()?;
 while let Some((my_type_value,)) = iter.try_next().await? {
     println!("{:?}", my_type_value);
 }

diff --git a/docs/source/data-types/uuid.md b/docs/source/data-types/uuid.md
@@ -21,7 +21,7 @@ session
 // Read uuid from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(Uuid,)>();
+    .rows_stream::<(Uuid,)>()?;
 while let Some((uuid_value,)) = iter.try_next().await? {
     println!("{:?}", uuid_value);
 }

diff --git a/docs/source/data-types/varint.md b/docs/source/data-types/varint.md
@@ -32,7 +32,7 @@ session
 // Read a varint from the table
 let mut iter = session.query_iter("SELECT a FROM keyspace.table", &[])
     .await?
-    .into_typed::<(BigInt,)>();
+    .rows_stream::<(BigInt,)>()?;
 while let Some((varint_value,)) = iter.try_next().await? {
     println!("{:?}", varint_value);
 }