Struct PutItemRequest 

pub struct PutItemRequest<TD: TableDefinition, T = (), O: OutputFormat = Raw, R: ReturnValue = ReturnNothing, C: ConditionState = NoCondition> { /* private fields */ }

Builder for a DynamoDB PutItem request.

Constructed via DynamoDBItemOp::put (typed, with a concrete T) or PutItemRequest::new (stand-alone, raw output). The builder provides:

• Output format — the result can be deserialized into T. Call .raw() to receive an untyped Item<TD> instead (one-way).
• Return value — by default nothing is returned. Call .return_old() to request the previous item, or .return_none() to revert.
• Condition — optionally add a guard expression via .condition(), .exists(), or .not_exists(). DynamoDB accepts a single condition expression per request, so this can only be called once.

The builder implements IntoFuture, so it can be .awaited directly.

Errors

Returns Err if the DynamoDB request fails, if a condition expression is set and the condition check fails (ConditionalCheckFailedException), or if serialization of self fails.

Examples

use dynamodb_facade::{DynamoDBItemOp, Condition};

let user = sample_user();

// Simple put
user.put(client).await?;

// Create-only: fails if item already exists
user.put(client).not_exists().await?;

// Custom condition
user.put(client)
    .condition(User::not_exists() | Condition::lt("expiration_timestamp", 1_700_000_000))
    .await?;

// Put and return the old item
let old /* : Option<User> */ = user.put(client).return_old().await?;

Implementations

impl<TD: TableDefinition, T, R: ReturnValue, O: OutputFormat, C: ConditionState> PutItemRequest<TD, T, O, R, C>

pub fn into_inner(self) -> PutItemFluentBuilder

Consumes the builder and returns the underlying SDK PutItemFluentBuilder.

Use this escape hatch when you need to set options not exposed by this facade, or when integrating with code that expects the raw SDK builder.

Examples

use dynamodb_facade::DynamoDBItemOp;

let sdk_builder = sample_user().put(client).into_inner();
// configure sdk_builder further, then call .send().await

impl<TD: TableDefinition> PutItemRequest<TD, (), Raw>

pub fn new(client: Client, item: Item<TD>) -> Self

Creates a stand-alone PutItemRequest with raw output (T = (), O = Raw).

Use this when you already have an Item<TD> and do not need typed deserialization of the old value. For typed access, prefer DynamoDBItemOp::put instead.

Examples

use dynamodb_facade::PutItemRequest;

let item = sample_user_item();
PutItemRequest::<PlatformTable>::new(client, item).await?;

impl<TD: TableDefinition, T, O: OutputFormat, C: ConditionState> PutItemRequest<TD, T, O, ReturnNothing, C>

pub fn return_old(self) -> PutItemRequest<TD, T, O, Return<Old>, C>

Requests that DynamoDB return the item’s previous attributes after the put.

When executed, execute returns Option<T> (typed) or Option<Item<TD>> (raw) — None if no item previously existed at that key.

Examples

use dynamodb_facade::DynamoDBItemOp;

let user = sample_user();
let old /* : Option<User> */ = user.put(client).return_old().await?;
// old is None if this was the first put, Some(prev_user) otherwise

impl<TD: TableDefinition, T, O: OutputFormat, C: ConditionState> PutItemRequest<TD, T, O, Return<Old>, C>

pub fn return_none(self) -> PutItemRequest<TD, T, O, ReturnNothing, C>

Reverts the return-value setting so that nothing is returned.

After this call, execute returns () instead of the old item.

Examples

use dynamodb_facade::DynamoDBItemOp;

let user = sample_user();
// Start with return_old, then decide we don't need the old value
user.put(client).return_old().return_none().await?;

impl<TD: TableDefinition, T, O: OutputFormat, R: ReturnValue> PutItemRequest<TD, T, O, R, NoCondition>

pub fn condition( self, condition: Condition<'_>, ) -> PutItemRequest<TD, T, O, R, AlreadyHasCondition>

Adds a condition expression that must be satisfied for the put to succeed.

DynamoDB accepts a single condition expression per request, so this method can only be called once. If the condition fails at runtime, DynamoDB returns a ConditionalCheckFailedException.

For the common item exists/not_exists cases, prefer the .exists() and .not_exists() shorthands.

Examples

use dynamodb_facade::{DynamoDBItemOp, Condition};

let user = sample_user();
// Put only if the item does not exist OR its TTL has expired
user.put(client)
    .condition(User::not_exists() | Condition::lt("expiration_timestamp", 1_700_000_000))
    .await?;

impl<TD: TableDefinition, T: DynamoDBItem<TD>, O: OutputFormat, R: ReturnValue> PutItemRequest<TD, T, O, R, NoCondition>

pub fn exists(self) -> PutItemRequest<TD, T, O, R, AlreadyHasCondition>

Adds an attribute_exists(<PK>) condition, requiring the item to already exist.

Examples

use dynamodb_facade::DynamoDBItemOp;

// Overwrite only if the item already exists
sample_user().put(client).exists().await?;

pub fn not_exists(self) -> PutItemRequest<TD, T, O, R, AlreadyHasCondition>

Adds an attribute_not_exists(<PK>) condition, requiring the item to not yet exist.

Use this to implement create-only (insert-if-absent) semantics.

Examples

use dynamodb_facade::DynamoDBItemOp;

// Create-only: fails if user already exists
sample_user().put(client).not_exists().await?;

impl<TD: TableDefinition, T, R: ReturnValue, C: ConditionState> PutItemRequest<TD, T, Typed, R, C>

pub fn raw(self) -> PutItemRequest<TD, T, Raw, R, C>

Switches the output format from Typed to Raw.

After calling .raw(), execute returns Option<Item<TD>> instead of Option<T> when Return<Old> is active. This transition is one-way.

Examples

use dynamodb_facade::DynamoDBItemOp;

let old_raw = sample_user()
    .put(client)
    .return_old()
    .raw()
    .await?;
// old_raw: Option<Item<PlatformTable>>

impl<TD: TableDefinition, T, O: OutputFormat, C: ConditionState> PutItemRequest<TD, T, O, ReturnNothing, C>

pub fn execute(self) -> impl Future<Output = Result<()>> + Send + 'static

Sends the PutItem request, returning nothing on success.

This method is also available implicitly via .await.

Errors

Returns Err if the DynamoDB request fails or if a condition expression is set and the check fails (ConditionalCheckFailedException).

Examples

use dynamodb_facade::DynamoDBItemOp;

sample_user().put(client).not_exists().execute().await?;

impl<TD: TableDefinition, T: DynamoDBItem<TD> + DeserializeOwned, C: ConditionState> PutItemRequest<TD, T, Typed, Return<Old>, C>

pub fn execute(self) -> impl Future<Output = Result<Option<T>>> + Send + 'static

Sends the PutItem request and returns the previous item deserialized as T.

Returns Ok(None) if no item previously existed at the key.

This method is also available implicitly via .await.

Errors

Returns Err if the DynamoDB request fails, if a condition check fails, or if deserialization of the returned attributes fails.

Examples

use dynamodb_facade::DynamoDBItemOp;

let old /* : Option<User> */ = sample_user().put(client).return_old().execute().await?;
// old is None on first put, Some(previous_user) on subsequent puts

impl<TD: TableDefinition, T, C: ConditionState> PutItemRequest<TD, T, Raw, Return<Old>, C>

pub fn execute( self, ) -> impl Future<Output = Result<Option<Item<TD>>>> + Send + 'static

Sends the PutItem request and returns the previous raw item map.

Returns Ok(None) if no item previously existed at the key.

This method is also available implicitly via .await.

Errors

Returns Err if the DynamoDB request fails or if a condition check fails.

Examples

use dynamodb_facade::DynamoDBItemOp;

let old_raw = sample_user()
    .put(client)
    .return_old()
    .raw()
    .execute()
    .await?;
// old_raw: Option<Item<PlatformTable>>