Struct UpdateItemRequest 

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

Builder for a DynamoDB UpdateItem request.

Constructed via DynamoDBItemOp::update / DynamoDBItemOp::update_by_id (typed, with a concrete T) or UpdateItemRequest::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(), .return_new(), or .return_none() to choose whether DynamoDB returns the pre- or post-update item. .return_new() returns T / Item<TD> directly (DynamoDB’s ALL_NEW always provides the updated item). .return_old() returns Option<T> / Option<Item<TD>> because the item may not have existed before the update (DynamoDB’s UpdateItem is an upsert). Note: DynamoDBItemOp::update_by_id starts with return-new by default.
• 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 check fails, or if deserialization of the returned attributes fails.

Examples

use dynamodb_facade::{DynamoDBItemOp, Condition, KeyId, Update};

// Simple update by ID (returns the updated item by default)
let updated /* : User */ = User::update_by_id(
    client,
    KeyId::pk("user-1"),
    Update::set("role", "instructor"),
)
.await?;

// Update guarded by existence
let updated /* : User */ = User::update_by_id(
    client,
    KeyId::pk("user-1"),
    Update::set("role", "instructor"),
)
.exists()
.await?;

// Update with a custom condition
let updated /* : User */ = User::update_by_id(
    client,
    KeyId::pk("user-1"),
    Update::set("role", "instructor"),
)
.condition(Condition::eq("role", "student"))
.await?;

// Update without returning the item
User::update_by_id(
    client,
    KeyId::pk("user-1"),
    Update::set("name", "Bob"),
)
.exists()
.return_none()
.await?;

Implementations

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

pub fn into_inner(self) -> UpdateItemFluentBuilder

Consumes the builder and returns the underlying SDK UpdateItemFluentBuilder.

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, Update};

let sdk_builder = sample_user()
    .update(client, Update::set("role", "instructor"))
    .into_inner();
// configure sdk_builder further, then call .send().await

impl<TD: TableDefinition> UpdateItemRequest<TD>

pub fn new(client: Client, key: Key<TD>, update: Update<'_>) -> Self

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

Use this when you already have a Key<TD> and an Update expression and do not need typed deserialization of the returned item. For typed access, prefer DynamoDBItemOp::update or DynamoDBItemOp::update_by_id instead.

Examples

use dynamodb_facade::{UpdateItemRequest, Update};

let key = sample_user_item().into_key_only();
UpdateItemRequest::<PlatformTable>::new(client, key, Update::set("role", "instructor"))
    .await?;

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

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

Requests that DynamoDB return the item’s attributes before the update.

When executed, execute returns Option<T> (typed) or Option<Item<TD>> (raw) containing the pre-update state, or None if no item existed at the target key prior to the update.

Examples

use dynamodb_facade::{DynamoDBItemOp, Update};

let before /* : Option<User> */ = sample_user()
    .update(client, Update::set("role", "instructor"))
    .exists()
    .return_old()
    .await?;

pub fn return_new(self) -> UpdateItemRequest<TD, T, O, Return<New>, C>

Requests that DynamoDB return the item’s attributes after the update.

When executed, execute returns T (typed) or Item<TD> (raw) containing the post-update state.

Examples

use dynamodb_facade::{DynamoDBItemOp, Update};

let after /* : User */ = sample_user()
    .update(client, Update::set("role", "instructor"))
    .exists()
    .return_new()
    .await?;

impl<TD: TableDefinition, T, O: OutputFormat, C: ConditionState> UpdateItemRequest<TD, T, O, Return<New>, C>

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

Switches from returning the post-update item to returning the pre-update item.

The execute return type changes from T / Item<TD> to Option<T> / Option<Item<TD>>, because the old item may not exist if the update created it (DynamoDB’s UpdateItem is an upsert).

Examples

use dynamodb_facade::{DynamoDBItemOp, KeyId, Update};

// update_by_id defaults to Return<New>; switch to Return<Old>
let before /* : Option<User> */ = User::update_by_id(
    client,
    KeyId::pk("user-1"),
    Update::set("role", "instructor"),
)
.exists()
.return_old()
.await?;

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

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

After this call, execute returns ().

Examples

use dynamodb_facade::{DynamoDBItemOp, KeyId, Update};

// update_by_id defaults to Return<New>; opt out
User::update_by_id(
    client,
    KeyId::pk("user-1"),
    Update::set("role", "instructor"),
)
.exists()
.return_none()
.await?;

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

pub fn return_new(self) -> UpdateItemRequest<TD, T, O, Return<New>, C>

Switches from returning the pre-update item to returning the post-update item.

The execute return type changes from Option<T> / Option<Item<TD>> to T / Item<TD>, because DynamoDB’s ALL_NEW return mode always includes the full item after the update.

Examples

use dynamodb_facade::{DynamoDBItemOp, Update};

let after /* : User */ = sample_user()
    .update(client, Update::set("role", "instructor"))
    .exists()
    .return_old()
    .return_new()
    .await?;

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

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

After this call, execute returns ().

Examples

use dynamodb_facade::{DynamoDBItemOp, Update};

sample_user()
    .update(client, Update::set("role", "instructor"))
    .exists()
    .return_old()
    .return_none()
    .await?;

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

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

Adds a condition expression that must be satisfied for the update 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, KeyId, Update, Condition};

// Update role only if the current role is not "student"
User::update_by_id(
    client,
    KeyId::pk("user-1"),
    Update::set("role", "instructor"),
)
.condition(Condition::ne("role", "student"))
.await?;

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

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

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

The update fails with ConditionalCheckFailedException if the item does not exist.

Examples

use dynamodb_facade::{DynamoDBItemOp, KeyId, Update};

User::update_by_id(
    client,
    KeyId::pk("user-1"),
    Update::set("name", "Bob"),
)
.exists()
.await?;

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

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

Useful for upsert-style operations where you want to initialize an item only if it does not already exist.

Examples

use dynamodb_facade::{DynamoDBItemOp, KeyId, Update};

User::update_by_id(
    client,
    KeyId::pk("user-1"),
    Update::set("role", "student"),
)
.not_exists()
.await?;

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

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

Switches the output format from Typed to Raw.

After calling .raw(), execute returns Item<TD> instead of T when a return value is requested. This transition is one-way.

Examples

use dynamodb_facade::{DynamoDBItemOp, KeyId, Update};

let raw_new = User::update_by_id(
    client,
    KeyId::pk("user-1"),
    Update::set("role", "instructor"),
)
.exists()
.raw()
.await?;
// raw_new: Item<PlatformTable>

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

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

Sends the UpdateItem 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, KeyId, Update};

User::update_by_id(
    client,
    KeyId::pk("user-1"),
    Update::set("name", "Bob"),
)
.exists()
.return_none()
.execute()
.await?;

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

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

Sends the UpdateItem request and returns the pre-update item deserialized as Option<T>.

Returns Some(T) containing the item’s state before the update was applied, or None if no item existed at the target key prior to the update (DynamoDB’s UpdateItem is an upsert — it creates the item if absent).

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, KeyId, Update};

let before /* : Option<User> */ = User::update_by_id(
    client,
    KeyId::pk("user-1"),
    Update::set("role", "instructor"),
)
.exists()
.return_old()
.execute()
.await?;

impl<TD: TableDefinition, T: DynamoDBItem<TD> + DeserializeOwned, C: ConditionState> UpdateItemRequest<TD, T, Typed, Return<New>, C>

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

Sends the UpdateItem request and returns the post-update item deserialized as T.

Because DynamoDB’s ALL_NEW return mode always includes the full item after the update, this method returns T directly (not Option<T>).

This method is also available implicitly via .await.

Panics

Panics if DynamoDB does not return attributes in the response. This should not happen when ALL_NEW is requested, but could indicate a bug in the SDK or an unexpected API change.

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, KeyId, Update};

let updated /* : User */ = User::update_by_id(
    client,
    KeyId::pk("user-1"),
    Update::set("role", "instructor"),
)
.exists()
.execute()
.await?;

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

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

Sends the UpdateItem request and returns the pre-update raw item map as Option<Item<TD>>.

Returns Some(Item<TD>) containing the item’s state before the update was applied, or None if no item existed at the target key prior to the update (DynamoDB’s UpdateItem is an upsert — it creates the item if absent).

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, KeyId, Update};

let raw /* : Option<dynamodb_facade::Item<PlatformTable>> */ = User::update_by_id(
    client,
    KeyId::pk("user-1"),
    Update::set("role", "instructor"),
)
.exists()
.return_old()
.raw()
.execute()
.await?;

impl<TD: TableDefinition, T, C: ConditionState> UpdateItemRequest<TD, T, Raw, Return<New>, C>

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

Sends the UpdateItem request and returns the post-update raw item map as Item<TD>.

Because DynamoDB’s ALL_NEW return mode always includes the full item after the update, this method returns Item<TD> directly (not Option<Item<TD>>).

This method is also available implicitly via .await.

Panics

Panics if DynamoDB does not return attributes in the response. This should not happen when ALL_NEW is requested, but could indicate a bug in the SDK or an unexpected API change.

Errors

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

Examples

use dynamodb_facade::{DynamoDBItemOp, KeyId, Update};

let raw /* : dynamodb_facade::Item<PlatformTable> */ = User::update_by_id(
    client,
    KeyId::pk("user-1"),
    Update::set("role", "instructor"),
)
.exists()
.raw()
.execute()
.await?;
assert!(raw.get("role").is_some());