Struct QueryRequest

pub struct QueryRequest { /* private fields */ }

Encapsulates a SQL query of a NoSQL Database table.

A query may be either a string query statement or a prepared query, which may include bind variables. A query request cannot have both a string statement and prepared query, but it must have one or the other.

See the SQL for NoSQL Database Guide for details on creating and using queries.

Simple Example

Here is a simple example of running a query that will return every row in a table named users:

let handle = Handle::builder().build().await?;
let results = QueryRequest::new("select * from users")
              .execute(&handle).await?;
for row in results.rows() {
    println!("Row = {}", row);
}

For performance reasons, prepared queries are preferred for queries that may be reused. Prepared queries bypass compilation of the query. They also allow for parameterized queries using bind variables.

Implementations

impl QueryRequest

pub fn new(statement: &str) -> Self

Create a new QueryRequest from a SQL query string.

While this struct is named QueryRequest, the SQL supplied to it does not necessarily have to be a SELECT query. It could also be one of INSERT, UPDATE, or DELETE.

See the SQL for NoSQL Database Guide for details on creating and using queries.

Note: this request should not be used for DDL statements (those that create or modify tables or indexes, such as CREATE TABLE). For DDL statements, use TableRequest instead.

pub fn new_prepared(prepared_statement: &PreparedStatement) -> Self

Create a new QueryRequest from a previously prepared query statement.

Use of this method is recommended when executing the same type of query multiple times with different values for parameters. Doing so will save resources by not re-preparing the query on every execution.

To set bind variables for query execution, first create the request with this method, then call QueryRequest::set_variable() for all desired bind variables. Then execute the query with QueryRequest::execute().

pub fn prepare_only(self) -> Self

Specify that this query execution should only prepare the query.

Setting this value to true and then calling QueryRequest::execute() will result in only the query being prepared, and no result rows being returned. The prepared statement can then be retrieved using QueryResult::prepared_statement() and can be used in subsequent query calls using QueryRequest::new_prepared().

pub fn timeout(self, t: &Duration) -> Self

Specify the timeout value for the request.

This is optional. If set, it must be greater than or equal to 1 millisecond, otherwise an IllegalArgument error will be returned. If not set, the default timeout value configured for the Handle is used.

pub fn compartment_id(self, compartment_id: &str) -> Self

Cloud Service only: set the name or id of a compartment to be used for this operation.

The compartment may be specified as either a name (or path for nested compartments) or as an id (OCID). A name (vs id) can only be used when authenticated using a specific user identity. It is not available if the associated handle authenticated as an Instance Principal (which can be done when calling the service from a compute instance in the Oracle Cloud Infrastructure: see HandleBuilder::cloud_auth_from_instance().)

If no compartment is given, the root compartment of the tenancy will be used.

pub fn consistency(self, c: &Consistency) -> Self

Specify the desired consistency policy for the request.

If not set, the default consistency of Consistency::Eventual is used.

pub fn max_read_kb(self, max: u32) -> Self

Specify the limit on the total data read during a single batch operation, in KB.

For cloud service, this value can only reduce the system defined limit. An attempt to increase the limit beyond the system defined limit will cause an IllegalArgument error. This limit is independent of read units consumed by the operation.

It is recommended that for tables with relatively low provisioned read throughput that this limit be set to less than or equal to one half of the provisioned throughput in order to reduce the possibility of throttling errors.

pub fn max_write_kb(self, max: u32) -> Self

Specify the limit on the total data written during a single batch operation, in KB.

For cloud service, this value can only reduce the system defined limit. An attempt to increase the limit beyond the system defined limit will cause an IllegalArgument error. This limit is independent of write units consumed by the operation.

This limit is independent of write units consumed by the operation.

pub fn set_variable( &mut self, name: &str, value: &impl NoSQLColumnToFieldValue, ) -> Result<(), NoSQLError>

Set a named bind variable for execution of a prepared query.

See PreparedStatement for an example of using this method.

pub fn set_variable_by_id( &mut self, id: i32, value: &impl NoSQLColumnToFieldValue, ) -> Result<(), NoSQLError>

Set a positional bind variable for execution of a prepared query.

This is similar to set_variable() but uses integer-based positional parameters:

let handle = Handle::builder().build().await?;
let prep_result = QueryRequest::new("insert into testusers(id, name) values(?, ?)")
    .prepare_only()
    .execute(&handle)
    .await?;
let data = vec!["jane", "john", "jasper"];
let mut qreq = QueryRequest::new_prepared(&prep_result.prepared_statement());
for i in 0..data.len() {
    let id = (i as i32) + 100;
    qreq.set_variable_by_id(1, &id)?;
    qreq.set_variable_by_id(2, &data[i])?;
    let result = qreq.execute(&handle).await?;
    println!("Insert result = {:?}", result);
}

pub async fn execute(&mut self, h: &Handle) -> Result<QueryResult, NoSQLError>

Execute the query to full completion.

This is the preferred method for execution of a query. Internally, this method will loop calling execute_batch() until all results are returned and all post-processing (sorting, grouping, aggregations, etc) are complete.

If the query has no rows to return, QueryResult::rows() will return an empty vector. Otherwise it will return a vector of MapValue structs in the order specified by the query statement.

pub async fn execute_batch( &mut self, handle: &Handle, results: &mut Vec<MapValue>, ) -> Result<(), NoSQLError>

Execute one batch of a query.

This will execute at most one round-trip to the server. It should be called in a loop until is_done() returns true. Note that any one batch execution may not set any results, since some queries require many server round trips to finish (sorting, for example).

It is recommended to use execute() instead of this method. This method may be deprecated in future releases.

pub fn is_done(&self) -> bool

Determine if the query is complete.

If using QueryRequest::execute_batch() in a loop, this method determines when to terminate the loop, specifying that no more results exist for this query execution. This is only necessary if executing queries in batch looping mode.

Trait Implementations

impl Debug for QueryRequest

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for QueryRequest

fn default() -> QueryRequest

Returns the “default value” for a type.