Developer Preview — This documentation covers the AWS SDK for Python, which is in Developer Preview and intended for evaluation and testing only. Do not use it for production workloads. For production applications, use the AWS SDK for Python (Boto3). To understand the differences between the two SDKs, see Choosing the right AWS SDK for Python.

Work with DynamoDB items

In DynamoDB, an item is a collection of attributes, each of which has a name and a value. An attribute value can be a scalar, set, or document type. For more information, see Naming Rules and Data Types in the Amazon DynamoDB Developer Guide.

The low-level client represents an item as a map of attribute names to typed AttributeValue models, such as AttributeValueS for a string and AttributeValueN for a number. Numbers are strings to preserve decimal precision. Response attributes use the same models, so check the concrete model before reading its value, as shown in Get an item.

The examples on this page use the composite-key table created in Create a table with a composite primary key. The client that is used in the following examples can be created from the snippet in Set up the examples.

Put an item

For request and response details, see the put_item() API reference.

Pass a complete map of typed attributes to put_item. A put replaces an existing item with the same primary key unless you add a condition.

Imports

from aws_sdk_dynamodb.client import AsyncDynamoDBClient
from aws_sdk_dynamodb.models import (
    AttributeValueN,
    AttributeValueS,
    PutItemInput,
)

Code

async def put_item(client: AsyncDynamoDBClient, table_name: str) -> None:
    """Put a book item, replacing any item with the same primary key."""
    await client.put_item(
        input=PutItemInput(
            table_name=table_name,
            item={
                "author": AttributeValueS(value="Ada Lovelace"),
                "title": AttributeValueS(value="Notes on the Analytical Engine"),
                "year": AttributeValueN(value="1843"),
                "copies": AttributeValueN(value="0"),
            },
        )
    )

Get an item

For request and response details, see the get_item() API reference.

Supply every primary-key attribute to get_item. This example requests a strongly consistent read and returns the optional item.

Imports

from aws_sdk_dynamodb.client import AsyncDynamoDBClient
from aws_sdk_dynamodb.models import AttributeValue, AttributeValueS, GetItemInput

Code

async def get_item(
    client: AsyncDynamoDBClient, table_name: str
) -> dict[str, AttributeValue] | None:
    """Get a book by its complete composite primary key."""
    response = await client.get_item(
        input=GetItemInput(
            table_name=table_name,
            key={
                "author": AttributeValueS(value="Ada Lovelace"),
                "title": AttributeValueS(value="Notes on the Analytical Engine"),
            },
            consistent_read=True,
        )
    )
    return response.item

Each returned attribute is a typed AttributeValue union. Narrow it to its concrete model before reading its value.

if item:
    title = item.get("title")
    if isinstance(title, AttributeValueS):
        print(title.value)

Update an item

For request and response details, see the update_item() API reference.

Use an update expression to change selected attributes. Expression-name placeholders safely represent attribute names, and ALL_NEW returns the item after the update.

Imports

from aws_sdk_dynamodb.client import AsyncDynamoDBClient
from aws_sdk_dynamodb.models import (
    AttributeValue,
    AttributeValueN,
    AttributeValueS,
    UpdateItemInput,
)

Code

async def update_item(
    client: AsyncDynamoDBClient, table_name: str
) -> dict[str, AttributeValue]:
    """Increment a book's copy count and return the updated item."""
    response = await client.update_item(
        input=UpdateItemInput(
            table_name=table_name,
            key={
                "author": AttributeValueS(value="Ada Lovelace"),
                "title": AttributeValueS(value="Notes on the Analytical Engine"),
            },
            update_expression="SET #copies = #copies + :increment",
            expression_attribute_names={"#copies": "copies"},
            expression_attribute_values={
                ":increment": AttributeValueN(value="1")
            },
            return_values="ALL_NEW",
        )
    )
    return response.attributes or {}

Delete an item

For request and response details, see the delete_item() API reference.

Delete one item by supplying its complete primary key.

Imports

from aws_sdk_dynamodb.client import AsyncDynamoDBClient
from aws_sdk_dynamodb.models import AttributeValueS, DeleteItemInput

Code

async def delete_item(client: AsyncDynamoDBClient, table_name: str) -> None:
    """Delete a book by its complete composite primary key."""
    await client.delete_item(
        input=DeleteItemInput(
            table_name=table_name,
            key={
                "author": AttributeValueS(value="Ada Lovelace"),
                "title": AttributeValueS(value="Notes on the Analytical Engine"),
            },
        )
    )

Protect a write with a condition expression

For request and response details, see the put_item() API reference.

A condition expression is evaluated before DynamoDB changes the item. This conditional put prevents replacement of an item that already has the same key. A false condition raises the modeled ConditionalCheckFailedException and does not change the item.

Imports

from aws_sdk_dynamodb.client import AsyncDynamoDBClient
from aws_sdk_dynamodb.models import (
    AttributeValueS,
    ConditionalCheckFailedException,
    PutItemInput,
)

Code

async def put_item_conditionally(
    client: AsyncDynamoDBClient, table_name: str
) -> bool:
    """Put a book only when its partition key does not already exist."""
    try:
        await client.put_item(
            input=PutItemInput(
                table_name=table_name,
                item={
                    "author": AttributeValueS(value="Ada Lovelace"),
                    "title": AttributeValueS(
                        value="Notes on the Analytical Engine"
                    ),
                },
                condition_expression="attribute_not_exists(#author)",
                expression_attribute_names={"#author": "author"},
            )
        )
        return True
    except ConditionalCheckFailedException:
        return False

More information