DynamoDB Rust: AWS SDK Query and CRUD Cheat Sheet

Use aws-sdk-dynamodb with aws-config and Tokio to call DynamoDB from Rust. Configure the client with BehaviorVersion::latest(), build requests with the fluent API, and use into_paginator() for complete Query and Scan results. The SDK exposes typed AttributeValue maps; optional serde_dynamo conversion lets application code use Rust structs.

Table of contents

• Setup
• Create table
• Delete table
• List tables
• Get all items / Scan
• Get item
• Batch get item
• Put item
• Batch write / put item
• Query for a set of items
• Query an index
• Update item
• Conditionally update item
• Increment an item attribute
• Delete item
• Delete all items
• Simple transaction
• Read transaction
• Query with sorting
• Query and Scan pagination
• Handle SdkError and service errors

Setup

Create a project and add these dependencies to Cargo.toml. The versions checked for this refresh are aws-sdk-dynamodb 1.134.0 and aws-config 1.13.0; both declare Rust 1.94.1 as their minimum supported Rust version. Keep your application's Cargo.lock so later compatible releases do not silently change a deployment.

cargo new dynamodb-examples
cd dynamodb-examples
cargo new dynamodb-examples
cd dynamodb-examples

[dependencies]
aws-config = "1.13.0"
aws-sdk-dynamodb = "1.134.0"
tokio = { version = "1", features = ["macros", "rt-multi-thread", "time"] }
serde = { version = "1", features = ["derive"] }
serde_dynamo = { version = "4.3.0", features = ["aws-sdk-dynamodb+1"] }
fastrand = "2"
[dependencies]
aws-config = "1.13.0"
aws-sdk-dynamodb = "1.134.0"
tokio = { version = "1", features = ["macros", "rt-multi-thread", "time"] }
serde = { version = "1", features = ["derive"] }
serde_dynamo = { version = "4.3.0", features = ["aws-sdk-dynamodb+1"] }
fastrand = "2"

The AWS SDK crate reference documents its types and operations. aws-config supplies the credential and Region provider chains. Use AWS_PROFILE and AWS_REGION locally, or the workload's IAM role on AWS; never embed real credentials.

Put this first block in src/main.rs, then add the remaining Rust functions below it. The shared imports cover the whole collection. The entry point constructs a client without making writes; call only the operation you want to test. Run cargo check to check the combined example.

use std::{collections::HashMap, time::Duration};
use aws_config::BehaviorVersion;
use aws_sdk_dynamodb::{
    client::Waiters,
    error::SdkError,
    operation::{put_item::PutItemError, query::QueryOutput},
    types::{
        AttributeDefinition, AttributeValue, BillingMode, Get, GlobalSecondaryIndex,
        KeySchemaElement, KeysAndAttributes, KeyType, Projection, ProjectionType,
        Put, PutRequest, ReturnValue, ScalarAttributeType, TransactGetItem,
        TransactWriteItem, Update, WriteRequest,
    },
    Client,
};
use serde::{Deserialize, Serialize};

type ItemMap = HashMap<String, AttributeValue>;
type BoxError = Box<dyn std::error::Error + Send + Sync>;
const TABLE: &str = "my-table";

#[derive(Debug, Serialize, Deserialize)]
pub struct Pokemon {
    pub name: String,
    #[serde(rename = "createdAt")]
    pub created_at: i32,
    pub pokemon_type: String,
    #[serde(default)]
    pub score: i32,
}

fn key(name: &str, date: i32) -> ItemMap {
    HashMap::from([
        ("name".into(), AttributeValue::S(name.into())),
        ("createdAt".into(), AttributeValue::N(date.to_string())),
    ])
}

#[tokio::main]
async fn main() -> Result<(), BoxError> {
    let config = aws_config::load_defaults(BehaviorVersion::latest()).await;
    let _client = Client::new(&config);
    println!("DynamoDB client ready");
    Ok(())
}
use std::{collections::HashMap, time::Duration};
use aws_config::BehaviorVersion;
use aws_sdk_dynamodb::{
    client::Waiters,
    error::SdkError,
    operation::{put_item::PutItemError, query::QueryOutput},
    types::{
        AttributeDefinition, AttributeValue, BillingMode, Get, GlobalSecondaryIndex,
        KeySchemaElement, KeysAndAttributes, KeyType, Projection, ProjectionType,
        Put, PutRequest, ReturnValue, ScalarAttributeType, TransactGetItem,
        TransactWriteItem, Update, WriteRequest,
    },
    Client,
};
use serde::{Deserialize, Serialize};

type ItemMap = HashMap<String, AttributeValue>;
type BoxError = Box<dyn std::error::Error + Send + Sync>;
const TABLE: &str = "my-table";

#[derive(Debug, Serialize, Deserialize)]
pub struct Pokemon {
    pub name: String,
    #[serde(rename = "createdAt")]
    pub created_at: i32,
    pub pokemon_type: String,
    #[serde(default)]
    pub score: i32,
}

fn key(name: &str, date: i32) -> ItemMap {
    HashMap::from([
        ("name".into(), AttributeValue::S(name.into())),
        ("createdAt".into(), AttributeValue::N(date.to_string())),
    ])
}

#[tokio::main]
async fn main() -> Result<(), BoxError> {
    let config = aws_config::load_defaults(BehaviorVersion::latest()).await;
    let _client = Client::new(&config);
    println!("DynamoDB client ready");
    Ok(())
}

Every example uses my-table with String partition key name and Number sort key createdAt. Dates are numeric YYYYMMDD examples. GSI1 uses String pokemon_type and Number createdAt. This lets the same sample items support both individual lookups and type-based queries.

The optional serde_dynamo project is unarchived and its published 4.3.0 release supports AWS SDK 1.x through the aws-sdk-dynamodb+1 feature. Its latest published release was September 2025, so treat it as a third-party dependency rather than an AWS support commitment. The integration below is compatible with the SDK versions shown here; low-level examples work without a serializer.

Create table

Define only the attributes used as table or index keys. Required-field builders such as AttributeDefinition and KeySchemaElement return a Result; propagate build errors with ?. Creation is asynchronous, so use the SDK waiter instead of assuming a successful CreateTable response means the table is active.

pub async fn create_table(client: &Client) -> Result<(), BoxError> {
    let index = GlobalSecondaryIndex::builder()
        .index_name("GSI1")
        .key_schema(KeySchemaElement::builder()
            .attribute_name("pokemon_type").key_type(KeyType::Hash).build()?)
        .key_schema(KeySchemaElement::builder()
            .attribute_name("createdAt").key_type(KeyType::Range).build()?)
        .projection(Projection::builder().projection_type(ProjectionType::All).build())
        .build()?;
    client.create_table().table_name(TABLE)
        .billing_mode(BillingMode::PayPerRequest)
        .attribute_definitions(AttributeDefinition::builder()
            .attribute_name("name").attribute_type(ScalarAttributeType::S).build()?)
        .attribute_definitions(AttributeDefinition::builder()
            .attribute_name("createdAt").attribute_type(ScalarAttributeType::N).build()?)
        .attribute_definitions(AttributeDefinition::builder()
            .attribute_name("pokemon_type").attribute_type(ScalarAttributeType::S).build()?)
        .key_schema(KeySchemaElement::builder()
            .attribute_name("name").key_type(KeyType::Hash).build()?)
        .key_schema(KeySchemaElement::builder()
            .attribute_name("createdAt").key_type(KeyType::Range).build()?)
        .global_secondary_indexes(index)
        .send().await?;
    client.wait_until_table_exists().table_name(TABLE)
        .wait(Duration::from_secs(120)).await?;
    Ok(())
}
pub async fn create_table(client: &Client) -> Result<(), BoxError> {
    let index = GlobalSecondaryIndex::builder()
        .index_name("GSI1")
        .key_schema(KeySchemaElement::builder()
            .attribute_name("pokemon_type").key_type(KeyType::Hash).build()?)
        .key_schema(KeySchemaElement::builder()
            .attribute_name("createdAt").key_type(KeyType::Range).build()?)
        .projection(Projection::builder().projection_type(ProjectionType::All).build())
        .build()?;
    client.create_table().table_name(TABLE)
        .billing_mode(BillingMode::PayPerRequest)
        .attribute_definitions(AttributeDefinition::builder()
            .attribute_name("name").attribute_type(ScalarAttributeType::S).build()?)
        .attribute_definitions(AttributeDefinition::builder()
            .attribute_name("createdAt").attribute_type(ScalarAttributeType::N).build()?)
        .attribute_definitions(AttributeDefinition::builder()
            .attribute_name("pokemon_type").attribute_type(ScalarAttributeType::S).build()?)
        .key_schema(KeySchemaElement::builder()
            .attribute_name("name").key_type(KeyType::Hash).build()?)
        .key_schema(KeySchemaElement::builder()
            .attribute_name("createdAt").key_type(KeyType::Range).build()?)
        .global_secondary_indexes(index)
        .send().await?;
    client.wait_until_table_exists().table_name(TABLE)
        .wait(Duration::from_secs(120)).await?;
    Ok(())
}

The waiter requires the client::Waiters trait import. Its duration is an application wait budget, not an AWS completion guarantee. A failed wait does not necessarily mean table creation failed; inspect the table state before retrying creation.

Delete table

Deleting a table also deletes its items and indexes. Wait for absence when a test needs to reuse the table name. Do not call this function during normal startup.

pub async fn delete_table(client: &Client) -> Result<(), BoxError> {
    client.delete_table().table_name(TABLE).send().await?;
    client.wait_until_table_not_exists().table_name(TABLE)
        .wait(Duration::from_secs(120)).await?;
    Ok(())
}
pub async fn delete_table(client: &Client) -> Result<(), BoxError> {
    client.delete_table().table_name(TABLE).send().await?;
    client.wait_until_table_not_exists().table_name(TABLE)
        .wait(Duration::from_secs(120)).await?;
    Ok(())
}

List tables

List names in the configured account and Region with a paginator. A single ListTables call is only one page. The paginator's stream yields a result for every page; propagate failures rather than silently returning a partial list.

pub async fn list_tables(client: &Client) -> Result<(), BoxError> {
    let mut pages = client.list_tables().into_paginator().send();
    while let Some(page) = pages.next().await {
        for name in page?.table_names() {
            println!("{name}");
        }
    }
    Ok(())
}
pub async fn list_tables(client: &Client) -> Result<(), BoxError> {
    let mut pages = client.list_tables().into_paginator().send();
    while let Some(page) = pages.next().await {
        for name in page?.table_names() {
            println!("{name}");
        }
    }
    Ok(())
}

Get all items / Scan

A Scan evaluates the table's items. Consume pages as they arrive to keep memory bounded. Here the output accessor returns an empty slice when no items were returned, so there is no need to unwrap an optional collection.

pub async fn scan_all(client: &Client) -> Result<(), BoxError> {
    let mut pages = client.scan().table_name(TABLE).into_paginator().send();
    while let Some(page) = pages.next().await {
        for item in page?.items() {
            println!("{item:?}");
        }
    }
    Ok(())
}
pub async fn scan_all(client: &Client) -> Result<(), BoxError> {
    let mut pages = client.scan().table_name(TABLE).into_paginator().send();
    while let Some(page) = pages.next().await {
        for item in page?.items() {
            println!("{item:?}");
        }
    }
    Ok(())
}

For a filter, set the expression and its aliases before converting the request into a paginator:

pub async fn scan_filtered(client: &Client) -> Result<(), BoxError> {
    let mut pages = client.scan().table_name(TABLE)
        .filter_expression("#length < :seconds")
        .expression_attribute_names("#length", "lengthInSeconds")
        .expression_attribute_values(":seconds", AttributeValue::N("100".into()))
        .into_paginator().send();
    while let Some(page) = pages.next().await {
        for item in page?.items() {
            println!("{item:?}");
        }
    }
    Ok(())
}
pub async fn scan_filtered(client: &Client) -> Result<(), BoxError> {
    let mut pages = client.scan().table_name(TABLE)
        .filter_expression("#length < :seconds")
        .expression_attribute_names("#length", "lengthInSeconds")
        .expression_attribute_values(":seconds", AttributeValue::N("100".into()))
        .into_paginator().send();
    while let Some(page) = pages.next().await {
        for item in page?.items() {
            println!("{item:?}");
        }
    }
    Ok(())
}

The optional lengthInSeconds Number is not in the basic sample struct. Items missing it will not match this filter. Filtering occurs after reads, so it reduces returned data, not the read capacity already consumed. A filtered page may be empty while the paginator still has more work.

Get item

A single-item read needs both primary-key fields. A missing item yields None, not a missing-table error. consistent_read(true) requests a strongly consistent base-table read.

pub async fn get_item(client: &Client) -> Result<Option<ItemMap>, BoxError> {
    let response = client.get_item().table_name(TABLE)
        .set_key(Some(key("bulbasaur", 20261023)))
        .consistent_read(true)
        .send().await?;
    Ok(response.item)
}

pub async fn get_typed(client: &Client) -> Result<Option<Pokemon>, BoxError> {
    match get_item(client).await? {
        Some(item) => Ok(Some(serde_dynamo::from_item(item)?)),
        None => Ok(None),
    }
}
pub async fn get_item(client: &Client) -> Result<Option<ItemMap>, BoxError> {
    let response = client.get_item().table_name(TABLE)
        .set_key(Some(key("bulbasaur", 20261023)))
        .consistent_read(true)
        .send().await?;
    Ok(response.item)
}

pub async fn get_typed(client: &Client) -> Result<Option<Pokemon>, BoxError> {
    match get_item(client).await? {
        Some(item) => Ok(Some(serde_dynamo::from_item(item)?)),
        None => Ok(None),
    }
}

The typed version uses serde_dynamo::from_item. Required struct fields must exist with compatible types; #[serde(default)] allows score to be absent. Do not convert high-precision DynamoDB decimals blindly to f64; choose a representation that preserves your application's precision.

Batch get item

BatchGet retrieves known keys, including from multiple tables, with up to 100 items and a 16 MB response. Keys must be distinct. The results are unordered and missing items are omitted.

A successful response can contain UnprocessedKeys. This loop accumulates completed reads and retries only the remaining keys. The bounded retry count and delay are example policy choices; use a job-level deadline in production.

async fn pause(attempt: u32) {
    let cap_ms = (50_u64 << attempt.min(5)).min(1000);
    tokio::time::sleep(Duration::from_millis(fastrand::u64(0..=cap_ms))).await;
}

pub async fn batch_get(client: &Client) -> Result<Vec<ItemMap>, BoxError> {
    let keys = KeysAndAttributes::builder()
        .keys(key("bulbasaur", 20261023))
        .keys(key("charmander", 20261023))
        .build()?;
    let mut pending = HashMap::from([(TABLE.to_owned(), keys)]);
    let mut items = Vec::new();
    for attempt in 0..8 {
        if attempt > 0 { pause(attempt - 1).await; }
        let output = client.batch_get_item()
            .set_request_items(Some(pending)).send().await?;
        if let Some(mut responses) = output.responses {
            items.extend(responses.remove(TABLE).unwrap_or_default());
        }
        pending = output.unprocessed_keys.unwrap_or_default();
        if pending.is_empty() { return Ok(items); }
    }
    Err("batch get incomplete; persist remaining keys for recovery".into())
}
async fn pause(attempt: u32) {
    let cap_ms = (50_u64 << attempt.min(5)).min(1000);
    tokio::time::sleep(Duration::from_millis(fastrand::u64(0..=cap_ms))).await;
}

pub async fn batch_get(client: &Client) -> Result<Vec<ItemMap>, BoxError> {
    let keys = KeysAndAttributes::builder()
        .keys(key("bulbasaur", 20261023))
        .keys(key("charmander", 20261023))
        .build()?;
    let mut pending = HashMap::from([(TABLE.to_owned(), keys)]);
    let mut items = Vec::new();
    for attempt in 0..8 {
        if attempt > 0 { pause(attempt - 1).await; }
        let output = client.batch_get_item()
            .set_request_items(Some(pending)).send().await?;
        if let Some(mut responses) = output.responses {
            items.extend(responses.remove(TABLE).unwrap_or_default());
        }
        pending = output.unprocessed_keys.unwrap_or_default();
        if pending.is_empty() { return Ok(items); }
    }
    Err("batch get incomplete; persist remaining keys for recovery".into())
}

Add another table-name entry to the request map for multiple tables, then collect each table's response separately. A durable worker should return or persist partial results and pending keys when its retry budget expires; this small example reports failure instead of claiming completion.

Put item

A put creates or replaces the entire item at its complete key. The low-level representation stores numbers in AttributeValue::N as decimal strings. These are DynamoDB Numbers, not String attributes.

pub async fn put_item(client: &Client) -> Result<(), BoxError> {
    client.put_item().table_name(TABLE)
        .item("name", AttributeValue::S("bulbasaur".into()))
        .item("createdAt", AttributeValue::N("20261023".into()))
        .item("pokemon_type", AttributeValue::S("grass".into()))
        .item("score", AttributeValue::N("0".into()))
        .send().await?;
    Ok(())
}

pub async fn put_typed(client: &Client, pokemon: &Pokemon) -> Result<(), BoxError> {
    let item: ItemMap = serde_dynamo::to_item(pokemon)?;
    client.put_item().table_name(TABLE).set_item(Some(item)).send().await?;
    Ok(())
}
pub async fn put_item(client: &Client) -> Result<(), BoxError> {
    client.put_item().table_name(TABLE)
        .item("name", AttributeValue::S("bulbasaur".into()))
        .item("createdAt", AttributeValue::N("20261023".into()))
        .item("pokemon_type", AttributeValue::S("grass".into()))
        .item("score", AttributeValue::N("0".into()))
        .send().await?;
    Ok(())
}

pub async fn put_typed(client: &Client, pokemon: &Pokemon) -> Result<(), BoxError> {
    let item: ItemMap = serde_dynamo::to_item(pokemon)?;
    client.put_item().table_name(TABLE).set_item(Some(item)).send().await?;
    Ok(())
}

The second function serializes the same schema with serde_dynamo::to_item. #[serde(rename = "createdAt")] maps the idiomatic Rust field name to the existing DynamoDB attribute. Use condition_expression("attribute_not_exists(#name)") with a #name alias if an existing item must not be overwritten.

Batch write / put item

BatchWrite supports up to 25 puts/deletes and a 16 MB request. It does not support partial updates or conditions, and the overall batch is not atomic. A successful response can contain UnprocessedItems; those operations have not yet succeeded.

pub async fn batch_write(client: &Client) -> Result<(), BoxError> {
    let pokemon = [
        Pokemon { name: "bulbasaur".into(), created_at: 20261023,
            pokemon_type: "grass".into(), score: 0 },
        Pokemon { name: "charmander".into(), created_at: 20261023,
            pokemon_type: "fire".into(), score: 0 },
    ];
    let mut writes = Vec::new();
    for item in pokemon {
        let request = PutRequest::builder()
            .set_item(Some(serde_dynamo::to_item(item)?)).build()?;
        writes.push(WriteRequest::builder().put_request(request).build());
    }
    let mut pending = HashMap::from([(TABLE.to_owned(), writes)]);
    for attempt in 0..8 {
        if attempt > 0 { pause(attempt - 1).await; }
        let output = client.batch_write_item()
            .set_request_items(Some(pending)).send().await?;
        pending = output.unprocessed_items.unwrap_or_default();
        if pending.is_empty() { return Ok(()); }
    }
    Err("batch write incomplete; persist remaining requests for recovery".into())
}
pub async fn batch_write(client: &Client) -> Result<(), BoxError> {
    let pokemon = [
        Pokemon { name: "bulbasaur".into(), created_at: 20261023,
            pokemon_type: "grass".into(), score: 0 },
        Pokemon { name: "charmander".into(), created_at: 20261023,
            pokemon_type: "fire".into(), score: 0 },
    ];
    let mut writes = Vec::new();
    for item in pokemon {
        let request = PutRequest::builder()
            .set_item(Some(serde_dynamo::to_item(item)?)).build()?;
        writes.push(WriteRequest::builder().put_request(request).build());
    }
    let mut pending = HashMap::from([(TABLE.to_owned(), writes)]);
    for attempt in 0..8 {
        if attempt > 0 { pause(attempt - 1).await; }
        let output = client.batch_write_item()
            .set_request_items(Some(pending)).send().await?;
        pending = output.unprocessed_items.unwrap_or_default();
        if pending.is_empty() { return Ok(()); }
    }
    Err("batch write incomplete; persist remaining requests for recovery".into())
}

To include a delete, construct a DeleteRequest with the complete key and use WriteRequest::builder().delete_request(...). Do not put and delete the same key in one batch. Application retries should preserve the outstanding subset so they do not overwrite newer changes with an already completed put.

Query for a set of items

A Query selects equality on the partition key and optionally a sort-key condition. This reads snapshots of bulbasaur after a numeric date. The aliases and placeholder values match exactly. Use a paginator because one call is not guaranteed to return all matches.

pub async fn query_items(client: &Client) -> Result<(), BoxError> {
    let mut pages = client.query().table_name(TABLE)
        .key_condition_expression("#name = :name AND #date > :date")
        .expression_attribute_names("#name", "name")
        .expression_attribute_names("#date", "createdAt")
        .expression_attribute_values(":name", AttributeValue::S("bulbasaur".into()))
        .expression_attribute_values(":date", AttributeValue::N("20261001".into()))
        .into_paginator().send();
    while let Some(page) = pages.next().await {
        let output = page?;
        let items: Vec<Pokemon> = serde_dynamo::from_items(output.items.unwrap_or_default())?;
        for pokemon in items { println!("{pokemon:?}"); }
    }
    Ok(())
}
pub async fn query_items(client: &Client) -> Result<(), BoxError> {
    let mut pages = client.query().table_name(TABLE)
        .key_condition_expression("#name = :name AND #date > :date")
        .expression_attribute_names("#name", "name")
        .expression_attribute_names("#date", "createdAt")
        .expression_attribute_values(":name", AttributeValue::S("bulbasaur".into()))
        .expression_attribute_values(":date", AttributeValue::N("20261001".into()))
        .into_paginator().send();
    while let Some(page) = pages.next().await {
        let output = page?;
        let items: Vec<Pokemon> = serde_dynamo::from_items(output.items.unwrap_or_default())?;
        for pokemon in items { println!("{pokemon:?}"); }
    }
    Ok(())
}

A filter can further restrict non-key attributes, but is applied after the key-matched items have been read. The Query vs. Scan guide explains when to model another key-based access pattern rather than scanning.

Query an index

Use the index name and its keys. GSI1 finds all grass-type records by date, regardless of their base-table partition keys. A GSI supports eventual consistency only; do not request strong consistency. This index projects all attributes, so typed decoding has the fields it needs.

pub async fn query_index(client: &Client) -> Result<(), BoxError> {
    let mut pages = client.query().table_name(TABLE).index_name("GSI1")
        .key_condition_expression("#type = :type AND #date >= :date")
        .expression_attribute_names("#type", "pokemon_type")
        .expression_attribute_names("#date", "createdAt")
        .expression_attribute_values(":type", AttributeValue::S("grass".into()))
        .expression_attribute_values(":date", AttributeValue::N("20261001".into()))
        .into_paginator().send();
    while let Some(page) = pages.next().await {
        for item in page?.items() { println!("{item:?}"); }
    }
    Ok(())
}
pub async fn query_index(client: &Client) -> Result<(), BoxError> {
    let mut pages = client.query().table_name(TABLE).index_name("GSI1")
        .key_condition_expression("#type = :type AND #date >= :date")
        .expression_attribute_names("#type", "pokemon_type")
        .expression_attribute_names("#date", "createdAt")
        .expression_attribute_values(":type", AttributeValue::S("grass".into()))
        .expression_attribute_values(":date", AttributeValue::N("20261001".into()))
        .into_paginator().send();
    while let Some(page) = pages.next().await {
        for item in page?.items() { println!("{item:?}"); }
    }
    Ok(())
}

For an LSI, supply its index name and its sort-key condition while keeping the table's partition key. A GSI query cannot fetch attributes that were not projected into the index.

Update item

An update changes only selected attributes and can create the item when it is absent. The following example updates a non-key nickname. It cannot rename the primary-key attribute's value in place. Request AllNew to return the resulting item.

pub async fn update_item(client: &Client) -> Result<(), BoxError> {
    let output = client.update_item().table_name(TABLE)
        .set_key(Some(key("bulbasaur", 20261023)))
        .update_expression("SET #nickname = :nickname")
        .expression_attribute_names("#nickname", "nickname")
        .expression_attribute_values(":nickname", AttributeValue::S("Leaf".into()))
        .return_values(ReturnValue::AllNew)
        .send().await?;
    println!("{:?}", output.attributes);
    Ok(())
}
pub async fn update_item(client: &Client) -> Result<(), BoxError> {
    let output = client.update_item().table_name(TABLE)
        .set_key(Some(key("bulbasaur", 20261023)))
        .update_expression("SET #nickname = :nickname")
        .expression_attribute_names("#nickname", "nickname")
        .expression_attribute_values(":nickname", AttributeValue::S("Leaf".into()))
        .return_values(ReturnValue::AllNew)
        .send().await?;
    println!("{:?}", output.attributes);
    Ok(())
}

Conditionally update item

A conditional update checks the current item atomically with the mutation. This changes the nickname only when the item is a grass type and has not been soft-deleted. It fails instead of creating a partial item when the record is absent.

pub async fn conditional_update(client: &Client) -> Result<(), BoxError> {
    client.update_item().table_name(TABLE)
        .set_key(Some(key("bulbasaur", 20261023)))
        .update_expression("SET #nickname = :nickname")
        .condition_expression("attribute_not_exists(#deleted) AND #type = :type")
        .expression_attribute_names("#nickname", "nickname")
        .expression_attribute_names("#deleted", "deletedAt")
        .expression_attribute_names("#type", "pokemon_type")
        .expression_attribute_values(":nickname", AttributeValue::S("Leaf".into()))
        .expression_attribute_values(":type", AttributeValue::S("grass".into()))
        .send().await?;
    Ok(())
}
pub async fn conditional_update(client: &Client) -> Result<(), BoxError> {
    client.update_item().table_name(TABLE)
        .set_key(Some(key("bulbasaur", 20261023)))
        .update_expression("SET #nickname = :nickname")
        .condition_expression("attribute_not_exists(#deleted) AND #type = :type")
        .expression_attribute_names("#nickname", "nickname")
        .expression_attribute_names("#deleted", "deletedAt")
        .expression_attribute_names("#type", "pokemon_type")
        .expression_attribute_values(":nickname", AttributeValue::S("Leaf".into()))
        .expression_attribute_values(":type", AttributeValue::S("grass".into()))
        .send().await?;
    Ok(())
}

Handle a condition failure as a conflict or a business-rule outcome. Repeating the identical condition without changing state usually will not help. Error handling is shown below.

Increment an item attribute

Use an atomic update instead of a read-modify-write cycle. if_not_exists initializes a missing counter to zero. An atomic increment is not idempotent: retrying an uncertain application request can increment twice, so use an idempotency design for business-critical counts.

pub async fn increment_score(client: &Client) -> Result<(), BoxError> {
    client.update_item().table_name(TABLE)
        .set_key(Some(key("bulbasaur", 20261023)))
        .update_expression("SET #score = if_not_exists(#score, :zero) + :one")
        .condition_expression("attribute_exists(#name)")
        .expression_attribute_names("#score", "score")
        .expression_attribute_names("#name", "name")
        .expression_attribute_values(":zero", AttributeValue::N("0".into()))
        .expression_attribute_values(":one", AttributeValue::N("1".into()))
        .send().await?;
    Ok(())
}
pub async fn increment_score(client: &Client) -> Result<(), BoxError> {
    client.update_item().table_name(TABLE)
        .set_key(Some(key("bulbasaur", 20261023)))
        .update_expression("SET #score = if_not_exists(#score, :zero) + :one")
        .condition_expression("attribute_exists(#name)")
        .expression_attribute_names("#score", "score")
        .expression_attribute_names("#name", "name")
        .expression_attribute_values(":zero", AttributeValue::N("0".into()))
        .expression_attribute_values(":one", AttributeValue::N("1".into()))
        .send().await?;
    Ok(())
}

Delete item

Delete by the same complete key used for GetItem. An absent item is not an error. Add a condition if deletion depends on current state; ReturnValue::AllOld can return the removed attributes.

pub async fn delete_item(client: &Client) -> Result<(), BoxError> {
    client.delete_item().table_name(TABLE)
        .set_key(Some(key("bulbasaur", 20261023)))
        .send().await?;
    Ok(())
}
pub async fn delete_item(client: &Client) -> Result<(), BoxError> {
    client.delete_item().table_name(TABLE)
        .set_key(Some(key("bulbasaur", 20261023)))
        .send().await?;
    Ok(())
}

Delete all items

DynamoDB has no table-wide delete operation. Scan the primary keys and delete each item, or group them into batch deletes with unprocessed-item retries. This deliberately sequential example bounds concurrency and projects only the two key attributes. Stop concurrent writers when the goal is an empty table; a scan is not a snapshot.

pub async fn delete_all_items(client: &Client) -> Result<(), BoxError> {
    let mut pages = client.scan().table_name(TABLE)
        .projection_expression("#name, #date")
        .expression_attribute_names("#name", "name")
        .expression_attribute_names("#date", "createdAt")
        .into_paginator().send();
    while let Some(page) = pages.next().await {
        for key in page?.items.unwrap_or_default() {
            client.delete_item().table_name(TABLE).set_key(Some(key)).send().await?;
        }
    }
    Ok(())
}
pub async fn delete_all_items(client: &Client) -> Result<(), BoxError> {
    let mut pages = client.scan().table_name(TABLE)
        .projection_expression("#name, #date")
        .expression_attribute_names("#name", "name")
        .expression_attribute_names("#date", "createdAt")
        .into_paginator().send();
    while let Some(page) = pages.next().await {
        for key in page?.items.unwrap_or_default() {
            client.delete_item().table_name(TABLE).set_key(Some(key)).send().await?;
        }
    }
    Ok(())
}

Simple transaction

Transactions make multiple writes succeed or fail together. This cart example uses the same table schema: seed a stock item at stock#bulbasaur / 0 with numeric count, then atomically decrement it and insert a distinct reservation at cart#123#bulbasaur / 20261023. The condition prevents negative stock and a duplicate reservation.

pub async fn reserve_stock(client: &Client, token: &str) -> Result<(), BoxError> {
    let put = Put::builder().table_name(TABLE)
        .set_item(Some(key("cart#123#bulbasaur", 20261023)))
        .condition_expression("attribute_not_exists(#name)")
        .expression_attribute_names("#name", "name")
        .build()?;
    let update = Update::builder().table_name(TABLE)
        .set_key(Some(key("stock#bulbasaur", 0)))
        .update_expression("SET #count = #count - :one")
        .condition_expression("#count >= :one")
        .expression_attribute_names("#count", "count")
        .expression_attribute_values(":one", AttributeValue::N("1".into()))
        .build()?;
    client.transact_write_items().client_request_token(token)
        .transact_items(TransactWriteItem::builder().put(put).build())
        .transact_items(TransactWriteItem::builder().update(update).build())
        .send().await?;
    Ok(())
}
pub async fn reserve_stock(client: &Client, token: &str) -> Result<(), BoxError> {
    let put = Put::builder().table_name(TABLE)
        .set_item(Some(key("cart#123#bulbasaur", 20261023)))
        .condition_expression("attribute_not_exists(#name)")
        .expression_attribute_names("#name", "name")
        .build()?;
    let update = Update::builder().table_name(TABLE)
        .set_key(Some(key("stock#bulbasaur", 0)))
        .update_expression("SET #count = #count - :one")
        .condition_expression("#count >= :one")
        .expression_attribute_names("#count", "count")
        .expression_attribute_values(":one", AttributeValue::N("1".into()))
        .build()?;
    client.transact_write_items().client_request_token(token)
        .transact_items(TransactWriteItem::builder().put(put).build())
        .transact_items(TransactWriteItem::builder().update(update).build())
        .send().await?;
    Ok(())
}

Give each logical reservation a unique token and reuse it only for identical retries. The idempotency window lasts 10 minutes after completion. Transactions accept up to 100 unique items and 4 MB in one account and Region, with one action per item. MRSC global tables do not support transactions. Stock and cart records do not have the fields needed for Pokemon decoding, so scan them as raw maps or define separate Rust types.

Read transaction

A read transaction fetches specified keys atomically. It can span tables in the same account and Region, and its response order matches request order. It is not a transactional table scan.

pub async fn read_transaction(client: &Client) -> Result<(), BoxError> {
    let first = Get::builder().table_name(TABLE)
        .set_key(Some(key("bulbasaur", 20261023))).build()?;
    let second = Get::builder().table_name(TABLE)
        .set_key(Some(key("charmander", 20261023))).build()?;
    let output = client.transact_get_items()
        .transact_items(TransactGetItem::builder().get(first).build())
        .transact_items(TransactGetItem::builder().get(second).build())
        .send().await?;
    for response in output.responses() { println!("{:?}", response.item()); }
    Ok(())
}
pub async fn read_transaction(client: &Client) -> Result<(), BoxError> {
    let first = Get::builder().table_name(TABLE)
        .set_key(Some(key("bulbasaur", 20261023))).build()?;
    let second = Get::builder().table_name(TABLE)
        .set_key(Some(key("charmander", 20261023))).build()?;
    let output = client.transact_get_items()
        .transact_items(TransactGetItem::builder().get(first).build())
        .transact_items(TransactGetItem::builder().get(second).build())
        .send().await?;
    for response in output.responses() { println!("{:?}", response.item()); }
    Ok(())
}

Query with sorting

Query orders results by the queried sort key. Numbers sort numerically, strings by UTF-8 bytes. Set scan_index_forward(false) for descending order, such as newest snapshots first. There is no arbitrary server-side sort field for Scan.

pub async fn query_descending(client: &Client) -> Result<(), BoxError> {
    let mut pages = client.query().table_name(TABLE)
        .key_condition_expression("#name = :name")
        .expression_attribute_names("#name", "name")
        .expression_attribute_values(":name", AttributeValue::S("bulbasaur".into()))
        .scan_index_forward(false)
        .into_paginator().send();
    while let Some(page) = pages.next().await {
        for item in page?.items() { println!("{item:?}"); }
    }
    Ok(())
}
pub async fn query_descending(client: &Client) -> Result<(), BoxError> {
    let mut pages = client.query().table_name(TABLE)
        .key_condition_expression("#name = :name")
        .expression_attribute_names("#name", "name")
        .expression_attribute_values(":name", AttributeValue::S("bulbasaur".into()))
        .scan_index_forward(false)
        .into_paginator().send();
    while let Some(page) = pages.next().await {
        for item in page?.items() { println!("{item:?}"); }
    }
    Ok(())
}

Query and Scan pagination

Both Query and Scan evaluate up to 1 MB before filtering. A limit also counts evaluated items, not matching results. The into_paginator() examples continue automatically, including after empty filtered pages.

For a user-facing page, return the last_evaluated_key from one request and pass the complete map as exclusive_start_key on the next. Preserve every returned key component, including index attributes for a GSI cursor. Pagination details explain why item count is not a reliable completion signal.

pub async fn query_page(client: &Client, cursor: Option<ItemMap>) -> Result<QueryOutput, BoxError> {
    let output = client.query().table_name(TABLE)
        .key_condition_expression("#name = :name")
        .expression_attribute_names("#name", "name")
        .expression_attribute_values(":name", AttributeValue::S("bulbasaur".into()))
        .limit(25)
        .set_exclusive_start_key(cursor)
        .send().await?;
    Ok(output)
}
pub async fn query_page(client: &Client, cursor: Option<ItemMap>) -> Result<QueryOutput, BoxError> {
    let output = client.query().table_name(TABLE)
        .key_condition_expression("#name = :name")
        .expression_attribute_names("#name", "name")
        .expression_attribute_values(":name", AttributeValue::S("bulbasaur".into()))
        .limit(25)
        .set_exclusive_start_key(cursor)
        .send().await?;
    Ok(output)
}

When implementing a manual loop, stop when the key map is absent or empty, not merely when items is absent. Bind an externally supplied cursor to the same authorized query and key conditions.

Handle SdkError and service errors

SDK operations return SdkError<OperationError>, which can represent a service response, a timeout, a connection failure or a request-construction failure. Inspect the service error before treating a failure as a condition conflict. into_service_error() consumes the wrapper; for a non-service failure it produces the operation's unhandled error, so retain the original wrapper when transport details matter.

fn insert_error(error: SdkError<PutItemError>) -> Result<bool, BoxError> {
    if error.as_service_error().is_some() {
        let service_error = error.into_service_error();
        if service_error.is_conditional_check_failed_exception() {
            return Ok(false);
        }
        return Err(service_error.into());
    }
    Err(error.into())
}

pub async fn insert_only(client: &Client, pokemon: &Pokemon) -> Result<bool, BoxError> {
    let item: ItemMap = serde_dynamo::to_item(pokemon)?;
    match client.put_item().table_name(TABLE).set_item(Some(item))
        .condition_expression("attribute_not_exists(#name)")
        .expression_attribute_names("#name", "name")
        .send().await {
        Ok(_) => Ok(true),
        Err(error) => insert_error(error),
    }
}
fn insert_error(error: SdkError<PutItemError>) -> Result<bool, BoxError> {
    if error.as_service_error().is_some() {
        let service_error = error.into_service_error();
        if service_error.is_conditional_check_failed_exception() {
            return Ok(false);
        }
        return Err(service_error.into());
    }
    Err(error.into())
}

pub async fn insert_only(client: &Client, pokemon: &Pokemon) -> Result<bool, BoxError> {
    let item: ItemMap = serde_dynamo::to_item(pokemon)?;
    match client.put_item().table_name(TABLE).set_item(Some(item))
        .condition_expression("attribute_not_exists(#name)")
        .expression_attribute_names("#name", "name")
        .send().await {
        Ok(_) => Ok(true),
        Err(error) => insert_error(error),
    }
}

Use the operation-specific error enum, such as PutItemError, rather than the retired preview SDK's ErrorKind structs. The SDK handles configured request retries, but your application must handle final errors and successful batch responses containing unprocessed work. AWS's Rust DynamoDB examples provide further operation-specific examples.