Struct PutRequest

Source

pub struct PutRequest { /* private fields */ }

Expand description

Struct used for inserting a single row of data into a NoSQL table.

This request can be used to insert data represented as a NoSQL MapValue, or as a native Rust struct using the NoSQLRow derive macro.

This request can perform unconditional and conditional puts:

Overwrite existing row. This is the default.
Succeed only if the row does not exist. Use if_absent() for this case.
Succeed only if the row exists. Use if_present() for this case.
Succeed only if the row exists and its Version matches a specific Version. Use if_version() for this case.

Information about the existing row can be returned from a put operation using return_row(true). Requesting this information incurs additional cost and may affect operation latency.

On successful operation, PutResult::version() is Some. This Version may be used in subsequent PutRequests.

Implementations§

Source §

impl PutRequest

Source

pub fn new(table_name: &str) -> PutRequest

Create a new PutRequest.

table_name should be the name of the table to insert the record into. It is required to be non-empty.

Source

pub fn value(self, val: MapValue) -> PutRequest

Set the row value to use for the put operation, from a MapValue.

Either this method or put() must be called for the PutRequest to be valid.

The fields of the given value will be mapped to their matching table columns on insertion:

use oracle_nosql_rust_sdk::PutRequest;
use oracle_nosql_rust_sdk::types::*;
use chrono::DateTime;

// Assume a table was created with the following statement:
// "CREATE TABLE users (shard integer, id long, name string, street string, city string,
// zip integer, birth timestamp(3), numbers array(long), data binary, num_map map(integer),
// primary key(shard(shard), id))"
// A MapValue may be created a populated to represent the columns of the table as such:
let user = MapValue::new()
     .column("shard", 1)
     .column("id", 123456788)
     .column("name", "Jane".to_string())
     .column("street", Some("321 Main Street".to_string()))
     .column("city", "Anytown".to_string())
     .column("zip", 12345)
     .column("data", Option::<NoSQLBinary>::None)
     .column("numbers", vec![12345i64, 654556578i64, 43543543543543i64, 23232i64])
     .column("birth", Some(DateTime::parse_from_rfc3339("1996-12-19T16:39:57-08:00")?))
     .column("num_map", HashMap::from([("cars".to_string(), 1), ("pets".to_string(), 4)]));

let put_result = PutRequest::new("users")
                 .value(user)
                 .execute(&handle).await?;

Source

pub fn put(self, val: impl NoSQLRow) -> Result<PutRequest, NoSQLError>

Set the row value to use for the put operation, from a given native Rust struct.

Either this method or value() must be called for the PutRequest to be valid.

The fields of the given value will be mapped to their matching table columns on insertion, based on the NoSQLRow derive macro being specified on the given struct:

use oracle_nosql_rust_sdk::PutRequest;
use oracle_nosql_rust_sdk::types::*;
use chrono::{DateTime, FixedOffset};

// Assume a table was created with the following statement:
// "CREATE TABLE users (shard integer, id long, name string, street string, city string,
// zip integer, birth timestamp(3), numbers array(long), data binary, num_map map(integer),
// primary key(shard(shard), id))"
// A corresponding Rust struct may look something like below. Adding the `NoSQLRow`
// derive allows instances of this struct to be written into the table without
// creating an equivalent `MapValue`.
#[derive(Default, Debug, NoSQLRow)]
struct Person {
    pub shard: i32,
    #[nosql(type=long, column=id)]
    pub uuid: i64,
    pub name: String,
    pub birth: Option<DateTime<FixedOffset>>,
    pub street: Option<String>,
    pub data: Option<NoSQLBinary>,
    pub city: String,
    pub zip: i32,
    pub numbers: Vec<i64>,
    pub num_map: HashMap<String, i32>,
}

// Create an instance of the struct and insert it into the NoSQL database:
let user = Person {
     shard: 1,
     uuid: 123456788,
     name: "Jane".to_string(),
     street: Some("321 Main Street".to_string()),
     city: "Anytown".to_string(),
     zip: 12345,
     data: None,
     numbers: vec![12345, 654556578, 43543543543543, 23232],
     birth: Some(DateTime::parse_from_rfc3339("1996-12-19T16:39:57-08:00")?),
     num_map: HashMap::from([("cars".to_string(), 1), ("pets".to_string(), 4)]),
     ..Default::default()
 };

let put_result = PutRequest::new("users")
                 .put(user)?
                 .execute(&handle).await?;

See the GetRequest::execute_into() documentation for another example of using native Rust structs with NoSQLRow.

Source

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

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.

Source

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

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.

Source

pub fn return_row(self, val: bool) -> PutRequest

Return information about the existing row, if present. Requesting this information incurs additional cost and may affect operation latency.

Source

pub fn ttl(self, val: &Duration) -> PutRequest

Specifies the optional time to live (TTL) value, causing the time to live on the row to be set to the specified value on put.

Note: Internally, NoSQL uses a resolution of one hour for TTL values. This value, if given, will be converted to a whole number of hours. The minimum number of hours is 1.

Source

pub fn use_table_ttl(self, val: bool) -> PutRequest

Specifies whether to use the table’s default TTL for the row. If true, and there is an existing row, causes the operation to update the time to live (TTL) value of the row based on the table’s default TTL if set. If the table has no default TTL this setting has no effect. By default updating an existing row has no effect on its TTL.

Source