Search across all documentation pages
The first-table quickstart in the Core Services section covered create, put, get, and a simple query. This page is the next layer: the everyday modeling vocabulary you need before single-table design and transactions make sense.
Each example is small and uses the document interface, so you work with plain objects rather than DynamoDB's typed attribute values. Read them in order - keys, then range queries, then indexes, then updates and batches.
pip install boto3 (boto3 1.43.x, Python 3.10+). TypeScript: npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb (Node.js 18+).aws configure, environment variables, or an IAM role - the SDK resolves them automatically.AWS_REGION or passed per client. These examples assume us-east-1 and a table named AppData.# --- Python (boto3) ---
import boto3
from boto3.dynamodb.conditions import Key, Attr
table = boto3.resource("dynamodb", region_name="us-east-1").Table("AppData")// --- TypeScript (AWS SDK v3) ---
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
const doc = DynamoDBDocumentClient.from(new DynamoDBClient({ region: "us-east-1" }));Model a table whose partition key groups items and whose sort key both orders and identifies them.
# --- Python (boto3) ---
# PK groups by customer; SK is an order id prefixed so items sort together.
table.put_item(Item={"pk": "CUSTOMER#c-1", "sk": "ORDER#2026-01-05#o-100", "total": 42})
table.put_item(Item={"pk": "CUSTOMER#c-1", "sk": "ORDER#2026-02-11#o-101", "total": 17})// --- TypeScript (AWS SDK v3) ---
import { PutCommand } from "@aws-sdk/lib-dynamodb";
// PK groups by customer; SK is an order id prefixed so items sort together.
await doc.send(new PutCommand({ TableName: "AppData", Item: { pk: "CUSTOMER#c-1", sk: "ORDER#2026-01-05#o-100", total: 42 } }));
await doc.send(new PutCommand({ TableName: "AppData", Item: { pk: "CUSTOMER#c-1", sk: "ORDER#2026-02-11#o-101", total: 17 } }));pk) decides physical placement; all of one customer's items share a partition.sk) both orders items and makes each unique within the partition.ORDER# and a date let you query subsets by sort-key condition later.pk/sk) leave room to store more entity types in the same table.Related: Single-Table Design Patterns.
Read a subset of one partition using begins_with, between, and comparisons - all evaluated on the key, so they are efficient.
# --- Python (boto3) ---
from boto3.dynamodb.conditions import Key
# All of this customer's orders (sort key begins with ORDER#).
resp = table.query(
KeyConditionExpression=Key("pk").eq("CUSTOMER#c-1") & Key("sk").begins_with("ORDER#")
)
print([i["sk"] for i in resp["Items"]])// --- TypeScript (AWS SDK v3) ---
import { QueryCommand } from "@aws-sdk/lib-dynamodb";
// All of this customer's orders (sort key begins with ORDER#).
const resp = await doc.send(new QueryCommand({
TableName: "AppData",
KeyConditionExpression: "pk = :p AND begins_with(sk, :prefix)",
ExpressionAttributeValues: { ":p": "CUSTOMER#c-1", ":prefix": "ORDER#" },
}));
console.log((resp.Items ?? []).map((i) => i.sk));pk equality is required.begins_with, between, <, and > all apply to the sort key in a KeyConditionExpression.ScanIndexForward=False.Related: Queries, Scans & Filter Expressions.
Change one field without reading and rewriting the whole item, using an UpdateExpression.
# --- Python (boto3) ---
resp = table.update_item(
Key={"pk": "CUSTOMER#c-1", "sk": "ORDER#2026-01-05#o-100"},
UpdateExpression="SET #s = :status, total = total + :delta",
ExpressionAttributeNames={"#s": "status"},
ExpressionAttributeValues={":status": "SHIPPED", ":delta": 5},
ReturnValues="ALL_NEW",
)
print(resp["Attributes"])// --- TypeScript (AWS SDK v3) ---
import { UpdateCommand } from "@aws-sdk/lib-dynamodb";
const resp = await doc.send(new UpdateCommand({
TableName: "AppData",
Key: { pk: "CUSTOMER#c-1", sk: "ORDER#2026-01-05#o-100" },
UpdateExpression: "SET #s = :status, total = total + :delta",
ExpressionAttributeNames: { "#s": "status" },
ExpressionAttributeValues: { ":status": "SHIPPED", ":delta": 5 },
ReturnValues: "ALL_NEW",
}));
console.log(resp.Attributes);SET assigns; DynamoDB also supports arithmetic like total + :delta atomically.#s is an expression-attribute name placeholder because status is a reserved word.ReturnValues="ALL_NEW" returns the item as it looks after the update.UpdateItem creates the item if the key does not exist, unless you add a condition.Related: Transactions & Conditional Writes.
A GSI projects a new partition/sort key over the same items, enabling a query the base key cannot serve. Define it at create time (or add later with UpdateTable).
# --- Python (boto3) ---
ddb = boto3.client("dynamodb", region_name="us-east-1")
ddb.create_table(
TableName="AppData",
KeySchema=[{"AttributeName": "pk", "KeyType": "HASH"}, {"AttributeName": "sk", "KeyType": "RANGE"}],
AttributeDefinitions=[
{"AttributeName": "pk", "AttributeType": "S"},
{"AttributeName": "sk", "AttributeType": "S"},
{"AttributeName": "status", "AttributeType": "S"},
],
GlobalSecondaryIndexes=[{
"IndexName": "byStatus",
"KeySchema": [{"AttributeName": "status", "KeyType": "HASH"}, {"AttributeName": "sk", "KeyType": "RANGE"}],
"Projection": {"ProjectionType": "ALL"},
}],
BillingMode="PAY_PER_REQUEST",
)// --- TypeScript (AWS SDK v3) ---
import { DynamoDBClient, CreateTableCommand } from "@aws-sdk/client-dynamodb";
const base = new DynamoDBClient({ region: "us-east-1" });
await base.send(new CreateTableCommand({
TableName: "AppData",
KeySchema: [{ AttributeName: "pk", KeyType: "HASH" }, { AttributeName: "sk", KeyType: "RANGE" }],
AttributeDefinitions: [
{ AttributeName: "pk", AttributeType: "S" },
{ AttributeName: "sk", AttributeType: "S" },
{ AttributeName: "status", AttributeType: "S" },
],
GlobalSecondaryIndexes: [{
IndexName: "byStatus",
KeySchema: [{ AttributeName: "status", KeyType: "HASH" }, { AttributeName: "sk", KeyType: "RANGE" }],
Projection: { ProjectionType: "ALL" },
}],
BillingMode: "PAY_PER_REQUEST",
}));IndexName).Projection controls which attributes are copied into the index; ALL copies everything.Send many puts (and deletes) in batches of up to 25, instead of one request per item.
# --- Python (boto3) ---
# batch_writer buffers and flushes in 25-item batches, retrying unprocessed items.
with table.batch_writer() as batch:
for n in range(100):
batch.put_item(Item={"pk": "CUSTOMER#c-1", "sk": f"EVENT#{n:04d}", "kind": "click"})// --- TypeScript (AWS SDK v3) ---
import { BatchWriteCommand } from "@aws-sdk/lib-dynamodb";
// BatchWriteItem accepts up to 25 requests; chunk larger loads yourself.
const items = Array.from({ length: 25 }, (_, n) => ({
PutRequest: { Item: { pk: "CUSTOMER#c-1", sk: `EVENT#${String(n).padStart(4, "0")}`, kind: "click" } },
}));
await doc.send(new BatchWriteCommand({ RequestItems: { AppData: items } }));BatchWriteItem caps at 25 items per request; the boto3 batch_writer chunks and retries for you.UpdateItem - they are put/delete only.UnprocessedItems; resend them (boto3 handles this automatically).Related: On-Demand vs Provisioned Capacity.
A Global Secondary Index (GSI) has a completely different partition key from the base table and can be added or removed at any time. It is eventually consistent and provisioned separately. Use it for most "second access pattern" needs.
A Local Secondary Index (LSI) shares the base table's partition key but adds a different sort key. It supports strongly consistent reads but must be created with the table and can never be added later, and it counts against a 10 GB per-partition limit. Reach for an LSI only when you need a strongly consistent alternate sort on the same partition.
Reads default to eventually consistent. Pass ConsistentRead=True on a GetItem or Query against the base table or an LSI when you must see the latest write. GSIs cannot be read strongly consistently at all.
FilterExpression runs after the read and still bills for scanned items. Fix: narrow with a KeyConditionExpression or an index instead.status, name, size, and many others are reserved. Fix: use an ExpressionAttributeNames placeholder like #s.BatchWriteItem rejects more than 25 requests. Fix: chunk into 25s (boto3's batch_writer does this for you).UpdateItem inserts a new item if the key is absent. Fix: add attribute_exists(pk) when you require the item to pre-exist.Whenever you need to store multiple related items under one partition key and query ranges of them - "all orders for a customer," "events since a date." The sort key both orders and uniquely identifies items within the partition.
A GSI has a different partition key, is eventually consistent, and can be added anytime. An LSI shares the table's partition key with a different sort key, supports strong consistency, but must be created with the table and cannot be added later.
No. It applies only the changes in your UpdateExpression - SET, REMOVE, ADD, DELETE on specific attributes - leaving everything else untouched. It is the right tool for changing one field.
Many attribute names (status, name, size, ttl) are DynamoDB reserved words and cannot appear directly in an expression. A #name placeholder mapped through ExpressionAttributeNames sidesteps the reservation.
BatchWriteItem accepts up to 25 put or delete requests per call. The boto3 batch_writer context manager chunks larger loads into 25-item batches and retries unprocessed items automatically.
No. GSIs are always eventually consistent because DynamoDB replicates writes into them asynchronously. If you need a strongly consistent alternate sort, use an LSI, which must be defined at table creation.
An index that only contains items which have its key attributes. If you write the index's partition-key attribute onto just some items, the index holds only those - a handy way to query "items in state X" cheaply.
It reduces network round trips and per-request overhead, but each item still consumes its own read or write capacity. Batching is about efficiency and latency, not a capacity discount.
Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).
Reviewed by Chris St. John·Last updated Jul 23, 2026