docs: adding context to timeuuid using v1 feature

[DanielHe4rt]

Motivation

I decided to give more context for newcomers that want to try Timeuuid in the Rust Driver. Since I didn't had that much experience in the beginning and struggled for a while until understand how to use it.

Also I still didn't understand when and how I should generate the the node_id on uuid::new_v1([]) parameters and IMHO it would be a great addition to the docs.

Fixes

• Add context to uuid::v1 usage
• (Optional) Add context to new_v1() node_id numbers

Pre-review checklist

• I have split my patch into logically separate commits.
• All commit messages clearly explain what they change and why.
• I added relevant tests for new features and bug fixes.
• All commits compile, pass static checks and pass test.
• PR description sums up the changes and reasons why they should be introduced.
• I have provided docstrings for the public items that I want to introduce.
• I have adjusted the documentation in ./docs/source/.
• I added appropriate Fixes: annotations to PR description.

[github-actions]

cargo semver-checks found no API-breaking changes in this PR! 🎉🥳
Checked commit: 599a2be

[DanielHe4rt]

Hmm apparently I can't ignore a snippet using the ,ignore flag and I also can't use the v1 flag in the extern crate...

Any ideas on how to make this work properly with extern crate or ignore?

[wprzytula]

I also can't use the v1 flag in the extern crate...

examples/Cargo.toml is the one used to configure deps for the docs. You can call cargo add uuid --dev -F v1 and the feature will be accessible from the docs.

[wprzytula]

Unfortunately, the error message from CI tells me nothing. As it's Sphinx task-related, it's @dgarcia360 who should have a clue about that.

[Lorak-mmk]

Unfortunately, the error message from CI tells me nothing. As it's Sphinx task-related, it's @dgarcia360 who should have a clue about that.

The problem is rust,ignore. We can't use that - our docs need to build both with mdbook and with Scylla's Sphinx setup, so code blocks can only use languages that are recognized by both.

Apart from incompatibility with Sphinx, I don't see why ignore is used - does this sample not compile for some reason? If so, the solution is to make it compile, not to use ignore

[wprzytula]

The problem is rust,ignore. We can't use that - our docs need to build both with mdbook and with Scylla's Sphinx setup, so code blocks can only use languages that are recognized by both.

Ah, right. Then adding v1 to uuid's feature list in examples/Cargo.toml and removing this ignore should fix the problem.

[DanielHe4rt]

@annastuchlik Can you drop a review on it? Just in case I missed something :p

[Lorak-mmk]

One minor typo, apart from this looks good to me

[DanielHe4rt]

Ready to merge!

[wprzytula]

Don't use raw rows field on QueryResult; prefer rows_typed::<(CqlTimeuuid,)>() method:

Suggested change

	if let Some(rows) = session.query("SELECT a FROM keyspace.table", &[]).await?.rows {
	for row in rows.into_typed::<(CqlTimeuuid,)>() {
	let (timeuuid_value,): (CqlTimeuuid,) = row?;
	}
	}
	let mut iter = session.query("SELECT a FROM keyspace.table", &[]).await?.rows_typed::<(CqlTimeuuid,)>();
	while let Some((timeuuid_value,)) = iter.next().transpose()? {
	// do something with timeuuid_value
	}

[DanielHe4rt]

I'll update, but can you explain in details why I shouldn't use it?

[DanielHe4rt]

Fixed! Ready to merge.

[wprzytula]

rows make you interact with an untyped, materialised vec of columns. At the present state of the driver, the main drawback is reduced type safety; as you call into_typed anyway, this negative aspect is mitigated.
Another reason for avoiding using rows ATM, which is relevant here, is the ongoing deserialization refactor. We ditch the materialized vec of CqlValue at all to reduce unnecessary allocations. The new deserialization framework is lazy, which means that the values are going to be deserialized on-the-fly straight to the end type, based on the type provided in the iterator (rows_typed::<T>).
With the new framework having landed in the driver, rows will be removed at all (although their capabilities can be emulated for the users that really need them).

See #955

[wprzytula]

Thank you for your contribution to the docs, @DanielHe4rt !