From 4ed531c9232235cf0ced7d5175961e4c37e4e799 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miko=C5=82aj=20Uzarski?= Date: Mon, 17 Feb 2025 17:21:21 +0100 Subject: [PATCH] docs: adjust to new terminology - renamed `queries` directory to `statements`. - renamed `queries.md` -> `statements.md`. - rename `simple.md` -> `unprepared.md` Apart from that, I adjusted the documentation to use the new terminology. --- docs/source/SUMMARY.md | 26 ++++++------ docs/source/contents.rst | 2 +- docs/source/data-types/data-types.md | 4 +- .../execution-profiles/create-and-use.md | 8 ++-- .../execution-profiles/maximal-example.md | 4 +- docs/source/execution-profiles/priority.md | 16 +++---- docs/source/execution-profiles/remap.md | 6 +-- docs/source/index.md | 12 +++--- docs/source/queries/lwt.md | 32 -------------- docs/source/retry-policy/default.md | 20 ++++----- .../retry-policy/downgrading-consistency.md | 18 ++++---- docs/source/retry-policy/fallthrough.md | 16 +++---- docs/source/retry-policy/retry-policy.md | 6 +-- docs/source/{queries => statements}/batch.md | 22 +++++----- docs/source/statements/lwt.md | 32 ++++++++++++++ docs/source/{queries => statements}/paged.md | 28 ++++++------- .../{queries => statements}/prepared.md | 36 ++++++++-------- docs/source/{queries => statements}/result.md | 0 .../schema-agreement.md | 6 +-- .../queries.md => statements/statements.md} | 24 +++++------ .../{queries => statements}/timeouts.md | 20 ++++----- .../timestamp-generators.md | 12 +++--- .../simple.md => statements/unprepared.md} | 42 +++++++++---------- .../{queries => statements}/usekeyspace.md | 10 ++--- docs/source/{queries => statements}/values.md | 12 +++--- docs/source/tracing/basic.md | 24 +++++------ docs/source/tracing/paged.md | 10 ++--- docs/source/tracing/prepare.md | 6 +-- docs/source/tracing/query-history.md | 4 +- scylla/src/client/session.rs | 18 ++++---- scylla/src/lib.rs | 2 +- 31 files changed, 239 insertions(+), 239 deletions(-) delete mode 100644 docs/source/queries/lwt.md rename docs/source/{queries => statements}/batch.md (84%) create mode 100644 docs/source/statements/lwt.md rename docs/source/{queries => statements}/paged.md (92%) rename docs/source/{queries => statements}/prepared.md (74%) rename docs/source/{queries => statements}/result.md (100%) rename docs/source/{queries => statements}/schema-agreement.md (88%) rename docs/source/{queries/queries.md => statements/statements.md} (85%) rename docs/source/{queries => statements}/timeouts.md (71%) rename docs/source/{queries => statements}/timestamp-generators.md (84%) rename docs/source/{queries/simple.md => statements/unprepared.md} (70%) rename docs/source/{queries => statements}/usekeyspace.md (89%) rename docs/source/{queries => statements}/values.md (92%) diff --git a/docs/source/SUMMARY.md b/docs/source/SUMMARY.md index 3093d5f355..8b6e6e21a5 100644 --- a/docs/source/SUMMARY.md +++ b/docs/source/SUMMARY.md @@ -5,7 +5,7 @@ - [Quick start](quickstart/quickstart.md) - [Creating a project](quickstart/create-project.md) - [Running Scylla using Docker](quickstart/scylla-docker.md) - - [Connecting and running a simple query](quickstart/example.md) + - [Connecting and executing a simple CQL statement](quickstart/example.md) - [Migration guides](migration-guides/migration-guides.md) - [Adjusting code to changes in serialization API introduced in 0.11](migration-guides/0.11-serialization.md) @@ -16,18 +16,18 @@ - [Authentication](connecting/authentication.md) - [TLS](connecting/tls.md) -- [Making queries](queries/queries.md) - - [Simple query](queries/simple.md) - - [Query values](queries/values.md) - - [Query result](queries/result.md) - - [Prepared query](queries/prepared.md) - - [Batch statement](queries/batch.md) - - [Paged query](queries/paged.md) - - [Lightweight transaction query (LWT)](queries/lwt.md) - - [USE keyspace](queries/usekeyspace.md) - - [Schema agreement](queries/schema-agreement.md) - - [Query timeouts](queries/timeouts.md) - - [Timestamp generators](queries/timestamp-generators.md) +- [Executing CQL statements](statements/statements.md) + - [Unprepared statement](statements/unprepared.md) + - [Statement values](statements/values.md) + - [Query result](statements/result.md) + - [Prepared statement](statements/prepared.md) + - [Batch statement](statements/batch.md) + - [Paged query](statements/paged.md) + - [Lightweight transaction statement (LWT)](statements/lwt.md) + - [USE keyspace](statements/usekeyspace.md) + - [Schema agreement](statements/schema-agreement.md) + - [Query timeouts](statements/timeouts.md) + - [Timestamp generators](statements/timestamp-generators.md) - [Execution profiles](execution-profiles/execution-profiles.md) - [Creating a profile and setting it](execution-profiles/create-and-use.md) diff --git a/docs/source/contents.rst b/docs/source/contents.rst index 5bc4a37c9e..36f9cfa192 100644 --- a/docs/source/contents.rst +++ b/docs/source/contents.rst @@ -6,7 +6,7 @@ index quickstart/quickstart connecting/connecting - queries/queries + statements/statements execution-profiles/execution-profiles data-types/data-types load-balancing/load-balancing diff --git a/docs/source/data-types/data-types.md b/docs/source/data-types/data-types.md index 0d9696e765..143edd161f 100644 --- a/docs/source/data-types/data-types.md +++ b/docs/source/data-types/data-types.md @@ -5,8 +5,8 @@ to achieve seamless sending and receiving of CQL values. See the following chapters for examples on how to send and receive each data type. -See [Query values](../queries/values.md) for more information about sending values in queries.\ -See [Query result](../queries/result.md) for more information about reading values from queries +See [Statement values](../statements/values.md) for more information about sending values in queries.\ +See [Query result](../statements/result.md) for more information about reading values from queries Database types and their Rust equivalents: * `Boolean` <----> `bool` diff --git a/docs/source/execution-profiles/create-and-use.md b/docs/source/execution-profiles/create-and-use.md index ee9553a12c..a1dc4ff58f 100644 --- a/docs/source/execution-profiles/create-and-use.md +++ b/docs/source/execution-profiles/create-and-use.md @@ -28,12 +28,12 @@ let session: Session = SessionBuilder::new() ``` ### Example -To create an `ExecutionProfile` and attach it to a `Query`: +To create an `ExecutionProfile` and attach it to a `Statement`: ```rust # extern crate scylla; # use std::error::Error; # async fn check_only_compiles() -> Result<(), Box> { -use scylla::query::Query; +use scylla::statement::Statement; use scylla::statement::Consistency; use scylla::client::execution_profile::ExecutionProfile; use std::time::Duration; @@ -45,10 +45,10 @@ let profile = ExecutionProfile::builder() let handle = profile.into_handle(); -let mut query1 = Query::from("SELECT * FROM ks.table"); +let mut query1 = Statement::from("SELECT * FROM ks.table"); query1.set_execution_profile_handle(Some(handle.clone())); -let mut query2 = Query::from("SELECT pk FROM ks.table WHERE pk = ?"); +let mut query2 = Statement::from("SELECT pk FROM ks.table WHERE pk = ?"); query2.set_execution_profile_handle(Some(handle)); # Ok(()) # } diff --git a/docs/source/execution-profiles/maximal-example.md b/docs/source/execution-profiles/maximal-example.md index dcbbb82f8d..1c702b94f3 100644 --- a/docs/source/execution-profiles/maximal-example.md +++ b/docs/source/execution-profiles/maximal-example.md @@ -6,7 +6,7 @@ # extern crate scylla; # use std::error::Error; # async fn check_only_compiles() -> Result<(), Box> { -use scylla::query::Query; +use scylla::statement::Statement; use scylla::policies::speculative_execution::SimpleSpeculativeExecutionPolicy; use scylla::statement::{Consistency, SerialConsistency}; use scylla::client::execution_profile::ExecutionProfile; @@ -32,7 +32,7 @@ let profile = ExecutionProfile::builder() ) .build(); -let mut query = Query::from("SELECT * FROM ks.table"); +let mut query = Statement::from("SELECT * FROM ks.table"); query.set_execution_profile_handle(Some(profile.into_handle())); # Ok(()) diff --git a/docs/source/execution-profiles/priority.md b/docs/source/execution-profiles/priority.md index 476f953c1f..2b77df9b3d 100644 --- a/docs/source/execution-profiles/priority.md +++ b/docs/source/execution-profiles/priority.md @@ -15,7 +15,7 @@ Priorities of execution profiles and directly set options: # async fn check_only_compiles() -> Result<(), Box> { use scylla::client::session::Session; use scylla::client::session_builder::SessionBuilder; -use scylla::query::Query; +use scylla::statement::Statement; use scylla::statement::Consistency; use scylla::client::execution_profile::ExecutionProfile; @@ -33,20 +33,20 @@ let session: Session = SessionBuilder::new() .build() .await?; -let mut query = Query::from("SELECT * FROM ks.table"); +let mut query = Statement::from("SELECT * FROM ks.table"); -// Query is not assigned any specific profile, so session's profile is applied. -// Therefore, the query will be executed with Consistency::One. +// Statement is not assigned any specific profile, so session's profile is applied. +// Therefore, the statement will be executed with Consistency::One. session.query_unpaged(query.clone(), ()).await?; query.set_execution_profile_handle(Some(query_profile.into_handle())); -// Query's profile is applied. -// Therefore, the query will be executed with Consistency::Two. +// Statement's profile is applied. +// Therefore, the statement will be executed with Consistency::Two. session.query_unpaged(query.clone(), ()).await?; query.set_consistency(Consistency::Three); -// An option is set directly on the query. -// Therefore, the query will be executed with Consistency::Three. +// An option is set directly on the Statement. +// Therefore, the statement will be executed with Consistency::Three. session.query_unpaged(query, ()).await?; # Ok(()) diff --git a/docs/source/execution-profiles/remap.md b/docs/source/execution-profiles/remap.md index b3b4c04ca8..a0b2a58da9 100644 --- a/docs/source/execution-profiles/remap.md +++ b/docs/source/execution-profiles/remap.md @@ -25,7 +25,7 @@ Below, the remaps described above are followed in code. # async fn check_only_compiles() -> Result<(), Box> { use scylla::client::session::Session; use scylla::client::session_builder::SessionBuilder; -use scylla::query::Query; +use scylla::statement::Statement; use scylla::statement::Consistency; use scylla::client::execution_profile::ExecutionProfile; @@ -46,8 +46,8 @@ let session: Session = SessionBuilder::new() .build() .await?; -let mut query1 = Query::from("SELECT * FROM ks.table"); -let mut query2 = Query::from("SELECT pk FROM ks.table WHERE pk = ?"); +let mut query1 = Statement::from("SELECT * FROM ks.table"); +let mut query2 = Statement::from("SELECT pk FROM ks.table WHERE pk = ?"); query1.set_execution_profile_handle(Some(handle1.clone())); query2.set_execution_profile_handle(Some(handle2.clone())); diff --git a/docs/source/index.md b/docs/source/index.md index d2a6b79313..3aeb16b1ab 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -12,15 +12,15 @@ Although optimized for Scylla, the driver is also compatible with [Apache Cassan ## Contents -* [Quick start](quickstart/quickstart.md) - Setting up a Rust project using `scylla-rust-driver` and running a few queries +* [Quick start](quickstart/quickstart.md) - Setting up a Rust project using `scylla-rust-driver` and executing a few CQL statements * [Migration guides](migration-guides/migration-guides.md) - How to update the code that used an older version of this driver * [Connecting to the cluster](connecting/connecting.md) - Configuring a connection to scylla cluster -* [Making queries](queries/queries.md) - Making different types of queries (simple, prepared, batch, paged) -* [Execution profiles](execution-profiles/execution-profiles.md) - Grouping query execution configuration options together and switching them all at once +* [CQL statement execution](statements/statements.md) - Executing different types of CQL statement (simple, prepared, batch, paged) +* [Execution profiles](execution-profiles/execution-profiles.md) - Grouping statement execution configuration options together and switching them all at once * [Data Types](data-types/data-types.md) - How to use various column data types * [Load balancing](load-balancing/load-balancing.md) - Load balancing configuration -* [Retry policy configuration](retry-policy/retry-policy.md) - What to do when a query fails, query idempotence -* [Driver metrics](metrics/metrics.md) - Statistics about the driver - number of queries, latency etc. +* [Retry policy configuration](retry-policy/retry-policy.md) - What to do when execution attempt fails, statement idempotence +* [Driver metrics](metrics/metrics.md) - Statistics about the driver - number of executed statements, latency etc. * [Logging](logging/logging.md) - Viewing and integrating logs produced by the driver -* [Query tracing](tracing/tracing.md) - Tracing query execution +* [Query tracing](tracing/tracing.md) - Tracing statement execution * [Database schema](schema/schema.md) - Fetching and inspecting database schema diff --git a/docs/source/queries/lwt.md b/docs/source/queries/lwt.md deleted file mode 100644 index 272339d2da..0000000000 --- a/docs/source/queries/lwt.md +++ /dev/null @@ -1,32 +0,0 @@ -# Lightweight transaction (LWT) query - -A lightweight transaction query can be expressed just like any other query, via `Session`, with the notable difference of having an additional consistency level parameter - the `serial_consistency_level`. - - -### Format of the query -A lightweight transaction query is not a separate type - it can be expressed just like any other queries: via `SimpleQuery`, `PreparedStatement`, batches, and so on. The difference lays in the query string itself - when it contains a condition (e.g. `IF NOT EXISTS`), it becomes a lightweight transaction. It's important to remember that CQL specification requires a separate, additional consistency level to be defined for LWT queries - `serial_consistency_level`. The serial consistency level can only be set to two values: `SerialConsistency::Serial` or `SerialConsistency::LocalSerial`. The "local" variant makes the transaction consistent only within the same datacenter. For convenience, Scylla Rust Driver sets the default consistency level to `LocalSerial`, as it's more commonly used. For cross-datacenter consistency, please remember to always override the default with `SerialConsistency::Serial`. -```rust -# extern crate scylla; -# use scylla::client::session::Session; -# use std::error::Error; -# async fn check_only_compiles(session: &Session) -> Result<(), Box> { -use scylla::query::Query; -use scylla::statement::{Consistency, SerialConsistency}; - -// Create a Query manually to change the Consistency to ONE -let mut my_query: Query = Query::new("INSERT INTO ks.tab (a) VALUES(?) IF NOT EXISTS".to_string()); -my_query.set_consistency(Consistency::One); -// Use cross-datacenter serial consistency -my_query.set_serial_consistency(Some(SerialConsistency::Serial)); - -// Insert a value into the table -let to_insert: i32 = 12345; -session.query_unpaged(my_query, (to_insert,)).await?; -# Ok(()) -# } -``` - -The rest of the API remains identical for LWT and non-LWT queries. - -See [Query API documentation](https://docs.rs/scylla/latest/scylla/statement/query/struct.Query.html) for more options - diff --git a/docs/source/retry-policy/default.md b/docs/source/retry-policy/default.md index 3e10fc278b..65e7aa34fd 100644 --- a/docs/source/retry-policy/default.md +++ b/docs/source/retry-policy/default.md @@ -30,36 +30,36 @@ let session: Session = SessionBuilder::new() # } ``` -To use in a [simple query](../queries/simple.md): +To use in an [unprepared statement](../statements/unprepared.md): ```rust # extern crate scylla; # use scylla::client::session::Session; # use std::error::Error; # use std::sync::Arc; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { -use scylla::query::Query; +use scylla::statement::Statement; use scylla::client::execution_profile::ExecutionProfile; use scylla::policies::retry::DefaultRetryPolicy; -// Create a Query manually and set the retry policy -let mut my_query: Query = Query::new("INSERT INTO ks.tab (a) VALUES(?)"); -my_query.set_retry_policy(Some(Arc::new(DefaultRetryPolicy::new()))); +// Create a Statement manually and set the retry policy +let mut my_statement: Statement = Statement::new("INSERT INTO ks.tab (a) VALUES(?)"); +my_statement.set_retry_policy(Some(Arc::new(DefaultRetryPolicy::new()))); // You can also set retry policy in an execution profile let handle = ExecutionProfile::builder() .retry_policy(Arc::new(DefaultRetryPolicy::new())) .build() .into_handle(); -my_query.set_execution_profile_handle(Some(handle)); +my_statement.set_execution_profile_handle(Some(handle)); -// Run the query using this retry policy +// Execute the statement using this retry policy let to_insert: i32 = 12345; -session.query_unpaged(my_query, (to_insert,)).await?; +session.query_unpaged(my_statement, (to_insert,)).await?; # Ok(()) # } ``` -To use in a [prepared query](../queries/prepared.md): +To use in a [prepared statement](../statements/prepared.md): ```rust # extern crate scylla; # use scylla::client::session::Session; @@ -83,7 +83,7 @@ let handle = ExecutionProfile::builder() .into_handle(); prepared.set_execution_profile_handle(Some(handle)); -// Run the query using this retry policy +// Execute the statement using this retry policy let to_insert: i32 = 12345; session.execute_unpaged(&prepared, (to_insert,)).await?; # Ok(()) diff --git a/docs/source/retry-policy/downgrading-consistency.md b/docs/source/retry-policy/downgrading-consistency.md index 7899c85a94..a814857f05 100644 --- a/docs/source/retry-policy/downgrading-consistency.md +++ b/docs/source/retry-policy/downgrading-consistency.md @@ -71,14 +71,14 @@ let session: Session = SessionBuilder::new() # } ``` -To use in a [simple query](../queries/simple.md): +To use in an [unprepared statement](../statements/unprepared.md): ```rust # extern crate scylla; # use scylla::client::session::Session; # use std::error::Error; # use std::sync::Arc; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { -use scylla::query::Query; +use scylla::statement::Statement; use scylla::client::execution_profile::ExecutionProfile; use scylla::policies::retry::DowngradingConsistencyRetryPolicy; @@ -87,18 +87,18 @@ let handle = ExecutionProfile::builder() .build() .into_handle(); -// Create a Query manually and set the retry policy -let mut my_query: Query = Query::new("INSERT INTO ks.tab (a) VALUES(?)"); -my_query.set_execution_profile_handle(Some(handle)); +// Create a Statement manually and set the retry policy +let mut my_statement: Statement = Statement::new("INSERT INTO ks.tab (a) VALUES(?)"); +my_statement.set_execution_profile_handle(Some(handle)); -// Run the query using this retry policy +// Execute the statement using this retry policy let to_insert: i32 = 12345; -session.query_unpaged(my_query, (to_insert,)).await?; +session.query_unpaged(my_statement, (to_insert,)).await?; # Ok(()) # } ``` -To use in a [prepared query](../queries/prepared.md): +To use in a [prepared statement](../statements/prepared.md): ```rust # extern crate scylla; # use scylla::client::session::Session; @@ -122,7 +122,7 @@ let mut prepared: PreparedStatement = session prepared.set_execution_profile_handle(Some(handle)); -// Run the query using this retry policy +// Execute the statement using this retry policy let to_insert: i32 = 12345; session.execute_unpaged(&prepared, (to_insert,)).await?; # Ok(()) diff --git a/docs/source/retry-policy/fallthrough.md b/docs/source/retry-policy/fallthrough.md index 7a5c170075..acd15eb103 100644 --- a/docs/source/retry-policy/fallthrough.md +++ b/docs/source/retry-policy/fallthrough.md @@ -29,14 +29,14 @@ let session: Session = SessionBuilder::new() # } ``` -To use in a [simple query](../queries/simple.md): +To use in an [unprepared statement](../statements/unprepared.md): ```rust # extern crate scylla; # use scylla::client::session::Session; # use std::error::Error; # use std::sync::Arc; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { -use scylla::query::Query; +use scylla::statement::Statement; use scylla::client::execution_profile::ExecutionProfile; use scylla::policies::retry::FallthroughRetryPolicy; @@ -45,18 +45,18 @@ let handle = ExecutionProfile::builder() .build() .into_handle(); -// Create a Query manually and set the retry policy -let mut my_query: Query = Query::new("INSERT INTO ks.tab (a) VALUES(?)"); -my_query.set_execution_profile_handle(Some(handle)); +// Create a Statement manually and set the retry policy +let mut my_statement: Statement = Statement::new("INSERT INTO ks.tab (a) VALUES(?)"); +my_statement.set_execution_profile_handle(Some(handle)); -// Run the query using this retry policy +// Execute the statement using this retry policy let to_insert: i32 = 12345; -session.query_unpaged(my_query, (to_insert,)).await?; +session.query_unpaged(my_statement, (to_insert,)).await?; # Ok(()) # } ``` -To use in a [prepared query](../queries/prepared.md): +To use in a [prepared statement](../statements/prepared.md): ```rust # extern crate scylla; # use scylla::client::session::Session; diff --git a/docs/source/retry-policy/retry-policy.md b/docs/source/retry-policy/retry-policy.md index 03e7adfb98..cd2acf6a4a 100644 --- a/docs/source/retry-policy/retry-policy.md +++ b/docs/source/retry-policy/retry-policy.md @@ -24,11 +24,11 @@ Idempotence has to be specified manually, the driver is not able to figure it ou # use scylla::client::session::Session; # use std::error::Error; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { -use scylla::query::Query; +use scylla::statement::Statement; use scylla::prepared_statement::PreparedStatement; -// Specify that a Query is idempotent -let mut my_query: Query = Query::new("SELECT a FROM ks.tab"); +// Specify that a Statement is idempotent +let mut my_query: Statement = Statement::new("SELECT a FROM ks.tab"); my_query.set_is_idempotent(true); diff --git a/docs/source/queries/batch.md b/docs/source/statements/batch.md similarity index 84% rename from docs/source/queries/batch.md rename to docs/source/statements/batch.md index f64c55a9aa..bff2e52dd6 100644 --- a/docs/source/queries/batch.md +++ b/docs/source/statements/batch.md @@ -1,7 +1,7 @@ # Batch statement A batch statement allows to execute many data-modifying statements at once.\ -These statements can be [simple](simple.md) or [prepared](prepared.md).\ +These statements can be [unprepared](unprepared.md) or [prepared](prepared.md).\ Only `INSERT`, `UPDATE` and `DELETE` statements are allowed. ```rust @@ -10,18 +10,18 @@ Only `INSERT`, `UPDATE` and `DELETE` statements are allowed. # use std::error::Error; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { use scylla::batch::Batch; -use scylla::query::Query; +use scylla::statement::Statement; use scylla::prepared_statement::PreparedStatement; // Create a batch statement let mut batch: Batch = Default::default(); -// Add a simple statement to the batch using its text +// Add an unprepared statement to the batch using its text batch.append_statement("INSERT INTO ks.tab(a, b) VALUES(1, 2)"); -// Add a simple statement created manually to the batch -let simple: Query = Query::new("INSERT INTO ks.tab (a, b) VALUES(3, 4)"); -batch.append_statement(simple); +// Add an unprepared statement created manually to the batch +let unprepared: Statement = Statement::new("INSERT INTO ks.tab (a, b) VALUES(3, 4)"); +batch.append_statement(unprepared); // Add a prepared statement to the batch let prepared: PreparedStatement = session @@ -41,8 +41,8 @@ session.batch(&batch, batch_values).await?; ``` > ***Warning***\ -> Using simple statements with bind markers in batches is strongly discouraged. -> For each simple statement with a non-empty list of values in the batch, +> Using unprepared statements with bind markers in batches is strongly discouraged. +> For each unprepared statement with a non-empty list of values in the batch, > the driver will send a prepare request, and it will be done **sequentially**. > Results of preparation are not cached between `Session::batch` calls. > Consider preparing the statements before putting them into the batch. @@ -103,7 +103,7 @@ See [Batch API documentation](https://docs.rs/scylla/latest/scylla/statement/bat for more options ### Batch values -Batch takes a tuple of values specified just like in [simple](simple.md) or [prepared](prepared.md) queries. +Batch takes a tuple of values specified just like in [unprepared](unprepared.md) or [prepared](prepared.md) statements. Length of batch values must be equal to the number of statements in a batch.\ Each statement must have its values specified, even if they are empty. @@ -142,10 +142,10 @@ session.batch(&batch, batch_values).await?; # Ok(()) # } ``` -For more information about sending values in a statement see [Query values](values.md) +For more information about sending values in a statement see [Statement values](values.md) ### Performance Batch statements do not use token/shard aware load balancing, batches are sent to a random node. -Use [prepared queries](prepared.md) for best performance +Use [prepared statements](prepared.md) for best performance diff --git a/docs/source/statements/lwt.md b/docs/source/statements/lwt.md new file mode 100644 index 0000000000..a583bc6a7f --- /dev/null +++ b/docs/source/statements/lwt.md @@ -0,0 +1,32 @@ +# Lightweight transaction (LWT) statement + +A lightweight transaction statement can be expressed just like any other statement, via `Session`, with the notable difference of having an additional consistency level parameter - the `serial_consistency_level`. + + +### Format of the statement +A lightweight transaction statement is not a separate type - it can be expressed just like any other statements: via `Statement`, `PreparedStatement`, batches, and so on. The difference lays in the statement string itself - when it contains a condition (e.g. `IF NOT EXISTS`), it becomes a lightweight transaction. It's important to remember that CQL specification requires a separate, additional consistency level to be defined for LWT statements - `serial_consistency_level`. The serial consistency level can only be set to two values: `SerialConsistency::Serial` or `SerialConsistency::LocalSerial`. The "local" variant makes the transaction consistent only within the same datacenter. For convenience, Scylla Rust Driver sets the default consistency level to `LocalSerial`, as it's more commonly used. For cross-datacenter consistency, please remember to always override the default with `SerialConsistency::Serial`. +```rust +# extern crate scylla; +# use scylla::client::session::Session; +# use std::error::Error; +# async fn check_only_compiles(session: &Session) -> Result<(), Box> { +use scylla::statement::Statement; +use scylla::statement::{Consistency, SerialConsistency}; + +// Create a Statement manually to change the Consistency to ONE +let mut my_statement: Statement = Statement::new("INSERT INTO ks.tab (a) VALUES(?) IF NOT EXISTS".to_string()); +my_statement.set_consistency(Consistency::One); +// Use cross-datacenter serial consistency +my_statement.set_serial_consistency(Some(SerialConsistency::Serial)); + +// Insert a value into the table +let to_insert: i32 = 12345; +session.query_unpaged(my_statement, (to_insert,)).await?; +# Ok(()) +# } +``` + +The rest of the API remains identical for LWT and non-LWT statements. + +See [Statement API documentation](https://docs.rs/scylla/latest/scylla/statement/struct.Statement.html) for more options + diff --git a/docs/source/queries/paged.md b/docs/source/statements/paged.md similarity index 92% rename from docs/source/queries/paged.md rename to docs/source/statements/paged.md index fb07208ae1..cc3aa365e4 100644 --- a/docs/source/queries/paged.md +++ b/docs/source/statements/paged.md @@ -25,8 +25,8 @@ while prefetching the next one. This limits latency and is a convenient abstract > don't use it for statements that do not benefit from paging. In particular, avoid using it > for non-SELECTs. -On API level, `Session::query_iter` and `Session::execute_iter` take a [simple query](simple.md) -or a [prepared query](prepared.md), respectively, and return a `QueryPager`. `QueryPager` needs +On API level, `Session::query_iter` and `Session::execute_iter` take a [unprepared statement](unprepared.md) +or a [prepared statement](prepared.md), respectively, and return a `QueryPager`. `QueryPager` needs to be converted into typed `Stream` (by calling `QueryPager::rows_stream::`) in order to deserialize rows. @@ -38,14 +38,14 @@ deserialize 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 +> driver will first fully prepare a statement (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: +Use `query_iter` to perform an [unprepared query](unprepared.md) with paging: ```rust # extern crate scylla; # extern crate futures; @@ -94,20 +94,20 @@ while let Some(next_row_res) = rows_stream.next().await { # } ``` -Query values can be passed to `query_iter` and `execute_iter` just like in a [simple query](simple.md) +Statement values can be passed to `query_iter` and `execute_iter` just like in an [unprepared statement](unprepared.md) ### Configuring page size It's possible to configure the size of a single page. -On a `Query`: +On a `Statement`: ```rust # extern crate scylla; # use scylla::client::session::Session; # use std::error::Error; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { -use scylla::query::Query; +use scylla::statement::Statement; -let mut query: Query = Query::new("SELECT a, b FROM ks.t"); +let mut query: Statement = Statement::new("SELECT a, b FROM ks.t"); query.set_page_size(16); let _ = session.query_iter(query, &[]).await?; // ... @@ -145,11 +145,11 @@ On a `Query`: # use scylla::client::session::Session; # use std::error::Error; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { -use scylla::query::Query; +use scylla::statement::Statement; use scylla::response::{PagingState, PagingStateResponse}; use std::ops::ControlFlow; -let paged_query = Query::new("SELECT a, b, c FROM ks.t").with_page_size(6); +let paged_query = Statement::new("SELECT a, b, c FROM ks.t").with_page_size(6); let mut paging_state = PagingState::start(); loop { @@ -188,12 +188,12 @@ On a `PreparedStatement`: # use scylla::client::session::Session; # use std::error::Error; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { -use scylla::query::Query; +use scylla::statement::Statement; use scylla::response::{PagingState, PagingStateResponse}; use std::ops::ControlFlow; let paged_prepared = session - .prepare(Query::new("SELECT a, b, c FROM ks.t").with_page_size(7)) + .prepare(Statement::new("SELECT a, b, c FROM ks.t").with_page_size(7)) .await?; let mut paging_state = PagingState::start(); @@ -227,8 +227,8 @@ loop { ``` ### Performance -For the best performance use [prepared queries](prepared.md). -See [query types overview](queries.md). +For the best performance use [prepared statements](prepared.md). +See [statement types overview](statements.md). ## Best practices diff --git a/docs/source/queries/prepared.md b/docs/source/statements/prepared.md similarity index 74% rename from docs/source/queries/prepared.md rename to docs/source/statements/prepared.md index 53be24e1c5..d3a16770e5 100644 --- a/docs/source/queries/prepared.md +++ b/docs/source/statements/prepared.md @@ -1,12 +1,12 @@ -# Prepared query +# Prepared statement -Prepared queries provide much better performance than simple queries, +Prepared statements provide much better performance than unprepared statements, but they need to be prepared before use. Benefits that prepared statements have to offer: - Type safety - thanks to metadata provided by the server, the driver can verify bound values' types before serialization. This way, we can be always sure that the Rust type provided by the user is compatible (and if not, the error is returned) with the destined native type. The same applies for deserialization. -- Performance - when executing a simple query with non-empty values list, the driver -prepares the statement before execution. The reason for this is to provide type safety for simple queries. However, this implies 2 round trips per simple query execution. On the other hand, the cost of prepared statement's execution is only 1 round trip. +- Performance - when executing an unprepared statement with non-empty values list, the driver +prepares the statement before execution. The reason for this is to provide type safety for unprepared statements. However, this implies 2 round trips per unprepared statement execution. On the other hand, the cost of prepared statement's execution is only 1 round trip. - Improved load-balancing - using the statement metadata, the driver can compute a set of destined replicas for current statement execution. These replicas will be preferred when choosing the node (and shard) to send the request to. For more insight on this, see [performance section](#performance). ```rust @@ -16,12 +16,12 @@ prepares the statement before execution. The reason for this is to provide type # async fn check_only_compiles(session: &Session) -> Result<(), Box> { use scylla::prepared_statement::PreparedStatement; -// Prepare the query for later execution +// Prepare the statement for later execution let prepared: PreparedStatement = session .prepare("INSERT INTO ks.tab (a) VALUES(?)") .await?; -// Run the prepared query with some values, just like a simple query +// Execute the prepared statement with some values, just like an unprepared statement. let to_insert: i32 = 12345; session.execute_unpaged(&prepared, (to_insert,)).await?; # Ok(()) @@ -40,14 +40,14 @@ session.execute_unpaged(&prepared, (to_insert,)).await?; > When page size is set, `execute` will return only the first page of results. ### `Session::prepare` -`Session::prepare` takes query text and prepares the query on all nodes and shards. +`Session::prepare` takes statement text and prepares the statement on all nodes and shards. If at least one succeeds returns success. ### `Session::execute` -`Session::execute` takes a prepared query and bound values and runs the query. -Passing values and the result is the same as in [simple query](simple.md). +`Session::execute` takes a prepared statement and bound values and executes the statement. +Passing values and the result is the same as in [unprepared statement](unprepared.md). -### Query options +### Statement options To specify custom options, set them on the `PreparedStatement` before execution. For example to change the consistency: @@ -60,16 +60,16 @@ For example to change the consistency: use scylla::prepared_statement::PreparedStatement; use scylla::statement::Consistency; -// Prepare the query for later execution +// Prepare the statement for later execution let mut prepared: PreparedStatement = session .prepare("INSERT INTO ks.tab (a) VALUES(?)") .await?; -// Set prepared query consistency to One -// This is the consistency with which this query will be executed +// Set prepared statement consistency to One +// This is the consistency with which this statement will be executed prepared.set_consistency(Consistency::One); -// Run the prepared query with some values, just like a simple query +// Execute the prepared statement with some values, just like an unprepared statement. let to_insert: i32 = 12345; session.execute_unpaged(&prepared, (to_insert,)).await?; # Ok(()) @@ -80,13 +80,13 @@ See [PreparedStatement API documentation](https://docs.rs/scylla/latest/scylla/s for more options. > ***Note*** -> Prepared statements can be created from `Query` structs and will inherit from -> the custom options that the `Query` was created with. +> Prepared statements can be created from `Statement` structs and will inherit from +> the custom options that the `Statement` was created with. > This is especially useful when using `CachingSession::execute` for example. ### Performance -Prepared queries have good performance, much better than simple queries. +Prepared statement have good performance, much better than unprepared statements. By default they use shard/token aware load balancing. > **Always** pass partition key values as bound values. @@ -111,7 +111,7 @@ TABLE ks.prepare_table ( # async fn check_only_compiles(session: &Session) -> Result<(), Box> { use scylla::prepared_statement::PreparedStatement; -// WRONG - partition key value is passed in query string +// WRONG - partition key value is passed in statement string // Load balancing will compute the wrong partition key let wrong_prepared: PreparedStatement = session .prepare("INSERT INTO ks.prepare_table (a, b, c) VALUES(12345, ?, 16)") diff --git a/docs/source/queries/result.md b/docs/source/statements/result.md similarity index 100% rename from docs/source/queries/result.md rename to docs/source/statements/result.md diff --git a/docs/source/queries/schema-agreement.md b/docs/source/statements/schema-agreement.md similarity index 88% rename from docs/source/queries/schema-agreement.md rename to docs/source/statements/schema-agreement.md index 86384e3755..22b4d55538 100644 --- a/docs/source/queries/schema-agreement.md +++ b/docs/source/statements/schema-agreement.md @@ -1,13 +1,13 @@ # Schema agreement -Sometimes after performing queries some nodes have not been updated, so we need a mechanism that checks if every node have agreed on schema version. +Sometimes after executing CQL statements some nodes have not been updated, so we need a mechanism that checks if every node have agreed on schema version. ### Automated awaiting schema agreement -The driver automatically awaits schema agreement after a schema-altering query is executed. +The driver automatically awaits schema agreement after a schema-altering statement is executed. Waiting for schema agreement more than necessary is never a bug, but might slow down applications which do a lot of schema changes (e.g. a migration). For instance, in case where somebody wishes to create a keyspace and then a lot of tables in it, it makes sense only to wait after creating a keyspace -and after creating all the tables rather than after every query. Therefore, the said behaviour can be disabled: +and after creating all the tables rather than after every statement execution. Therefore, the said behaviour can be disabled: ```rust # extern crate scylla; diff --git a/docs/source/queries/queries.md b/docs/source/statements/statements.md similarity index 85% rename from docs/source/queries/queries.md rename to docs/source/statements/statements.md index 4683b6f2b9..9b4c9e1b91 100644 --- a/docs/source/queries/queries.md +++ b/docs/source/statements/statements.md @@ -1,4 +1,4 @@ -# Making queries - best practices +# Executing CQL statements - best practices Driver supports all kinds of statements supported by ScyllaDB. The following tables aim to bridge between DB concepts and driver's API. They include recommendations on which API to use in what cases. @@ -8,19 +8,19 @@ They include recommendations on which API to use in what cases. | Kind of CQL statement | Single | Batch | |-----------------------|---------------------|------------------------------------------| | Prepared | `PreparedStatement` | `Batch` filled with `PreparedStatement`s | -| Unprepared | `Query` | `Batch` filled with `Query`s | +| Unprepared | `Statement` | `Batch` filled with `Statements`s | -This is **NOT** strictly related to content of the CQL query string. +This is **NOT** strictly related to content of the CQL statement string. > ***Interesting note***\ -> In fact, any kind of CQL statement could contain any CQL query string. +> In fact, any kind of CQL statement could contain any CQL statement string. > Yet, some of such combinations don't make sense and will be rejected by the DB. > For example, SELECTs in a Batch are nonsense. -### [Unprepared](simple.md) vs [Prepared](prepared.md) +### [Unprepared](unprepared.md) vs [Prepared](prepared.md) > ***GOOD TO KNOW***\ -> Each time a statement is executed by sending a query string to the DB, it needs to be parsed. Driver does not parse CQL, therefore it sees query strings as opaque.\ +> Each time a statement is executed by sending a statement string to the DB, it needs to be parsed. Driver does not parse CQL, therefore it sees statement strings as opaque.\ > There is an option to *prepare* a statement, i.e. parse it once by the DB and associate it with an ID. After preparation, it's enough that driver sends the ID > and the DB already knows what operation to perform - no more expensive parsing necessary! Moreover, upon preparation driver receives valuable data for load balancing, > enabling advanced load balancing (so better performance!) of all further executions of that prepared statement.\ @@ -61,11 +61,11 @@ This is **NOT** strictly related to content of the CQL query string. ## CQL statements - operations (based on what the CQL string contains) -| CQL data manipulation statement | Recommended statement kind | Recommended Session operation | -|------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------| -| SELECT | `PreparedStatement` if repeated, `Query` if once | `{query,execute}_iter` (or `{query,execute}_single_page` in a manual loop for performance / more control) | -| INSERT, UPDATE | `PreparedStatement` if repeated, `Query` if once, `Batch` if multiple statements are to be executed atomically (LightWeight Transaction) | `{query,execute}_unpaged` (paging is irrelevant, because the result set of such operation is empty) | -| CREATE/DROP {KEYSPACE, TABLE, TYPE, INDEX,...} | `Query`, `Batch` if multiple statements are to be executed atomically (LightWeight Transaction) | `query_unpaged` (paging is irrelevant, because the result set of such operation is empty) | +| CQL data manipulation statement | Recommended statement kind | Recommended Session operation | +|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------| +| SELECT | `PreparedStatement` if repeated, `Statement` if once | `{query,execute}_iter` (or `{query,execute}_single_page` in a manual loop for performance / more control) | +| INSERT, UPDATE | `PreparedStatement` if repeated, `Statement` if once, `Batch` if multiple statements are to be executed atomically (LightWeight Transaction) | `{query,execute}_unpaged` (paging is irrelevant, because the result set of such operation is empty) | +| CREATE/DROP {KEYSPACE, TABLE, TYPE, INDEX,...} | `Statement`, `Batch` if multiple statements are to be executed atomically (LightWeight Transaction) | `query_unpaged` (paging is irrelevant, because the result set of such operation is empty) | ### [Paged](paged.md) vs Unpaged query @@ -97,7 +97,7 @@ There is a special functionality to enable [USE keyspace](usekeyspace.md). :hidden: :glob: - simple + unprepared values result prepared diff --git a/docs/source/queries/timeouts.md b/docs/source/statements/timeouts.md similarity index 71% rename from docs/source/queries/timeouts.md rename to docs/source/statements/timeouts.md index f42cbdcf60..705f324857 100644 --- a/docs/source/queries/timeouts.md +++ b/docs/source/statements/timeouts.md @@ -1,10 +1,10 @@ -# Query timeouts +# Request timeouts -Query execution time can be limited by setting a request timeout. If a query does not complete +CQL statement execution time can be limited by setting a request timeout. If request does not complete in the given time, then `ExecutionError::RequestTimeout` is returned by the driver immediately, -so that application logic can continue operating, but the query may still be in progress on the server. +so that application logic can continue operating, but the request may still be in progress on the server. -As a side note, if one wishes custom server-side timeouts (i.e. actual interruption of query processing), +As a side note, if one wishes custom server-side timeouts (i.e. actual interruption of request processing), one can use a[`USING TIMEOUT ` directive supported in ScyllaDB](https://github.com/scylladb/scylladb/blob/master/docs/cql/cql-extensions.md#using-timeout) (but not in Cassandra). @@ -20,7 +20,7 @@ However, setting per-statement timeout to `None` results in falling back to per- use scylla::client::execution_profile::ExecutionProfile; use scylla::client::session::Session; use scylla::client::session_builder::SessionBuilder; -use scylla::query::Query; +use scylla::statement::Statement; use std::time::Duration; let uri = std::env::var("SCYLLA_URI") @@ -37,7 +37,7 @@ let session: Session = SessionBuilder::new() .build() .await?; -// This query, having no timeout, could block indefinitely if a queried node hangs. +// This statement, having no timeout, could block indefinitely if a queried node hangs. session .query_unpaged("TRUNCATE keyspace.table", ()) .await?; @@ -47,12 +47,12 @@ let three_sec_timeout_profile_handle = ExecutionProfile::builder() .build() .into_handle(); -// The below query will last for no more than 3 seconds, yielding a RequestTimeout error +// The below statement execution will last for no more than 3 seconds, yielding a RequestTimeout error // if no response arrives until then. -let mut query: Query = "TRUNCATE keyspace.table".into(); -query.set_execution_profile_handle(Some(three_sec_timeout_profile_handle)); +let mut statement: Statement = "TRUNCATE keyspace.table".into(); +statement.set_execution_profile_handle(Some(three_sec_timeout_profile_handle)); session - .query_unpaged(query, ()) + .query_unpaged(statement, ()) .await?; # Ok(()) diff --git a/docs/source/queries/timestamp-generators.md b/docs/source/statements/timestamp-generators.md similarity index 84% rename from docs/source/queries/timestamp-generators.md rename to docs/source/statements/timestamp-generators.md index b218c42f5e..58095fcfaf 100644 --- a/docs/source/queries/timestamp-generators.md +++ b/docs/source/statements/timestamp-generators.md @@ -6,8 +6,8 @@ every executed statement will have attached a new timestamp generated by the provided TimestampGenerator. Timestamps are set according to precendence: -1. ```USING TIMESTAMP``` in the query itself -2. Manually using ```set_timestamp``` on the query +1. ```USING TIMESTAMP``` in the statement string itself +2. Manually using ```set_timestamp``` on the statement 3. Timestamp generated by the generator ## Simple Timestamp Generator @@ -33,7 +33,7 @@ be warned about the clock skew, the warnings can be turned off with `without_war use scylla::client::session::Session; use scylla::client::session_builder::SessionBuilder; use scylla::policies::timestamp_generator::MonotonicTimestampGenerator; -use scylla::query::Query; +use scylla::statement::Statement; use std::sync::Arc; let session: Session = SessionBuilder::new() @@ -42,11 +42,11 @@ let session: Session = SessionBuilder::new() .build() .await?; -// This query will have a timestamp generated +// This statement will have a timestamp generated // by the monotonic timestamp generator -let my_query: Query = Query::new("INSERT INTO ks.tab (a) VALUES(?)"); +let my_statement: Statement = Statement::new("INSERT INTO ks.tab (a) VALUES(?)"); let to_insert: i32 = 12345; -session.query_unpaged(my_query, (to_insert,)).await?; +session.query_unpaged(my_statement, (to_insert,)).await?; # Ok(()) # } ``` diff --git a/docs/source/queries/simple.md b/docs/source/statements/unprepared.md similarity index 70% rename from docs/source/queries/simple.md rename to docs/source/statements/unprepared.md index 2300f3675c..365249dd8e 100644 --- a/docs/source/queries/simple.md +++ b/docs/source/statements/unprepared.md @@ -1,11 +1,11 @@ -# Simple query +# Unprepared statement -Simple query takes query text and values and simply executes them on a `Session`: +Unprepared statement takes CQL statement text and values and simply executes them on a `Session`: ```rust # extern crate scylla; # use scylla::client::session::Session; # use std::error::Error; -# async fn simple_query_example(session: &Session) -> Result<(), Box> { +# async fn unprepared_statement_example(session: &Session) -> Result<(), Box> { // Insert a value into the table let to_insert: i32 = 12345; session @@ -16,7 +16,7 @@ session ``` > ***Warning***\ -> Don't use simple query to receive large amounts of data.\ +> Don't use unprepared queries to receive large amounts of data.\ > By default the query is unpaged and might cause heavy load on the cluster.\ > In such cases use [paged query](paged.md) instead.\ > @@ -28,33 +28,33 @@ session > 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_unpaged` takes anything implementing `Into`.\ -You can create a query manually to set custom options. For example to change query consistency: +### First argument - the statement +As the first argument `Session::query_unpaged` takes anything implementing `Into`.\ +You can create a statement manually to set custom options. For example to change statement consistency: ```rust # extern crate scylla; # use scylla::client::session::Session; # use std::error::Error; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { -use scylla::query::Query; +use scylla::statement::Statement; use scylla::statement::Consistency; -// Create a Query manually to change the Consistency to ONE -let mut my_query: Query = Query::new("INSERT INTO ks.tab (a) VALUES(?)"); -my_query.set_consistency(Consistency::One); +// Create a Statement manually to change the Consistency to ONE +let mut my_statement: Statement = Statement::new("INSERT INTO ks.tab (a) VALUES(?)"); +my_statement.set_consistency(Consistency::One); // Insert a value into the table let to_insert: i32 = 12345; -session.query_unpaged(my_query, (to_insert,)).await?; +session.query_unpaged(my_statement, (to_insert,)).await?; # Ok(()) # } ``` -See [Query API documentation](https://docs.rs/scylla/latest/scylla/statement/query/struct.Query.html) for more options +See [Statement API documentation](https://docs.rs/scylla/latest/scylla/statement/struct.Statement.html) for more options ### Second argument - the values -Query text is constant, but the values might change. -You can pass changing values to a query by specifying a list of variables as bound values.\ -Each `?` in query text will be filled with the matching value. +Statement text is constant, but the values might change. +You can pass changing values to a statement by specifying a list of variables as bound values.\ +Each `?` in statement text will be filled with the matching value. The easiest way is to pass values using a tuple: ```rust @@ -84,7 +84,7 @@ Here, we use the `rows` method to check that the response indeed contains rows w # use std::error::Error; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { -// NOTE: using unpaged queries for SELECTs is discouraged in general. +// NOTE: using unpaged queries (SELECTs) is discouraged in general. // Query results may be so big that it is not preferable to fetch them all at once. // Even with small results, if there are a lot of tombstones, then there can be similar bad consequences. // However, `query_unpaged` will return all results in one, possibly giant, piece @@ -115,9 +115,9 @@ while let Some(read_row) = iter.next().transpose()? { See [Query result](result.md) for more information about handling query results ### Performance -Simple queries should not be used in places where performance matters.\ -If performance matters use a [Prepared query](prepared.md) instead. +Unprepared statements should not be used in places where performance matters.\ +If performance matters use a [Prepared statement](prepared.md) instead. -With simple query the database has to parse query text each time it's executed, which worsens performance.\ +With unprepared statement the database has to parse statement text each time it's executed, which worsens performance.\ -Additionally token and shard aware load balancing does not work with simple queries. They are sent to random nodes. +Additionally token and shard aware load balancing does not work with unprepared statements. They are sent to random nodes. diff --git a/docs/source/queries/usekeyspace.md b/docs/source/statements/usekeyspace.md similarity index 89% rename from docs/source/queries/usekeyspace.md rename to docs/source/statements/usekeyspace.md index 819da65ebf..07c87acedb 100644 --- a/docs/source/queries/usekeyspace.md +++ b/docs/source/statements/usekeyspace.md @@ -1,6 +1,6 @@ # USE keyspace -Using a keyspace allows to omit keyspace name in queries. +Using a keyspace allows to omit keyspace name in statements. For example in `cqlsh` one could write: ```sql @@ -38,7 +38,7 @@ session session.use_keyspace("my_keyspace", false).await?; -// Now we can omit keyspace name in the query +// Now we can omit keyspace name in the statement session .query_unpaged("INSERT INTO tab (a) VALUES ('test2')", &[]) .await?; @@ -49,7 +49,7 @@ session The first argument is the keyspace name.\ The second argument states whether this name is case sensitive. -It is also possible to send raw use keyspace query using `Session::query_*` instead of `Session::use_keyspace` such as: +It is also possible to send raw use keyspace statement using `Session::query_*` instead of `Session::use_keyspace` such as: ```rust # extern crate scylla; @@ -64,8 +64,8 @@ session.query_unpaged("USE my_keyspace", &[]).await?; This method has a slightly worse latency than `Session::use_keyspace` - there are two roundtrips needed instead of one. Therefore, `Session::use_keyspace` is the preferred method for setting keyspaces. -### Multiple use queries at once -Don't run multiple `use_keyspace` queries at once. +### Multiple use keyspace requests at once +Don't run multiple `use_keyspace` requests at once. This could end up with half of connections using one keyspace and the other half using the other. ### Case sensitivity diff --git a/docs/source/queries/values.md b/docs/source/statements/values.md similarity index 92% rename from docs/source/queries/values.md rename to docs/source/statements/values.md index 9ff152987b..1f19f9c832 100644 --- a/docs/source/queries/values.md +++ b/docs/source/statements/values.md @@ -1,11 +1,11 @@ -# Query values -Query text is constant, but the values might change. -You can pass changing values to a query by specifying a list of variables as bound values.\ -Each `?` in query text will be filled with the matching value. +# Statement values +Statement text is constant, but the values might change. +You can pass changing values to a statement by specifying a list of variables as bound values.\ +Each `?` in statement text will be filled with the matching value. > **Never** pass values by adding strings, this could lead to [SQL Injection](https://en.wikipedia.org/wiki/SQL_injection) -Each list of values to send in a query must implement the trait `SerializeRow`.\ +Each list of values to send must implement the trait `SerializeRow`.\ By default this can be a slice `&[]`, a tuple `()` (max 16 elements) of values to send, or a custom struct which derives from `SerializeRow`. @@ -57,7 +57,7 @@ session .query_unpaged("INSERT INTO ks.tab (a, b) VALUES(?, ?)", int_string) .await?; -// You can use named bind markers in query if you want +// You can use named bind markers in statement if you want // your names in struct to be different than column names. #[derive(SerializeRow)] struct IntStringCustom { diff --git a/docs/source/tracing/basic.md b/docs/source/tracing/basic.md index c6543dc71b..03d69a4bb3 100644 --- a/docs/source/tracing/basic.md +++ b/docs/source/tracing/basic.md @@ -1,25 +1,25 @@ # Tracing a simple/prepared/batch query -[Simple query](../queries/simple.md), [prepared query](../queries/prepared.md) and [batch query](../queries/batch.md) -return a `QueryResult` which contains a `tracing_id` if tracing was enabled. +[Unprepared statement](../statements/unprepared.md), [prepared statement](../statements/prepared.md) and [batch statement](../statements/batch.md) +execution return a `QueryResult` which contains a `tracing_id` if tracing was enabled. -### Tracing a simple query +### Tracing an unprepared statement execution ```rust # extern crate scylla; # extern crate uuid; # use scylla::client::session::Session; # use std::error::Error; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { -use scylla::query::Query; +use scylla::statement::Statement; use scylla::response::query_result::QueryResult; use scylla::observability::tracing::TracingInfo; use uuid::Uuid; -// Create a Query manually and enable tracing -let mut query: Query = Query::new("INSERT INTO ks.tab (a) VALUES(4)"); -query.set_tracing(true); +// Create a Statement manually and enable tracing +let mut statement: Statement = Statement::new("INSERT INTO ks.tab (a) VALUES(4)"); +statement.set_tracing(true); -let res: QueryResult = session.query_unpaged(query, &[]).await?; +let res: QueryResult = session.query_unpaged(statement, &[]).await?; let tracing_id: Option = res.tracing_id(); if let Some(id) = tracing_id { @@ -31,7 +31,7 @@ if let Some(id) = tracing_id { # } ``` -### Tracing a prepared query +### Tracing a prepared statement ```rust # extern crate scylla; # extern crate uuid; @@ -43,12 +43,12 @@ use scylla::response::query_result::QueryResult; use scylla::observability::tracing::TracingInfo; use uuid::Uuid; -// Prepare the query +// Prepare the statement let mut prepared: PreparedStatement = session .prepare("SELECT a FROM ks.tab") .await?; -// Enable tracing for the prepared query +// Enable tracing for the prepared statement prepared.set_tracing(true); let res: QueryResult = session.execute_unpaged(&prepared, &[]).await?; @@ -63,7 +63,7 @@ if let Some(id) = tracing_id { # } ``` -### Tracing a batch query +### Tracing a batch statement ```rust # extern crate scylla; # extern crate uuid; diff --git a/docs/source/tracing/paged.md b/docs/source/tracing/paged.md index 58f25d3351..2685fd1b4b 100644 --- a/docs/source/tracing/paged.md +++ b/docs/source/tracing/paged.md @@ -12,13 +12,13 @@ If tracing is enabled the row iterator will contain a list of tracing ids for al # use scylla::client::session::Session; # use std::error::Error; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { -use scylla::query::Query; +use scylla::statement::Statement; use scylla::observability::tracing::TracingInfo; use futures::StreamExt; use uuid::Uuid; -// Create a Query manually and enable tracing -let mut query: Query = Query::new("INSERT INTO ks.tab (a) VALUES(4)"); +// Create a Statement manually and enable tracing +let mut query: Statement = Statement::new("SELECT * FROM ks.tab"); query.set_tracing(true); // Create a paged query iterator and fetch pages @@ -55,12 +55,12 @@ use scylla::observability::tracing::TracingInfo; use futures::StreamExt; use uuid::Uuid; -// Prepare the query +// Prepare the statement let mut prepared: PreparedStatement = session .prepare("SELECT a FROM ks.tab") .await?; -// Enable tracing for the prepared query +// Enable tracing for the prepared statement prepared.set_tracing(true); // Create a paged query iterator and fetch pages diff --git a/docs/source/tracing/prepare.md b/docs/source/tracing/prepare.md index 3076523d27..d4d4369586 100644 --- a/docs/source/tracing/prepare.md +++ b/docs/source/tracing/prepare.md @@ -8,13 +8,13 @@ # use scylla::client::session::Session; # use std::error::Error; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { -use scylla::query::Query; +use scylla::statement::Statement; use scylla::prepared_statement::PreparedStatement; use scylla::observability::tracing::TracingInfo; use uuid::Uuid; -// Prepare the query with tracing enabled -let mut to_prepare: Query = Query::new("SELECT a FROM ks.tab"); +// Prepare the statement with tracing enabled +let mut to_prepare: Statement = Statement::new("SELECT a FROM ks.tab"); to_prepare.set_tracing(true); let mut prepared: PreparedStatement = session diff --git a/docs/source/tracing/query-history.md b/docs/source/tracing/query-history.md index d834a38ba3..97dc9921a3 100644 --- a/docs/source/tracing/query-history.md +++ b/docs/source/tracing/query-history.md @@ -11,12 +11,12 @@ This history includes all requests sent, decisions to retry and speculative exec # use scylla::client::session::Session; # use std::error::Error; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { -use scylla::query::Query; +use scylla::statement::Statement; use scylla::observability::history::{HistoryCollector, StructuredHistory}; use std::sync::Arc; // Create a query for which we would like to trace the history of its execution -let mut query: Query = Query::new("SELECT * FROM ks.t"); +let mut query: Statement = Statement::new("SELECT * FROM ks.t"); // Create a history collector and pass it to the query let history_listener = Arc::new(HistoryCollector::new()); diff --git a/scylla/src/client/session.rs b/scylla/src/client/session.rs index c0420be56f..1134a9d475 100644 --- a/scylla/src/client/session.rs +++ b/scylla/src/client/session.rs @@ -381,7 +381,7 @@ impl Session { /// - to receive multiple pages and transparently iterate through them, use [query_iter](Session::query_iter). /// - to manually receive multiple pages and iterate through them, use [query_single_page](Session::query_single_page). /// - /// See [the book](https://rust-driver.docs.scylladb.com/stable/queries/simple.html) for more information + /// See [the book](https://rust-driver.docs.scylladb.com/stable/statements/unprepared.html) for more information /// # Arguments /// * `statement` - statement to be executed, can be just a `&str` or the [`Statement`] struct. /// * `values` - values bound to the statement, the easiest way is to use a tuple of bound values. @@ -501,7 +501,7 @@ impl Session { /// trait method returns false). In such case, statement 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. + /// See [the book](https://rust-driver.docs.scylladb.com/stable/statements/paged.html) for more information. /// /// # Arguments /// * `statement` - statement to be executed, can be just a `&str` or the [`Statement`] struct. @@ -552,9 +552,9 @@ impl Session { /// > ***Warning***\ /// > For token/shard aware load balancing to work properly, all partition key values /// > must be sent as bound values - /// > (see [performance section](https://rust-driver.docs.scylladb.com/stable/queries/prepared.html#performance)). + /// > (see [performance section](https://rust-driver.docs.scylladb.com/stable/statements/prepared.html#performance)). /// - /// See [the book](https://rust-driver.docs.scylladb.com/stable/queries/prepared.html) for more information. + /// See [the book](https://rust-driver.docs.scylladb.com/stable/statements/prepared.html) for more information. /// /// # Arguments /// * `prepared` - the prepared statement to execute, generated using [`Session::prepare`](Session::prepare) @@ -658,7 +658,7 @@ impl Session { /// Returns an async iterator (stream) over all received rows.\ /// Page size can be specified in the [PreparedStatement] passed to the function. /// - /// See [the book](https://rust-driver.docs.scylladb.com/stable/queries/paged.html) for more information. + /// See [the book](https://rust-driver.docs.scylladb.com/stable/statements/paged.html) for more information. /// /// # Arguments /// * `prepared` - the prepared statement to execute, generated using [`Session::prepare`](Session::prepare) @@ -710,7 +710,7 @@ impl Session { /// send (numer_of_unprepared_statements_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 + /// See [the book](https://rust-driver.docs.scylladb.com/stable/statements/batch.html) for more information /// /// # Arguments /// * `batch` - [Batch] to be performed @@ -1139,9 +1139,9 @@ impl Session { /// > ***Warning***\ /// > For token/shard aware load balancing to work properly, all partition key values /// > must be sent as bound values - /// > (see [performance section](https://rust-driver.docs.scylladb.com/stable/queries/prepared.html#performance)) + /// > (see [performance section](https://rust-driver.docs.scylladb.com/stable/statements/prepared.html#performance)) /// - /// See [the book](https://rust-driver.docs.scylladb.com/stable/queries/prepared.html) for more information. + /// See [the book](https://rust-driver.docs.scylladb.com/stable/statements/prepared.html) for more information. /// See the documentation of [`PreparedStatement`]. /// /// # Arguments @@ -1537,7 +1537,7 @@ impl Session { /// Trying to do two `use_keyspace` requests simultaneously with different names /// can end with some connections using one keyspace and the rest using the other. /// - /// See [the book](https://rust-driver.docs.scylladb.com/stable/queries/usekeyspace.html) for more information + /// See [the book](https://rust-driver.docs.scylladb.com/stable/statements/usekeyspace.html) for more information /// /// # Arguments /// diff --git a/scylla/src/lib.rs b/scylla/src/lib.rs index d2a417ac1f..3670194f2d 100644 --- a/scylla/src/lib.rs +++ b/scylla/src/lib.rs @@ -90,7 +90,7 @@ //! # Ok(()) //! # } //! ``` -//! See the [book](https://rust-driver.docs.scylladb.com/stable/queries/result.html) for more receiving methods +//! See the [book](https://rust-driver.docs.scylladb.com/stable/statements/result.html) for more receiving methods #![cfg_attr(docsrs, feature(doc_auto_cfg))]