diff --git a/docs/source/SUMMARY.md b/docs/source/SUMMARY.md index 63639364fa..32f266c149 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 an unprepared 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) @@ -15,17 +15,17 @@ - [Authentication](connecting/authentication.md) - [TLS](connecting/tls.md) -- [Making queries](queries/queries.md) - - [Simple query](queries/simple.md) - - [Query values](queries/values.md) +- [Executing statements](queries/queries.md) + - [Unprepared statement](queries/simple.md) + - [Statement bound values](queries/values.md) - [Query result](queries/result.md) - - [Prepared query](queries/prepared.md) + - [Prepared statement](queries/prepared.md) - [Batch statement](queries/batch.md) - - [Paged query](queries/paged.md) - - [Lightweight transaction query (LWT)](queries/lwt.md) + - [Paged statement execution](queries/paged.md) + - [Lightweight transaction statement (LWT)](queries/lwt.md) - [USE keyspace](queries/usekeyspace.md) - [Schema agreement](queries/schema-agreement.md) - - [Query timeouts](queries/timeouts.md) + - [Statement execution timeouts](queries/timeouts.md) - [Execution profiles](execution-profiles/execution-profiles.md) - [Creating a profile and setting it](execution-profiles/create-and-use.md) @@ -67,10 +67,10 @@ - [Logging](logging/logging.md) -- [Query tracing](tracing/tracing.md) - - [Tracing a simple/prepared query](tracing/basic.md) - - [Tracing a paged query](tracing/paged.md) +- [Statement execution tracing](tracing/tracing.md) + - [Tracing a statement execution](tracing/basic.md) + - [Tracing a paged statement execution](tracing/paged.md) - [Tracing `Session::prepare`](tracing/prepare.md) - - [Query Execution History](tracing/query-history.md) + - [Statement Execution History](tracing/query-history.md) - [Database schema](schema/schema.md) diff --git a/docs/source/data-types/data-types.md b/docs/source/data-types/data-types.md index 0d9696e765..e35d387b96 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 bound values](../queries/values.md) for more information about sending values in statements.\ +See [Statement execution result](../queries/result.md) for more information about reading values after executing a statement. Database types and their Rust equivalents: * `Boolean` <----> `bool` diff --git a/docs/source/data-types/udt.md b/docs/source/data-types/udt.md index c2ed650738..a6226ddd07 100644 --- a/docs/source/data-types/udt.md +++ b/docs/source/data-types/udt.md @@ -3,17 +3,17 @@ Scylla allows users to define their own data types with named fields (See [the o To use user defined types in the driver, you can create a corresponding struct in Rust, and use it to read and write UDT values. -For example let's say `my_type` was created using this query: +For example let's say `my_type` was created using this statement: ```sql CREATE TYPE ks.my_type (int_val int, text_val text) ``` To use this type in the driver, create a matching struct and derive: -- `SerializeCql`: in order to be able to use this struct in query parameters. \ +- `SerializeCql`: in order to be able to use this struct in statement 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 `SerializeCql` macro documentation. -- `FromUserType`: in order to be able to use this struct in query results. \ +- `FromUserType`: in order to be able to use this struct in statement execution results. \ This macro requires fields of UDT and struct to be in the same *ORDER*. \ This mismatch between `SerializeCql` and `FromUserType` requirements is a temporary situation - in the future `FromUserType` (or the macro that replaces it) will also require matching names. diff --git a/docs/source/execution-profiles/create-and-use.md b/docs/source/execution-profiles/create-and-use.md index 01bfa52d99..05e157985f 100644 --- a/docs/source/execution-profiles/create-and-use.md +++ b/docs/source/execution-profiles/create-and-use.md @@ -27,12 +27,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 an `UnpreparedStatement`: ```rust # extern crate scylla; # use std::error::Error; # async fn check_only_compiles() -> Result<(), Box> { -use scylla::query::Query; +use scylla::unprepared_statement::UnpreparedStatement; use scylla::statement::Consistency; use scylla::transport::ExecutionProfile; use std::time::Duration; @@ -44,10 +44,10 @@ let profile = ExecutionProfile::builder() let handle = profile.into_handle(); -let mut query1 = Query::from("SELECT * FROM ks.table"); +let mut query1 = UnpreparedStatement::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 = UnpreparedStatement::from("SELECT pk FROM ks.table WHERE pk = ?"); query2.set_execution_profile_handle(Some(handle)); # Ok(()) # } diff --git a/docs/source/execution-profiles/execution-profiles.md b/docs/source/execution-profiles/execution-profiles.md index 6f36726aff..ca6f984300 100644 --- a/docs/source/execution-profiles/execution-profiles.md +++ b/docs/source/execution-profiles/execution-profiles.md @@ -1,6 +1,6 @@ # Execution profiles -Execution profiles are a way to group various query execution configuration options together. Profiles can be created to represent different workloads, which can be run conveniently on a single session. +Execution profiles are a way to group various statement execution configuration options together. Profiles can be created to represent different workloads, which can be run conveniently on a single session. The settings that an execution profile encapsulates are [as follows](maximal-example.md): * consistency diff --git a/docs/source/execution-profiles/maximal-example.md b/docs/source/execution-profiles/maximal-example.md index 8209b926a1..8f7d1633e0 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::unprepared_statement::UnpreparedStatement; use scylla::speculative_execution::SimpleSpeculativeExecutionPolicy; use scylla::statement::{Consistency, SerialConsistency}; use scylla::transport::ExecutionProfile; @@ -32,7 +32,7 @@ let profile = ExecutionProfile::builder() ) .build(); -let mut query = Query::from("SELECT * FROM ks.table"); +let mut query = UnpreparedStatement::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 4ae22d2c86..78bba0b263 100644 --- a/docs/source/execution-profiles/priority.md +++ b/docs/source/execution-profiles/priority.md @@ -14,7 +14,7 @@ Priorities of execution profiles and directly set options: # use std::error::Error; # async fn check_only_compiles() -> Result<(), Box> { use scylla::{Session, SessionBuilder}; -use scylla::query::Query; +use scylla::unprepared_statement::UnpreparedStatement; use scylla::statement::Consistency; use scylla::transport::ExecutionProfile; @@ -32,20 +32,20 @@ let session: Session = SessionBuilder::new() .build() .await?; -let mut query = Query::from("SELECT * FROM ks.table"); +let mut query = UnpreparedStatement::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(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(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(query, ()).await?; # Ok(()) diff --git a/docs/source/execution-profiles/remap.md b/docs/source/execution-profiles/remap.md index a64aee3916..87bcd64177 100644 --- a/docs/source/execution-profiles/remap.md +++ b/docs/source/execution-profiles/remap.md @@ -24,7 +24,7 @@ Below, the remaps described above are followed in code. # use std::error::Error; # async fn check_only_compiles() -> Result<(), Box> { use scylla::{Session, SessionBuilder}; -use scylla::query::Query; +use scylla::unprepared_statement::UnpreparedStatement; use scylla::statement::Consistency; use scylla::transport::ExecutionProfile; @@ -45,8 +45,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 = UnpreparedStatement::from("SELECT * FROM ks.table"); +let mut query2 = UnpreparedStatement::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..0066312503 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 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 +* [Executing statements](queries/queries.md) - Creating and executing different types of statements (unprepared, 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 a statement execution 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 +* [Statement execution tracing](tracing/tracing.md) - Tracing statement execution * [Database schema](schema/schema.md) - Fetching and inspecting database schema diff --git a/docs/source/load-balancing/default-policy.md b/docs/source/load-balancing/default-policy.md index 4f8310a36f..04e8492575 100644 --- a/docs/source/load-balancing/default-policy.md +++ b/docs/source/load-balancing/default-policy.md @@ -2,7 +2,7 @@ `DefaultPolicy` is the default load balancing policy in Scylla Rust Driver. It can be configured to be datacenter-aware and token-aware. Datacenter failover -for queries with non-local consistency mode is also supported. +for statements with non-local consistency mode is also supported. ## Creating a DefaultPolicy @@ -107,7 +107,7 @@ Every `update_rate` the global minimum average latency is computed, and all nodes whose average latency is worse than `exclusion_threshold` times the global minimum average latency become penalised for `retry_period`. Penalisation involves putting those nodes at the very end -of the query plan. As it is often not truly beneficial to prefer +of the statement execution plan. As it is often not truly beneficial to prefer faster non-replica than replicas lagging behind the non-replicas, this mechanism may as well worsen latencies and/or throughput. diff --git a/docs/source/load-balancing/load-balancing.md b/docs/source/load-balancing/load-balancing.md index 3ec27dd7e1..e02db1d2f9 100644 --- a/docs/source/load-balancing/load-balancing.md +++ b/docs/source/load-balancing/load-balancing.md @@ -3,9 +3,9 @@ ## Introduction The driver uses a load balancing policy to determine which node(s) and shard(s) -to contact when executing a query. Load balancing policies implement the +to contact when executing a statement. Load balancing policies implement the `LoadBalancingPolicy` trait, which contains methods to generate a load -balancing plan based on the query information and the state of the cluster. +balancing plan based on the statement information and the state of the cluster. Load balancing policies do not influence to which nodes connections are being opened. For a node connection blacklist configuration refer to @@ -16,9 +16,9 @@ In this chapter, "target" will refer to a pair ``. ## Plan -When a query is prepared to be sent to the database, the load balancing policy +When a statement is prepared to be sent to the database, the load balancing policy constructs a load balancing plan. This plan is essentially a list of targets to -which the driver will try to send the query. The first elements of the plan are +which the driver will try to send the statement. The first elements of the plan are the targets which are the best to contact (e.g. they might be replicas for the requested data or have the best latency). @@ -73,7 +73,7 @@ let session: Session = SessionBuilder::new() In addition to being able to configure load balancing policies through execution profiles at the session level, the driver also allow for setting -execution profile handles on a per-query basis. This means that for each query, +execution profile handles on a per-statement basis. This means that for each statement, a specific execution profile can be selected with a customized load balancing settings. @@ -81,12 +81,12 @@ settings. ### `pick` and `fallback`: -Most queries are sent successfully on the first try. In such cases, only the +Most statements are executed successfully on the first try. In such cases, only the first element of the load balancing plan is needed, so it's usually unnecessary to compute entire load balancing plan. To optimize this common case, the `LoadBalancingPolicy` trait provides two methods: `pick` and `fallback`. -`pick` returns the first target to contact for a given query, which is usually +`pick` returns the first target to contact for a given statement, which is usually the best based on a particular load balancing policy. `fallback`, returns an iterator that provides the rest of the targets in the @@ -94,7 +94,7 @@ load balancing plan. `fallback` is called when using the initial picked target fails (or when executing speculatively) or when `pick` returned `None`. It's possible for the `fallback` method to include the same target that was -returned by the `pick` method. In such cases, the query execution layer filters +returned by the `pick` method. In such cases, the statement execution layer filters out the picked target from the iterator returned by `fallback`. ### `on_query_success` and `on_query_failure`: @@ -103,13 +103,13 @@ The `on_query_success` and `on_query_failure` methods are useful for load balancing policies because they provide feedback on the performance and health of the nodes in the cluster. -When a query is successfully executed, the `on_query_success` method is called +When a statement is successfully executed, the `on_query_success` method is called and can be used by the load balancing policy to update its internal state. For example, a policy might use the latency of the successful query to update its latency statistics for each node in the cluster. This information can be used to make decisions about which nodes to contact in the future. -On the other hand, when a query fails to execute, the `on_query_failure` method +On the other hand, when a statement fails to execute, the `on_query_failure` method is called and provides information about the failure. The error message returned by Cassandra can help determine the cause of the failure, such as a node being down or overloaded. The load balancing policy can use this diff --git a/docs/source/logging/logging.md b/docs/source/logging/logging.md index 198b3291f4..3a7ec72635 100644 --- a/docs/source/logging/logging.md +++ b/docs/source/logging/logging.md @@ -33,7 +33,7 @@ async fn main() -> Result<(), Box> { ) .await?; - // This query should generate a warning message + // This statement should generate a warning message session.query("USE ks", &[]).await?; Ok(()) diff --git a/docs/source/metrics/metrics.md b/docs/source/metrics/metrics.md index ce52615383..3393420535 100644 --- a/docs/source/metrics/metrics.md +++ b/docs/source/metrics/metrics.md @@ -5,11 +5,11 @@ During operation the driver collects various metrics. They can be accessed at any moment using `Session::get_metrics()` ### Collected metrics: -* Query latencies -* Total number of nonpaged queries -* Number of errors during nonpaged queries -* Total number of paged queries -* Number of errors during paged queries +* Statement execution latencies +* Total number of nonpaged statements +* Number of errors during nonpaged statements' execution +* Total number of paged statements +* Number of errors during paged statements' execution * Number of retries ### Example diff --git a/docs/source/migration-guides/0.11-serialization.md b/docs/source/migration-guides/0.11-serialization.md index 4df222592c..dea3af5d3b 100644 --- a/docs/source/migration-guides/0.11-serialization.md +++ b/docs/source/migration-guides/0.11-serialization.md @@ -4,7 +4,7 @@ When executing a statement through the CQL protocol, values for the bind markers are sent in a serialized, untyped form. In order to implement a safer and more robust interface, drivers can use the information returned after preparing a statement to check the type of data provided by the user against the actual types of the bind markers. -Before 0.11, the driver couldn't do this kind of type checking. For example, in the case of non-batch queries, the only information about the user data it has is that it implements `ValueList` - defined as follows: +Before 0.11, the driver couldn't do this kind of type checking. For example, in the case of non-batch statements, the only information about the user data it has is that it implements `ValueList` - defined as follows: ```rust # extern crate scylla; @@ -29,7 +29,7 @@ In version 0.11, a new set of traits is introduced and the old ones are deprecat Both the old and the new APIs are based on three core traits: - `Value` - called `SerializeCql` in the new API. A type that can serialize itself to a single CQL value. For example, `i32` serializes itself into a representation that is compatible with the CQL `int` type. -- `ValueList` - called `SerializeRow` in the new API. A type that can serialize itself as a list of values for a CQL statement. For example, a `(i32, &str)` produces a list of two values which can be used in a query with two bind markers, e.g. `SELECT * FROM table WHERE pk = ? AND ck = ?`. Optionally, values in the produced list may be associated with names which is useful when using it with a query with named bind markers, e.g. `SELECT * FROM table WHERE pk = :pk AND ck = :ck`. +- `ValueList` - called `SerializeRow` in the new API. A type that can serialize itself as a list of values for a CQL statement. For example, a `(i32, &str)` produces a list of two values which can be used in a statement with two bind markers, e.g. `SELECT * FROM table WHERE pk = ? AND ck = ?`. Optionally, values in the produced list may be associated with names which is useful when using it with a statement with named bind markers, e.g. `SELECT * FROM table WHERE pk = :pk AND ck = :ck`. - `LegacyBatchValues`, previously named `BatchValues` - in new API replaced with new trait called (again) `BatchValues`. Represents a source of data for a batch request. It is essentially equivalent to a list of `ValueList`, one for each statement in the batch. For example, `((1, 2), (3, 4, 5))` can be used for a batch with two statements, the first one having two bind markers and the second one having three. All methods which take one of the old traits were changed to take the new trait - notably, this includes `Session::query`, `(Caching)Session::execute`, `(Caching)Session::batch`. @@ -71,12 +71,12 @@ As explained in the [Background](#background) section, the driver uses data retu > **NOTE:** The driver will skip preparation if it detects that the list of values for the statement is empty, as there is nothing to be type checked. -If you send simple statements along with non-empty lists of values, the slowdown will be as follows: +If you send unprepared statements along with non-empty lists of values, the slowdown will be as follows: - For `Session::query`, the driver will prepare the statement before sending it, incurring an additional round-trip. - For `Session::batch`, the driver will send a prepare request for each *unique* unprepared statement with a non-empty list of values. **This is done serially!** -In both cases, if the additional roundtrips are unacceptable, you should prepare the statements beforehand and reuse them - which aligns with our general recommendation against use of simple statements in performance sensitive scenarios. +In both cases, if the additional roundtrips are unacceptable, you should prepare the statements beforehand and reuse them - which aligns with our general recommendation against use of unprepared statements in performance sensitive scenarios. ### Migrating from old to new traits *gradually* diff --git a/docs/source/queries/batch.md b/docs/source/queries/batch.md index 4d9694c45e..6fa2bbb1c5 100644 --- a/docs/source/queries/batch.md +++ b/docs/source/queries/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](simple.md) or [prepared](prepared.md).\ Only `INSERT`, `UPDATE` and `DELETE` statements are allowed. ```rust @@ -10,17 +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::unprepared_statement::UnpreparedStatement; 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)"); +// Add an unprepared statement created manually to the batch +let simple: UnpreparedStatement = + UnpreparedStatement::new("INSERT INTO ks.tab (a, b) VALUES(3, 4)"); batch.append_statement(simple); // Add a prepared statement to the batch @@ -41,8 +42,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 +104,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](simple.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 +143,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 bound 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/queries/lwt.md b/docs/source/queries/lwt.md index afe0d9dc5c..3537d14392 100644 --- a/docs/source/queries/lwt.md +++ b/docs/source/queries/lwt.md @@ -1,20 +1,21 @@ -# Lightweight transaction (LWT) query +# Lightweight transaction (LWT) statement -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`. +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 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`. +### Format of the statement +A lightweight transaction statement is not a separate type - it can be expressed just like any other statements: via `UnpreparedStatement`, `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::Session; # use std::error::Error; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { -use scylla::query::Query; +use scylla::unprepared_statement::UnpreparedStatement; 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()); +// Create an UnpreparedStatement manually to change the Consistency to ONE +let mut my_query: UnpreparedStatement = + UnpreparedStatement::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)); @@ -26,7 +27,7 @@ session.query(my_query, (to_insert,)).await?; # } ``` -The rest of the API remains identical for LWT and non-LWT queries. +The rest of the API remains identical for LWT and non-LWT statements. -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/unprepared_statement/struct.UnpreparedStatement.html) for more options diff --git a/docs/source/queries/paged.md b/docs/source/queries/paged.md index 8112c9308b..57d3aa4e55 100644 --- a/docs/source/queries/paged.md +++ b/docs/source/queries/paged.md @@ -2,19 +2,19 @@ Sometimes query results might not fit in a single page. Paged queries allow to receive the whole result page by page. -`Session::query_iter` and `Session::execute_iter` take a [simple query](simple.md) or a [prepared query](prepared.md) +`Session::query_iter` and `Session::execute_iter` take an [unprepared statement](simple.md) or a [prepared statement](prepared.md) and return an `async` iterator over result `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 execute an [unprepared statement](simple.md) with paging: ```rust # extern crate scylla; # extern crate futures; @@ -37,7 +37,7 @@ while let Some(next_row_res) = rows_stream.next().await { # } ``` -Use `execute_iter` to perform a [prepared query](prepared.md) with paging: +Use `execute_iter` to execute a [prepared statement](prepared.md) with paging: ```rust # extern crate scylla; # extern crate futures; @@ -65,20 +65,21 @@ 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) +Bound values can be passed to `query_iter` and `execute_iter` just like in an [unprepared statement](simple.md) ### Configuring page size It's possible to configure the size of a single page. -On a `Query`: +On an `UnpreparedStatement`: ```rust # extern crate scylla; # use scylla::Session; # use std::error::Error; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { -use scylla::query::Query; +use scylla::unprepared_statement::UnpreparedStatement; -let mut query: Query = Query::new("SELECT a, b FROM ks.t"); +let mut query: UnpreparedStatement = + UnpreparedStatement::new("SELECT a, b FROM ks.t"); query.set_page_size(16); let _ = session.query_iter(query, &[]).await?; // ... @@ -110,15 +111,16 @@ It's possible to fetch a single page from the table, extract the paging state from the result and manually pass it to the next query. That way, the next query will start fetching the results from where the previous one left off. -On a `Query`: +On an `UnpreparedStatement`: ```rust # extern crate scylla; # use scylla::Session; # use std::error::Error; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { -use scylla::query::Query; +use scylla::unprepared_statement::UnpreparedStatement; -let paged_query = Query::new("SELECT a, b, c FROM ks.t").with_page_size(6); +let paged_query = UnpreparedStatement::new("SELECT a, b, c FROM ks.t") + .with_page_size(6); let res1 = session.query(paged_query.clone(), &[]).await?; let res2 = session .query_paged(paged_query.clone(), &[], res1.paging_state) @@ -138,10 +140,10 @@ On a `PreparedStatement`: # use scylla::Session; # use std::error::Error; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { -use scylla::query::Query; +use scylla::unprepared_statement::UnpreparedStatement; let paged_prepared = session - .prepare(Query::new("SELECT a, b, c FROM ks.t").with_page_size(7)) + .prepare(UnpreparedStatement::new("SELECT a, b, c FROM ks.t").with_page_size(7)) .await?; let res1 = session.execute(&paged_prepared, &[]).await?; let res2 = session @@ -153,4 +155,4 @@ let res2 = session ### Performance Performance is the same as in non-paged variants.\ -For the best performance use [prepared queries](prepared.md). \ No newline at end of file +For the best performance use [prepared statements](prepared.md). \ No newline at end of file diff --git a/docs/source/queries/prepared.md b/docs/source/queries/prepared.md index f8230b6a5f..d7d8564b1d 100644 --- a/docs/source/queries/prepared.md +++ b/docs/source/queries/prepared.md @@ -1,6 +1,6 @@ -# 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. ```rust @@ -10,12 +10,12 @@ but they need to be prepared before use. # 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(&prepared, (to_insert,)).await?; # Ok(()) @@ -34,14 +34,14 @@ session.execute(&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](simple.md). -### Query options +### Statement options To specify custom options, set them on the `PreparedStatement` before execution. For example to change the consistency: @@ -54,16 +54,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(&prepared, (to_insert,)).await?; # Ok(()) @@ -74,13 +74,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 `UnpreparedStatement` structs and will inherit from +> the custom options that the `UnpreparedStatement` 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 statements 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. @@ -105,7 +105,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/queries.md b/docs/source/queries/queries.md index b75810d0ad..ca875833c9 100644 --- a/docs/source/queries/queries.md +++ b/docs/source/queries/queries.md @@ -1,11 +1,11 @@ -# Making queries +# Creating and executing statements -This driver supports all query types available in Scylla: -* [Simple queries](simple.md) +This driver supports all statement types available in Scylla: +* [Unprepared statements](simple.md) * Easy to use * Poor performance * Primitive load balancing -* [Prepared queries](prepared.md) +* [Prepared statements](prepared.md) * Need to be prepared before use * Fast * Properly load balanced @@ -16,7 +16,7 @@ This driver supports all query types available in Scylla: * Allows to read result in multiple pages when it doesn't fit in a single response * Can be prepared for better performance and load balancing -Additionally there is special functionality to enable `USE KEYSPACE` queries: +Additionally there is special functionality to enable `USE KEYSPACE` statements: [USE keyspace](usekeyspace.md) Queries are fully asynchronous - you can run as many of them in parallel as you wish. diff --git a/docs/source/queries/simple.md b/docs/source/queries/simple.md index d065f52d2d..c74b77ecdc 100644 --- a/docs/source/queries/simple.md +++ b/docs/source/queries/simple.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 statement text and values and simply executes them on a `Session`: ```rust # extern crate scylla; # use scylla::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,11 +16,11 @@ session ``` > ***Warning***\ -> Don't use simple query to receive large amounts of data.\ -> By default the query is unpaged and might cause heavy load on the cluster.\ -> In such cases set a page size and use [paged query](paged.md) instead.\ +> Don't use unprepared statements to receive large amounts of data.\ +> By default the statement execution is unpaged and might cause heavy load on the cluster.\ +> In such cases set a page size and use [paged statement](paged.md) instead.\ > -> When page size is set, `query` will return only the first page of results. +> When page size is set, `Session::query` will return only the first page of results. > ***Warning***\ > If the values are not empty, driver first needs to send a `PREPARE` request @@ -35,11 +35,12 @@ You can create a query manually to set custom options. For example to change que # use scylla::Session; # use std::error::Error; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { -use scylla::query::Query; +use scylla::unprepared_statement::UnpreparedStatement; 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(?)"); +// Create an UnpreparedStatement manually to change the Consistency to ONE +let mut my_query: UnpreparedStatement = + UnpreparedStatement::new("INSERT INTO ks.tab (a) VALUES(?)"); my_query.set_consistency(Consistency::One); // Insert a value into the table @@ -48,7 +49,7 @@ session.query(my_query, (to_insert,)).await?; # Ok(()) # } ``` -See [Query API documentation](https://docs.rs/scylla/latest/scylla/statement/query/struct.Query.html) for more options +See [Query API documentation](https://docs.rs/scylla/latest/scylla/statement/unprepared_statement/struct.UnpreparedStatement.html) for more options ### Second argument - the values Query text is constant, but the values might change. @@ -92,15 +93,15 @@ while let Some(read_row) = iter.next().transpose()? { # Ok(()) # } ``` -> In cases where page size is set, simple query returns only a single page of results.\ -> To receive all pages use a [paged query](paged.md) instead.\ +> In cases where page size is set, unprepared statement returns only a single page of results.\ +> To receive all pages use a [paged statement](paged.md) instead.\ 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/quickstart/example.md b/docs/source/quickstart/example.md index 32e01b2d5f..6431894fff 100644 --- a/docs/source/quickstart/example.md +++ b/docs/source/quickstart/example.md @@ -1,4 +1,4 @@ -# Connecting and running a simple query +# Connecting and executing an unprepared statement Now everything is ready to use the driver. Here is a small example: diff --git a/docs/source/retry-policy/default.md b/docs/source/retry-policy/default.md index e1f8514ed4..d448d2b9b9 100644 --- a/docs/source/retry-policy/default.md +++ b/docs/source/retry-policy/default.md @@ -28,19 +28,20 @@ let session: Session = SessionBuilder::new() # } ``` -To use in a [simple query](../queries/simple.md): +To use in an [unprepared statement](../queries/simple.md): ```rust # extern crate scylla; # use scylla::Session; # use std::error::Error; # use std::sync::Arc; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { -use scylla::query::Query; +use scylla::unprepared_statement::UnpreparedStatement; use scylla::transport::ExecutionProfile; use scylla::transport::retry_policy::DefaultRetryPolicy; // Create a Query manually and set the retry policy -let mut my_query: Query = Query::new("INSERT INTO ks.tab (a) VALUES(?)"); +let mut my_query: UnpreparedStatement = + UnpreparedStatement::new("INSERT INTO ks.tab (a) VALUES(?)"); my_query.set_retry_policy(Some(Arc::new(DefaultRetryPolicy::new()))); // You can also set retry policy in an execution profile diff --git a/docs/source/retry-policy/downgrading-consistency.md b/docs/source/retry-policy/downgrading-consistency.md index 711329ec80..cfe230641c 100644 --- a/docs/source/retry-policy/downgrading-consistency.md +++ b/docs/source/retry-policy/downgrading-consistency.md @@ -69,13 +69,13 @@ let session: Session = SessionBuilder::new() # } ``` -To use in a [simple query](../queries/simple.md): +To use in an [unprepared statement](../queries/simple.md): ```rust # extern crate scylla; # use scylla::Session; # use std::error::Error; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { -use scylla::query::Query; +use scylla::unprepared_statement::UnpreparedStatement; use scylla::transport::ExecutionProfile; use scylla::transport::downgrading_consistency_retry_policy::DowngradingConsistencyRetryPolicy; @@ -84,8 +84,9 @@ 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(?)"); +// Create an UnpreparedStatement manually and set the retry policy +let mut my_query: UnpreparedStatement = + UnpreparedStatement::new("INSERT INTO ks.tab (a) VALUES(?)"); my_query.set_execution_profile_handle(Some(handle)); // Run the query using this retry policy diff --git a/docs/source/retry-policy/fallthrough.md b/docs/source/retry-policy/fallthrough.md index 0f6ab59388..f4a32427fa 100644 --- a/docs/source/retry-policy/fallthrough.md +++ b/docs/source/retry-policy/fallthrough.md @@ -27,13 +27,13 @@ let session: Session = SessionBuilder::new() # } ``` -To use in a [simple query](../queries/simple.md): +To use in an [unprepared statement](../queries/simple.md): ```rust # extern crate scylla; # use scylla::Session; # use std::error::Error; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { -use scylla::query::Query; +use scylla::unprepared_statement::UnpreparedStatement; use scylla::transport::ExecutionProfile; use scylla::transport::retry_policy::FallthroughRetryPolicy; @@ -42,8 +42,9 @@ 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(?)"); +// Create an UnpreparedStatement manually and set the retry policy +let mut my_query: UnpreparedStatement = + UnpreparedStatement::new("INSERT INTO ks.tab (a) VALUES(?)"); my_query.set_execution_profile_handle(Some(handle)); // Run the query using this retry policy diff --git a/docs/source/retry-policy/retry-policy.md b/docs/source/retry-policy/retry-policy.md index b4859b0c89..d0e4619a94 100644 --- a/docs/source/retry-policy/retry-policy.md +++ b/docs/source/retry-policy/retry-policy.md @@ -24,11 +24,12 @@ Idempotence has to be specified manually, the driver is not able to figure it ou # use scylla::Session; # use std::error::Error; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { -use scylla::query::Query; +use scylla::unprepared_statement::UnpreparedStatement; use scylla::prepared_statement::PreparedStatement; // Specify that a Query is idempotent -let mut my_query: Query = Query::new("SELECT a FROM ks.tab"); +let mut my_query: UnpreparedStatement = + UnpreparedStatement::new("SELECT a FROM ks.tab"); my_query.set_is_idempotent(true); diff --git a/docs/source/tracing/basic.md b/docs/source/tracing/basic.md index 4ee5bc5737..3ef504a639 100644 --- a/docs/source/tracing/basic.md +++ b/docs/source/tracing/basic.md @@ -1,22 +1,23 @@ -# Tracing a simple/prepared/batch query +# Tracing an unprepared/prepared/batch statement execution -[Simple query](../queries/simple.md), [prepared query](../queries/prepared.md) and [batch query](../queries/batch.md) +[Unprepared statement](../queries/simple.md), [prepared statement](../queries/prepared.md) and [batch statement](../queries/batch.md) 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::Session; # use std::error::Error; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { -use scylla::query::Query; +use scylla::unprepared_statement::UnpreparedStatement; use scylla::QueryResult; use scylla::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)"); +// Create an UnpreparedStatement manually and enable tracing +let mut query: UnpreparedStatement = + UnpreparedStatement::new("INSERT INTO ks.tab (a) VALUES(4)"); query.set_tracing(true); let res: QueryResult = session.query(query, &[]).await?; @@ -31,7 +32,7 @@ if let Some(id) = tracing_id { # } ``` -### Tracing a prepared query +### Tracing a prepared statement execution ```rust # extern crate scylla; # extern crate uuid; @@ -43,12 +44,12 @@ use scylla::QueryResult; use scylla::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(&prepared, &[]).await?; diff --git a/docs/source/tracing/paged.md b/docs/source/tracing/paged.md index e69d4f3361..16341928d8 100644 --- a/docs/source/tracing/paged.md +++ b/docs/source/tracing/paged.md @@ -1,7 +1,7 @@ # Tracing a paged query -A paged query performs multiple simple/prepared queries to query subsequent pages.\ -If tracing is enabled the row iterator will contain a list of tracing ids for all performed queries. +A paged query performs multiple unprepared/prepared statements to query subsequent pages.\ +If tracing is enabled the row iterator will contain a list of tracing ids for all executed statements. ### Tracing `Session::query_iter` @@ -12,14 +12,15 @@ If tracing is enabled the row iterator will contain a list of tracing ids for al # use scylla::Session; # use std::error::Error; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { -use scylla::query::Query; +use scylla::unprepared_statement::UnpreparedStatement; use scylla::transport::iterator::RowIterator; use scylla::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)"); +let mut query: UnpreparedStatement = + UnpreparedStatement::new("INSERT INTO ks.tab (a) VALUES(4)"); query.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 2f3850cbde..e714606e29 100644 --- a/docs/source/tracing/prepare.md +++ b/docs/source/tracing/prepare.md @@ -8,13 +8,14 @@ # use scylla::Session; # use std::error::Error; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { -use scylla::query::Query; +use scylla::unprepared_statement::UnpreparedStatement; use scylla::prepared_statement::PreparedStatement; use scylla::tracing::TracingInfo; use uuid::Uuid; // Prepare the query with tracing enabled -let mut to_prepare: Query = Query::new("SELECT a FROM ks.tab"); +let mut to_prepare: UnpreparedStatement = + UnpreparedStatement::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 1c0779259e..a776ab1045 100644 --- a/docs/source/tracing/query-history.md +++ b/docs/source/tracing/query-history.md @@ -11,12 +11,13 @@ This history includes all requests sent, decisions to retry and speculative exec # use scylla::Session; # use std::error::Error; # async fn check_only_compiles(session: &Session) -> Result<(), Box> { -use scylla::query::Query; +use scylla::unprepared_statement::UnpreparedStatement; use scylla::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"); +// Create an UnpreparedStatement for which we would like to trace the history of its execution +let mut query: UnpreparedStatement = + UnpreparedStatement::new("SELECT * FROM ks.t"); // Create a history collector and pass it to the query let history_listener = Arc::new(HistoryCollector::new());