DynamoDB tutorial for beginners: build an orders table

This DynamoDB tutorial builds a customer-orders table in 30-45 minutes using DynamoDB Local, with no AWS account required. You will write, read, query, update and delete orders, add a global secondary index (GSI), and prevent accidental overwrites with a conditional write. Every database step has an AWS SDK for JavaScript v3 example and a Python boto3 equivalent, with outputs from running both against the local database.

What will you build?

A small order-management data layer with three access patterns:

The project is a set of runnable scripts, not a web application. Choose JavaScript or Python and follow that language throughout. The two versions use the same table; to try the other language, finish step 9 first, then start again at step 2 while the container is still running.

Allow about 5 minutes for the concepts, 5-10 for setup, 15-20 for operations, and 5-10 for cleanup and the AWS transition. Installing Docker for the first time can take longer.

DynamoDB concepts in five minutes

A table contains items. An item is a record composed of named attributes, such as customerId, status and totalCents. Items can have different non-key attributes; you do not declare every field when creating a table.

Our table, BeginnerOrders, has a composite primary key:

• Partition key: customerId. Orders for C001 share this value. A table query must name a specific customer.
• Sort key: orderId. A value such as 2026-10-01#1001 contains a date and an order identifier. Within one customer, results are ordered by this value.
• Primary key: both together. Two items cannot have the same customer ID and order ID. A different order for the same customer is a different item.

The date prefix makes October queries possible. DynamoDB sorts String keys by UTF-8 bytes, so consistently formatted YYYY-MM-DD dates sort chronologically. The suffix distinguishes orders on the same day; it does not sort them by time of day. The sample uses fixed dates so its output stays reproducible.

A GSI provides another way to query the same data. We will add StatusIndex, with status as its partition key and orderId as its sort key. DynamoDB maintains the index when table items change. You write to the table, not directly to the index.

Capacity mode controls billing and throughput in AWS. On-demand (PAY_PER_REQUEST) charges for read and write requests without asking you to provision capacity. Provisioned mode reserves read and write capacity units, which you manage directly or with auto scaling. This tutorial uses on-demand; compare the capacity modes before choosing for a sustained workload. DynamoDB Local does not charge for requests or reproduce production capacity behavior.

These are DynamoDB's core components. The diagram shows our records after step 6, when the first order has shipped, and the index we create in step 7.

1. Start DynamoDB Local and connect

You need Docker running and either Node.js 22 or later with npm, or Python 3.10 or later with pip. AWS CLI v2 is optional, for the alternative table-creation command. The terminal commands below use Bash or Zsh; on Windows, use WSL with Docker integration.

Start a disposable database on port 8000:

docker run -d --rm --name dynamodb-local -p 8000:8000 \
  amazon/dynamodb-local:latest \
  -jar DynamoDBLocal.jar -inMemory -sharedDb -disableTelemetry
docker run -d --rm --name dynamodb-local -p 8000:8000 \
  amazon/dynamodb-local:latest \
  -jar DynamoDBLocal.jar -inMemory -sharedDb -disableTelemetry

Docker prints a container ID, which differs each time. 8000:8000 connects port 8000 on your computer to port 8000 inside the container. -inMemory discards the data when the container stops. -sharedDb lets both languages see the same database. For a persistent setup, use the DynamoDB Local setup guide.

Create a working directory:

mkdir dynamodb-beginner
cd dynamodb-beginner
mkdir dynamodb-beginner
cd dynamodb-beginner

Save each code block in the filename shown in its first comment, in this directory. Run scripts from this directory too. Each step's JavaScript and Python versions are alternatives, not commands to run one after the other.

JavaScript: install SDK v3 and connect

npm init -y
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
npm init -y
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb

// client.mjs
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb"

export const TABLE = "BeginnerOrders"
export const raw = new DynamoDBClient({
  endpoint: "http://localhost:8000",
  region: "us-east-1",
  credentials: { accessKeyId: "fake", secretAccessKey: "fake" },
})
export const db = DynamoDBDocumentClient.from(raw)
// client.mjs
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb"

export const TABLE = "BeginnerOrders"
export const raw = new DynamoDBClient({
  endpoint: "http://localhost:8000",
  region: "us-east-1",
  credentials: { accessKeyId: "fake", secretAccessKey: "fake" },
})
export const db = DynamoDBDocumentClient.from(raw)

// 01-connect.mjs
import { ListTablesCommand } from "@aws-sdk/client-dynamodb"
import { raw } from "./client.mjs"

const result = await raw.send(new ListTablesCommand({}))
console.log(`Tables: ${result.TableNames.length}`)
// 01-connect.mjs
import { ListTablesCommand } from "@aws-sdk/client-dynamodb"
import { raw } from "./client.mjs"

const result = await raw.send(new ListTablesCommand({}))
console.log(`Tables: ${result.TableNames.length}`)

Run node 01-connect.mjs. The .mjs extension enables ES modules and top-level await. The document client accepts normal JavaScript values for item operations; raw handles table administration.

Python: install boto3 and connect

python3 -m venv .venv
source .venv/bin/activate
python -m pip install boto3
python3 -m venv .venv
source .venv/bin/activate
python -m pip install boto3

# client.py
import boto3

TABLE = "BeginnerOrders"
ddb = boto3.resource(
    "dynamodb",
    endpoint_url="http://localhost:8000",
    region_name="us-east-1",
    aws_access_key_id="fake",
    aws_secret_access_key="fake",
)
raw = ddb.meta.client
table = ddb.Table(TABLE)
# client.py
import boto3

TABLE = "BeginnerOrders"
ddb = boto3.resource(
    "dynamodb",
    endpoint_url="http://localhost:8000",
    region_name="us-east-1",
    aws_access_key_id="fake",
    aws_secret_access_key="fake",
)
raw = ddb.meta.client
table = ddb.Table(TABLE)

# 01-connect.py
from client import raw

result = raw.list_tables()
print(f"Tables: {len(result['TableNames'])}")
# 01-connect.py
from client import raw

result = raw.list_tables()
print(f"Tables: {len(result['TableNames'])}")

Run python 01-connect.py. Keep the virtual environment active for subsequent Python commands. The boto3 Table resource accepts Python dictionaries for item operations.

Output from either language on a fresh container:

Tables: 0
Tables: 0

The dummy credentials are intentional. The local database needs a signed SDK request but does not authenticate an AWS account. If the connection fails immediately after starting Docker, allow the server to finish starting and rerun the connection script. AWS documents the local setup and credentials in its installation guide.

2. Create the orders table

Use one of the three alternatives below. Each creates the same table. HASH means partition key, RANGE means sort key, and S means String. AttributeDefinitions declares only attributes used as keys, not status, totalCents or every possible item field.

JavaScript: CreateTable

// 02-create.mjs
import { CreateTableCommand, waitUntilTableExists } from "@aws-sdk/client-dynamodb"
import { raw, TABLE } from "./client.mjs"

await raw.send(new CreateTableCommand({
  TableName: TABLE,
  BillingMode: "PAY_PER_REQUEST",
  KeySchema: [
    { AttributeName: "customerId", KeyType: "HASH" },
    { AttributeName: "orderId", KeyType: "RANGE" },
  ],
  AttributeDefinitions: [
    { AttributeName: "customerId", AttributeType: "S" },
    { AttributeName: "orderId", AttributeType: "S" },
  ],
}))
await waitUntilTableExists(
  { client: raw, maxWaitTime: 120, minDelay: 1 },
  { TableName: TABLE },
)
console.log(`${TABLE}: ACTIVE`)
// 02-create.mjs
import { CreateTableCommand, waitUntilTableExists } from "@aws-sdk/client-dynamodb"
import { raw, TABLE } from "./client.mjs"

await raw.send(new CreateTableCommand({
  TableName: TABLE,
  BillingMode: "PAY_PER_REQUEST",
  KeySchema: [
    { AttributeName: "customerId", KeyType: "HASH" },
    { AttributeName: "orderId", KeyType: "RANGE" },
  ],
  AttributeDefinitions: [
    { AttributeName: "customerId", AttributeType: "S" },
    { AttributeName: "orderId", AttributeType: "S" },
  ],
}))
await waitUntilTableExists(
  { client: raw, maxWaitTime: 120, minDelay: 1 },
  { TableName: TABLE },
)
console.log(`${TABLE}: ACTIVE`)

Run node 02-create.mjs.

Python: create_table

# 02-create.py
from client import raw, TABLE

raw.create_table(
    TableName=TABLE,
    BillingMode="PAY_PER_REQUEST",
    KeySchema=[
        {"AttributeName": "customerId", "KeyType": "HASH"},
        {"AttributeName": "orderId", "KeyType": "RANGE"},
    ],
    AttributeDefinitions=[
        {"AttributeName": "customerId", "AttributeType": "S"},
        {"AttributeName": "orderId", "AttributeType": "S"},
    ],
)
raw.get_waiter("table_exists").wait(
    TableName=TABLE, WaiterConfig={"Delay": 1, "MaxAttempts": 120}
)
print(f"{TABLE}: ACTIVE")
# 02-create.py
from client import raw, TABLE

raw.create_table(
    TableName=TABLE,
    BillingMode="PAY_PER_REQUEST",
    KeySchema=[
        {"AttributeName": "customerId", "KeyType": "HASH"},
        {"AttributeName": "orderId", "KeyType": "RANGE"},
    ],
    AttributeDefinitions=[
        {"AttributeName": "customerId", "AttributeType": "S"},
        {"AttributeName": "orderId", "AttributeType": "S"},
    ],
)
raw.get_waiter("table_exists").wait(
    TableName=TABLE, WaiterConfig={"Delay": 1, "MaxAttempts": 120}
)
print(f"{TABLE}: ACTIVE")

Run python 02-create.py. Both versions wait for the table to become usable and print:

BeginnerOrders: ACTIVE
BeginnerOrders: ACTIVE

Optional CLI alternative

If you use this command, skip both SDK creation scripts. The first command prints the table name; the waiter finishes without output.

AWS_ACCESS_KEY_ID=fake AWS_SECRET_ACCESS_KEY=fake AWS_SESSION_TOKEN= \
aws dynamodb create-table \
  --endpoint-url http://localhost:8000 --region us-east-1 \
  --table-name BeginnerOrders --billing-mode PAY_PER_REQUEST \
  --attribute-definitions AttributeName=customerId,AttributeType=S AttributeName=orderId,AttributeType=S \
  --key-schema AttributeName=customerId,KeyType=HASH AttributeName=orderId,KeyType=RANGE \
  --query TableDescription.TableName --output text --no-cli-pager

AWS_ACCESS_KEY_ID=fake AWS_SECRET_ACCESS_KEY=fake AWS_SESSION_TOKEN= \
aws dynamodb wait table-exists \
  --endpoint-url http://localhost:8000 --region us-east-1 \
  --table-name BeginnerOrders
AWS_ACCESS_KEY_ID=fake AWS_SECRET_ACCESS_KEY=fake AWS_SESSION_TOKEN= \
aws dynamodb create-table \
  --endpoint-url http://localhost:8000 --region us-east-1 \
  --table-name BeginnerOrders --billing-mode PAY_PER_REQUEST \
  --attribute-definitions AttributeName=customerId,AttributeType=S AttributeName=orderId,AttributeType=S \
  --key-schema AttributeName=customerId,KeyType=HASH AttributeName=orderId,KeyType=RANGE \
  --query TableDescription.TableName --output text --no-cli-pager

AWS_ACCESS_KEY_ID=fake AWS_SECRET_ACCESS_KEY=fake AWS_SESSION_TOKEN= \
aws dynamodb wait table-exists \
  --endpoint-url http://localhost:8000 --region us-east-1 \
  --table-name BeginnerOrders

BeginnerOrders
BeginnerOrders

3. Write three orders with PutItem

Save this shared fixture as orders.json. Amounts are integer cents, so neither language needs a floating-point money value.

[
  { "customerId": "C001", "orderId": "2026-10-01#1001", "status": "OPEN", "totalCents": 2599 },
  { "customerId": "C001", "orderId": "2026-10-03#1002", "status": "OPEN", "totalCents": 4999 },
  { "customerId": "C002", "orderId": "2026-10-02#1003", "status": "OPEN", "totalCents": 1299 }
]
[
  { "customerId": "C001", "orderId": "2026-10-01#1001", "status": "OPEN", "totalCents": 2599 },
  { "customerId": "C001", "orderId": "2026-10-03#1002", "status": "OPEN", "totalCents": 4999 },
  { "customerId": "C002", "orderId": "2026-10-02#1003", "status": "OPEN", "totalCents": 1299 }
]

JavaScript: PutCommand

// 03-put.mjs
import { readFileSync } from "node:fs"
import { PutCommand } from "@aws-sdk/lib-dynamodb"
import { db, TABLE } from "./client.mjs"

const orders = JSON.parse(readFileSync("orders.json", "utf8"))
for (const order of orders) {
  await db.send(new PutCommand({ TableName: TABLE, Item: order }))
}
console.log(`Wrote ${orders.length} orders`)
// 03-put.mjs
import { readFileSync } from "node:fs"
import { PutCommand } from "@aws-sdk/lib-dynamodb"
import { db, TABLE } from "./client.mjs"

const orders = JSON.parse(readFileSync("orders.json", "utf8"))
for (const order of orders) {
  await db.send(new PutCommand({ TableName: TABLE, Item: order }))
}
console.log(`Wrote ${orders.length} orders`)

Run node 03-put.mjs.

Python: put_item

# 03-put.py
import json
from client import table

with open("orders.json", encoding="utf-8") as source:
    orders = json.load(source)
for order in orders:
    table.put_item(Item=order)
print(f"Wrote {len(orders)} orders")
# 03-put.py
import json
from client import table

with open("orders.json", encoding="utf-8") as source:
    orders = json.load(source)
for order in orders:
    table.put_item(Item=order)
print(f"Wrote {len(orders)} orders")

Run python 03-put.py. Output from either:

Wrote 3 orders
Wrote 3 orders

PutCommand calls the PutItem API. An unconditional put replaces the entire existing item with the same primary key; it does not merge fields. Rerunning this seed step also resets a shipped order to OPEN. Step 8 adds overwrite protection. See the PutItem behavior.

4. Read one order with GetItem

Provide both key attributes. ConsistentRead: true requests the latest committed version from the base table, useful when checking a write. It is not the default.

JavaScript: GetCommand

// 04-get.mjs
import { GetCommand } from "@aws-sdk/lib-dynamodb"
import { db, TABLE } from "./client.mjs"

const { Item } = await db.send(new GetCommand({
  TableName: TABLE,
  Key: { customerId: "C001", orderId: "2026-10-01#1001" },
  ConsistentRead: true,
}))
if (!Item) throw new Error("Order not found")
console.log(`${Item.customerId} | ${Item.orderId} | ${Item.status} | ${Item.totalCents}`)
// 04-get.mjs
import { GetCommand } from "@aws-sdk/lib-dynamodb"
import { db, TABLE } from "./client.mjs"

const { Item } = await db.send(new GetCommand({
  TableName: TABLE,
  Key: { customerId: "C001", orderId: "2026-10-01#1001" },
  ConsistentRead: true,
}))
if (!Item) throw new Error("Order not found")
console.log(`${Item.customerId} | ${Item.orderId} | ${Item.status} | ${Item.totalCents}`)

Run node 04-get.mjs.

Python: get_item

# 04-get.py
from client import table

result = table.get_item(
    Key={"customerId": "C001", "orderId": "2026-10-01#1001"},
    ConsistentRead=True,
)
item = result.get("Item")
if item is None:
    raise RuntimeError("Order not found")
print(f"{item['customerId']} | {item['orderId']} | {item['status']} | {item['totalCents']}")
# 04-get.py
from client import table

result = table.get_item(
    Key={"customerId": "C001", "orderId": "2026-10-01#1001"},
    ConsistentRead=True,
)
item = result.get("Item")
if item is None:
    raise RuntimeError("Order not found")
print(f"{item['customerId']} | {item['orderId']} | {item['status']} | {item['totalCents']}")

Run python 04-get.py. Output from either:

C001 | 2026-10-01#1001 | OPEN | 2599
C001 | 2026-10-01#1001 | OPEN | 2599

These scripts print selected returned fields, not the whole SDK response with request metadata. A missing item produces no Item field, which is why the scripts check it.

5. Query a customer's orders by sort-key prefix

Retrieve C001's October orders with customerId = :customer AND begins_with(orderId, :month). The partition-key equality selects the customer; the sort-key condition selects the month. A key condition cannot use arbitrary non-key attributes such as status on this table.

Set Limit to 1 deliberately to practice pagination with this tiny dataset. Each request evaluates at most one item here; keep passing LastEvaluatedKey back as ExclusiveStartKey until it disappears.

JavaScript: QueryCommand

// 05-query.mjs
import { QueryCommand } from "@aws-sdk/lib-dynamodb"
import { db, TABLE } from "./client.mjs"

let cursor
do {
  const page = await db.send(new QueryCommand({
    TableName: TABLE,
    KeyConditionExpression: "customerId = :customer AND begins_with(orderId, :month)",
    ExpressionAttributeValues: { ":customer": "C001", ":month": "2026-10" },
    ConsistentRead: true,
    Limit: 1,
    ExclusiveStartKey: cursor,
  }))
  for (const item of page.Items ?? []) {
    console.log(`${item.customerId} | ${item.orderId} | ${item.status}`)
  }
  cursor = page.LastEvaluatedKey
} while (cursor)
// 05-query.mjs
import { QueryCommand } from "@aws-sdk/lib-dynamodb"
import { db, TABLE } from "./client.mjs"

let cursor
do {
  const page = await db.send(new QueryCommand({
    TableName: TABLE,
    KeyConditionExpression: "customerId = :customer AND begins_with(orderId, :month)",
    ExpressionAttributeValues: { ":customer": "C001", ":month": "2026-10" },
    ConsistentRead: true,
    Limit: 1,
    ExclusiveStartKey: cursor,
  }))
  for (const item of page.Items ?? []) {
    console.log(`${item.customerId} | ${item.orderId} | ${item.status}`)
  }
  cursor = page.LastEvaluatedKey
} while (cursor)

Run node 05-query.mjs.

Python: query

# 05-query.py
from client import table

params = {
    "KeyConditionExpression": "customerId = :customer AND begins_with(orderId, :month)",
    "ExpressionAttributeValues": {":customer": "C001", ":month": "2026-10"},
    "ConsistentRead": True,
    "Limit": 1,
}
while True:
    page = table.query(**params)
    for item in page.get("Items", []):
        print(f"{item['customerId']} | {item['orderId']} | {item['status']}")
    if not page.get("LastEvaluatedKey"):
        break
    params["ExclusiveStartKey"] = page["LastEvaluatedKey"]
# 05-query.py
from client import table

params = {
    "KeyConditionExpression": "customerId = :customer AND begins_with(orderId, :month)",
    "ExpressionAttributeValues": {":customer": "C001", ":month": "2026-10"},
    "ConsistentRead": True,
    "Limit": 1,
}
while True:
    page = table.query(**params)
    for item in page.get("Items", []):
        print(f"{item['customerId']} | {item['orderId']} | {item['status']}")
    if not page.get("LastEvaluatedKey"):
        break
    params["ExclusiveStartKey"] = page["LastEvaluatedKey"]

Run python 05-query.py. Output from either, in ascending sort-key order:

C001 | 2026-10-01#1001 | OPEN
C001 | 2026-10-03#1002 | OPEN
C001 | 2026-10-01#1001 | OPEN
C001 | 2026-10-03#1002 | OPEN

Remove the demonstration Limit for normal use, but retain the loop. Query evaluates at most 1 MB per page even without a limit. Filters run after evaluation and can return an empty page that still has a continuation key. Filtering does not reduce the read capacity already consumed. Set ScanIndexForward to false in JavaScript or False in Python when you want descending sort-key order.

6. Update an order's status

Ship the first order with SET #s = :shipped. #s aliases the attribute name status, avoiding reserved-word conflicts, and :shipped supplies the value. The existence condition prevents UpdateItem from creating a partial new order if you mistype its key.

JavaScript: UpdateCommand

// 06-update.mjs
import { UpdateCommand } from "@aws-sdk/lib-dynamodb"
import { db, TABLE } from "./client.mjs"

const { Attributes } = await db.send(new UpdateCommand({
  TableName: TABLE,
  Key: { customerId: "C001", orderId: "2026-10-01#1001" },
  UpdateExpression: "SET #s = :shipped",
  ConditionExpression: "attribute_exists(customerId)",
  ExpressionAttributeNames: { "#s": "status" },
  ExpressionAttributeValues: { ":shipped": "SHIPPED" },
  ReturnValues: "ALL_NEW",
}))
console.log(`${Attributes.orderId} | ${Attributes.status} | ${Attributes.totalCents}`)
// 06-update.mjs
import { UpdateCommand } from "@aws-sdk/lib-dynamodb"
import { db, TABLE } from "./client.mjs"

const { Attributes } = await db.send(new UpdateCommand({
  TableName: TABLE,
  Key: { customerId: "C001", orderId: "2026-10-01#1001" },
  UpdateExpression: "SET #s = :shipped",
  ConditionExpression: "attribute_exists(customerId)",
  ExpressionAttributeNames: { "#s": "status" },
  ExpressionAttributeValues: { ":shipped": "SHIPPED" },
  ReturnValues: "ALL_NEW",
}))
console.log(`${Attributes.orderId} | ${Attributes.status} | ${Attributes.totalCents}`)

Run node 06-update.mjs.

Python: update_item

# 06-update.py
from client import table

result = table.update_item(
    Key={"customerId": "C001", "orderId": "2026-10-01#1001"},
    UpdateExpression="SET #s = :shipped",
    ConditionExpression="attribute_exists(customerId)",
    ExpressionAttributeNames={"#s": "status"},
    ExpressionAttributeValues={":shipped": "SHIPPED"},
    ReturnValues="ALL_NEW",
)
item = result["Attributes"]
print(f"{item['orderId']} | {item['status']} | {item['totalCents']}")
# 06-update.py
from client import table

result = table.update_item(
    Key={"customerId": "C001", "orderId": "2026-10-01#1001"},
    UpdateExpression="SET #s = :shipped",
    ConditionExpression="attribute_exists(customerId)",
    ExpressionAttributeNames={"#s": "status"},
    ExpressionAttributeValues={":shipped": "SHIPPED"},
    ReturnValues="ALL_NEW",
)
item = result["Attributes"]
print(f"{item['orderId']} | {item['status']} | {item['totalCents']}")

Run python 06-update.py. Output from either:

2026-10-01#1001 | SHIPPED | 2599
2026-10-01#1001 | SHIPPED | 2599

The amount remains unchanged. UpdateItem changes the specified attributes and can return their new values in the same response. See DynamoDB update expressions for counters, nested paths and removing attributes.

7. Add a GSI and query open orders

The table's key cannot answer “all open orders across customers” directly. Add StatusIndex with status as its partition key and orderId as its sort key. ProjectionType: ALL copies all item attributes into the index so the query can return the customer and amount too.

JavaScript: create the index

// 07-add-index.mjs
import { UpdateTableCommand } from "@aws-sdk/client-dynamodb"
import { raw, TABLE } from "./client.mjs"

await raw.send(new UpdateTableCommand({
  TableName: TABLE,
  AttributeDefinitions: [
    { AttributeName: "status", AttributeType: "S" },
    { AttributeName: "orderId", AttributeType: "S" },
  ],
  GlobalSecondaryIndexUpdates: [{ Create: {
    IndexName: "StatusIndex",
    KeySchema: [
      { AttributeName: "status", KeyType: "HASH" },
      { AttributeName: "orderId", KeyType: "RANGE" },
    ],
    Projection: { ProjectionType: "ALL" },
  } }],
}))
console.log("StatusIndex creation requested")
// 07-add-index.mjs
import { UpdateTableCommand } from "@aws-sdk/client-dynamodb"
import { raw, TABLE } from "./client.mjs"

await raw.send(new UpdateTableCommand({
  TableName: TABLE,
  AttributeDefinitions: [
    { AttributeName: "status", AttributeType: "S" },
    { AttributeName: "orderId", AttributeType: "S" },
  ],
  GlobalSecondaryIndexUpdates: [{ Create: {
    IndexName: "StatusIndex",
    KeySchema: [
      { AttributeName: "status", KeyType: "HASH" },
      { AttributeName: "orderId", KeyType: "RANGE" },
    ],
    Projection: { ProjectionType: "ALL" },
  } }],
}))
console.log("StatusIndex creation requested")

Run node 07-add-index.mjs once, then save and run node 07-query-index.mjs:

// 07-query-index.mjs
import { setTimeout as sleep } from "node:timers/promises"
import { DescribeTableCommand } from "@aws-sdk/client-dynamodb"
import { QueryCommand } from "@aws-sdk/lib-dynamodb"
import { raw, db, TABLE } from "./client.mjs"

let active = false
for (let attempt = 0; attempt < 120; attempt++) {
  const { Table } = await raw.send(new DescribeTableCommand({ TableName: TABLE }))
  active = Table.GlobalSecondaryIndexes?.some(
    (index) => index.IndexName === "StatusIndex" && index.IndexStatus === "ACTIVE",
  ) ?? false
  if (active) break
  await sleep(1000)
}
if (!active) throw new Error("Index not ready; rerun only 07-query-index.mjs later")
console.log("StatusIndex: ACTIVE")

let cursor
do {
  const page = await db.send(new QueryCommand({
    TableName: TABLE,
    IndexName: "StatusIndex",
    KeyConditionExpression: "#s = :open",
    ExpressionAttributeNames: { "#s": "status" },
    ExpressionAttributeValues: { ":open": "OPEN" },
    ExclusiveStartKey: cursor,
  }))
  for (const item of page.Items ?? []) {
    console.log(`${item.customerId} | ${item.orderId} | ${item.status}`)
  }
  cursor = page.LastEvaluatedKey
} while (cursor)
// 07-query-index.mjs
import { setTimeout as sleep } from "node:timers/promises"
import { DescribeTableCommand } from "@aws-sdk/client-dynamodb"
import { QueryCommand } from "@aws-sdk/lib-dynamodb"
import { raw, db, TABLE } from "./client.mjs"

let active = false
for (let attempt = 0; attempt < 120; attempt++) {
  const { Table } = await raw.send(new DescribeTableCommand({ TableName: TABLE }))
  active = Table.GlobalSecondaryIndexes?.some(
    (index) => index.IndexName === "StatusIndex" && index.IndexStatus === "ACTIVE",
  ) ?? false
  if (active) break
  await sleep(1000)
}
if (!active) throw new Error("Index not ready; rerun only 07-query-index.mjs later")
console.log("StatusIndex: ACTIVE")

let cursor
do {
  const page = await db.send(new QueryCommand({
    TableName: TABLE,
    IndexName: "StatusIndex",
    KeyConditionExpression: "#s = :open",
    ExpressionAttributeNames: { "#s": "status" },
    ExpressionAttributeValues: { ":open": "OPEN" },
    ExclusiveStartKey: cursor,
  }))
  for (const item of page.Items ?? []) {
    console.log(`${item.customerId} | ${item.orderId} | ${item.status}`)
  }
  cursor = page.LastEvaluatedKey
} while (cursor)

Python: create and query the index

# 07-add-index.py
from client import raw, TABLE

raw.update_table(
    TableName=TABLE,
    AttributeDefinitions=[
        {"AttributeName": "status", "AttributeType": "S"},
        {"AttributeName": "orderId", "AttributeType": "S"},
    ],
    GlobalSecondaryIndexUpdates=[{"Create": {
        "IndexName": "StatusIndex",
        "KeySchema": [
            {"AttributeName": "status", "KeyType": "HASH"},
            {"AttributeName": "orderId", "KeyType": "RANGE"},
        ],
        "Projection": {"ProjectionType": "ALL"},
    }}],
)
print("StatusIndex creation requested")
# 07-add-index.py
from client import raw, TABLE

raw.update_table(
    TableName=TABLE,
    AttributeDefinitions=[
        {"AttributeName": "status", "AttributeType": "S"},
        {"AttributeName": "orderId", "AttributeType": "S"},
    ],
    GlobalSecondaryIndexUpdates=[{"Create": {
        "IndexName": "StatusIndex",
        "KeySchema": [
            {"AttributeName": "status", "KeyType": "HASH"},
            {"AttributeName": "orderId", "KeyType": "RANGE"},
        ],
        "Projection": {"ProjectionType": "ALL"},
    }}],
)
print("StatusIndex creation requested")

Run python 07-add-index.py once, then save and run python 07-query-index.py:

# 07-query-index.py
import time
from client import raw, table, TABLE

for attempt in range(120):
    description = raw.describe_table(TableName=TABLE)["Table"]
    active = any(
        index["IndexName"] == "StatusIndex" and index["IndexStatus"] == "ACTIVE"
        for index in description.get("GlobalSecondaryIndexes", [])
    )
    if active:
        break
    time.sleep(1)
else:
    raise RuntimeError("Index not ready; rerun only 07-query-index.py later")
print("StatusIndex: ACTIVE")

params = {
    "IndexName": "StatusIndex",
    "KeyConditionExpression": "#s = :open",
    "ExpressionAttributeNames": {"#s": "status"},
    "ExpressionAttributeValues": {":open": "OPEN"},
}
while True:
    page = table.query(**params)
    for item in page.get("Items", []):
        print(f"{item['customerId']} | {item['orderId']} | {item['status']}")
    if not page.get("LastEvaluatedKey"):
        break
    params["ExclusiveStartKey"] = page["LastEvaluatedKey"]
# 07-query-index.py
import time
from client import raw, table, TABLE

for attempt in range(120):
    description = raw.describe_table(TableName=TABLE)["Table"]
    active = any(
        index["IndexName"] == "StatusIndex" and index["IndexStatus"] == "ACTIVE"
        for index in description.get("GlobalSecondaryIndexes", [])
    )
    if active:
        break
    time.sleep(1)
else:
    raise RuntimeError("Index not ready; rerun only 07-query-index.py later")
print("StatusIndex: ACTIVE")

params = {
    "IndexName": "StatusIndex",
    "KeyConditionExpression": "#s = :open",
    "ExpressionAttributeNames": {"#s": "status"},
    "ExpressionAttributeValues": {":open": "OPEN"},
}
while True:
    page = table.query(**params)
    for item in page.get("Items", []):
        print(f"{item['customerId']} | {item['orderId']} | {item['status']}")
    if not page.get("LastEvaluatedKey"):
        break
    params["ExclusiveStartKey"] = page["LastEvaluatedKey"]

Combined output from the two scripts, in either language:

StatusIndex creation requested
StatusIndex: ACTIVE
C002 | 2026-10-02#1003 | OPEN
C001 | 2026-10-03#1002 | OPEN
StatusIndex creation requested
StatusIndex: ACTIVE
C002 | 2026-10-02#1003 | OPEN
C001 | 2026-10-03#1002 | OPEN

The shipped order is absent; the open orders span both customers. Existing items are backfilled when the index is created. The query script checks the index's IndexStatus, not just the table's status, because an index under construction cannot yet be queried. A cloud backfill may take longer than this local waiting loop; rerun the query script later rather than requesting creation again.

GSI reads are eventually consistent: do not add ConsistentRead: true. Recently changed records can take time to appear in the index in AWS, even when the index is already active. Local results do not establish production replication timing.

This low-volume example uses only a few status values. At higher traffic, putting every open order under the same index partition-key value can concentrate writes. Review the GSI design guide before using this exact index for a busy fulfillment system. Index storage and index updates also add AWS cost.

Optional: see the table in a GUI

Connect Dynobase to DynamoDB Local using endpoint http://localhost:8000, region us-east-1 and the dummy credentials fake/fake. Open BeginnerOrders to inspect the items before cleanup. For the index query, choose StatusIndex and status = OPEN.

This existing product screenshot shows a different example Orders table; your tutorial table has customerId, orderId, status and totalCents.

8. Prevent overwrites with a conditional write

Try inserting a conflicting order with a total of one cent. attribute_not_exists(customerId) is evaluated against the item identified by the complete primary key, so it prevents replacing that order while still allowing other orders for C001. The condition and write are atomic; checking existence with a separate read would leave a race.

JavaScript: conditional PutCommand

// 08-conditional.mjs
import { PutCommand, GetCommand } from "@aws-sdk/lib-dynamodb"
import { db, TABLE } from "./client.mjs"

const key = { customerId: "C001", orderId: "2026-10-01#1001" }
try {
  await db.send(new PutCommand({
    TableName: TABLE,
    Item: { ...key, status: "OPEN", totalCents: 1 },
    ConditionExpression: "attribute_not_exists(customerId)",
  }))
  throw new Error("Expected the duplicate to be rejected")
} catch (error) {
  if (error.name !== "ConditionalCheckFailedException") throw error
  console.log("Duplicate rejected: ConditionalCheckFailedException")
}
const { Item } = await db.send(new GetCommand({
  TableName: TABLE, Key: key, ConsistentRead: true,
}))
console.log(`Preserved: ${Item.status} | ${Item.totalCents}`)
// 08-conditional.mjs
import { PutCommand, GetCommand } from "@aws-sdk/lib-dynamodb"
import { db, TABLE } from "./client.mjs"

const key = { customerId: "C001", orderId: "2026-10-01#1001" }
try {
  await db.send(new PutCommand({
    TableName: TABLE,
    Item: { ...key, status: "OPEN", totalCents: 1 },
    ConditionExpression: "attribute_not_exists(customerId)",
  }))
  throw new Error("Expected the duplicate to be rejected")
} catch (error) {
  if (error.name !== "ConditionalCheckFailedException") throw error
  console.log("Duplicate rejected: ConditionalCheckFailedException")
}
const { Item } = await db.send(new GetCommand({
  TableName: TABLE, Key: key, ConsistentRead: true,
}))
console.log(`Preserved: ${Item.status} | ${Item.totalCents}`)

Run node 08-conditional.mjs.

Python: conditional put_item

# 08-conditional.py
from botocore.exceptions import ClientError
from client import table

key = {"customerId": "C001", "orderId": "2026-10-01#1001"}
try:
    table.put_item(
        Item={**key, "status": "OPEN", "totalCents": 1},
        ConditionExpression="attribute_not_exists(customerId)",
    )
    raise RuntimeError("Expected the duplicate to be rejected")
except ClientError as error:
    if error.response["Error"]["Code"] != "ConditionalCheckFailedException":
        raise
    print("Duplicate rejected: ConditionalCheckFailedException")
item = table.get_item(Key=key, ConsistentRead=True)["Item"]
print(f"Preserved: {item['status']} | {item['totalCents']}")
# 08-conditional.py
from botocore.exceptions import ClientError
from client import table

key = {"customerId": "C001", "orderId": "2026-10-01#1001"}
try:
    table.put_item(
        Item={**key, "status": "OPEN", "totalCents": 1},
        ConditionExpression="attribute_not_exists(customerId)",
    )
    raise RuntimeError("Expected the duplicate to be rejected")
except ClientError as error:
    if error.response["Error"]["Code"] != "ConditionalCheckFailedException":
        raise
    print("Duplicate rejected: ConditionalCheckFailedException")
item = table.get_item(Key=key, ConsistentRead=True)["Item"]
print(f"Preserved: {item['status']} | {item['totalCents']}")

Run python 08-conditional.py. Output from either:

Duplicate rejected: ConditionalCheckFailedException
Preserved: SHIPPED | 2599
Duplicate rejected: ConditionalCheckFailedException
Preserved: SHIPPED | 2599

The error is the expected success case for this test. Only that error is handled; connection failures and other problems still stop the script. In an application, report a duplicate or conflict to the caller. Conditional writes and updates also support rules such as “ship only if the current status is OPEN.”

9. Delete an order and clean up

Delete C002's order, confirm it is gone with a consistent read, and delete the whole tutorial table. Deleting the table also removes its GSI and remaining items.

JavaScript: DeleteCommand and DeleteTable

// 09-cleanup.mjs
import { DeleteCommand, GetCommand } from "@aws-sdk/lib-dynamodb"
import { DeleteTableCommand, waitUntilTableNotExists } from "@aws-sdk/client-dynamodb"
import { db, raw, TABLE } from "./client.mjs"

const key = { customerId: "C002", orderId: "2026-10-02#1003" }
await db.send(new DeleteCommand({ TableName: TABLE, Key: key }))
const result = await db.send(new GetCommand({
  TableName: TABLE, Key: key, ConsistentRead: true,
}))
console.log(`Order exists: ${Boolean(result.Item)}`)
await raw.send(new DeleteTableCommand({ TableName: TABLE }))
await waitUntilTableNotExists(
  { client: raw, maxWaitTime: 120, minDelay: 1 },
  { TableName: TABLE },
)
console.log("BeginnerOrders deleted")
// 09-cleanup.mjs
import { DeleteCommand, GetCommand } from "@aws-sdk/lib-dynamodb"
import { DeleteTableCommand, waitUntilTableNotExists } from "@aws-sdk/client-dynamodb"
import { db, raw, TABLE } from "./client.mjs"

const key = { customerId: "C002", orderId: "2026-10-02#1003" }
await db.send(new DeleteCommand({ TableName: TABLE, Key: key }))
const result = await db.send(new GetCommand({
  TableName: TABLE, Key: key, ConsistentRead: true,
}))
console.log(`Order exists: ${Boolean(result.Item)}`)
await raw.send(new DeleteTableCommand({ TableName: TABLE }))
await waitUntilTableNotExists(
  { client: raw, maxWaitTime: 120, minDelay: 1 },
  { TableName: TABLE },
)
console.log("BeginnerOrders deleted")

Run node 09-cleanup.mjs.

Python: delete_item and delete_table

# 09-cleanup.py
from client import table, raw, TABLE

key = {"customerId": "C002", "orderId": "2026-10-02#1003"}
table.delete_item(Key=key)
result = table.get_item(Key=key, ConsistentRead=True)
print(f"Order exists: {str('Item' in result).lower()}")
raw.delete_table(TableName=TABLE)
raw.get_waiter("table_not_exists").wait(
    TableName=TABLE, WaiterConfig={"Delay": 1, "MaxAttempts": 120}
)
print("BeginnerOrders deleted")
# 09-cleanup.py
from client import table, raw, TABLE

key = {"customerId": "C002", "orderId": "2026-10-02#1003"}
table.delete_item(Key=key)
result = table.get_item(Key=key, ConsistentRead=True)
print(f"Order exists: {str('Item' in result).lower()}")
raw.delete_table(TableName=TABLE)
raw.get_waiter("table_not_exists").wait(
    TableName=TABLE, WaiterConfig={"Delay": 1, "MaxAttempts": 120}
)
print("BeginnerOrders deleted")

Run python 09-cleanup.py. Output from either:

Order exists: false
BeginnerOrders deleted
Order exists: false
BeginnerOrders deleted

If you want to try the other language, keep Docker running and return to step 2 after installing that language's dependencies and saving its client file. Otherwise stop the disposable container:

docker stop dynamodb-local
docker stop dynamodb-local

Output:

dynamodb-local
dynamodb-local

10. Move from DynamoDB Local to AWS

The local exercise is complete. This optional step requires an AWS account and can incur charges. The local examples above were executed against DynamoDB Local; the AWS configuration below was checked without creating cloud resources.

Choose on-demand and understand the free tier

Keep BillingMode: "PAY_PER_REQUEST" for a first cloud experiment with unpredictable traffic. The DynamoDB free tier includes 25 GB of Standard-class storage and 25 provisioned read capacity units plus 25 provisioned write capacity units, per Region and payer account. The capacity allowance does not cover on-demand read/write requests. The Standard storage allowance does apply to on-demand tables. Check AWS pricing for your Region and include index writes and storage in your estimate.

For eligible new accounts created on or after July 15, 2025, AWS offers $100 in sign-up credits and up to $100 more through qualifying activities. The Free account plan ends after six months or when its credits run out, whichever comes first; its account closes unless upgraded. These credits are separate from DynamoDB's ongoing allowances. See the current AWS account plan rules.

Configure credentials and IAM

1. Use an AWS IAM Identity Center profile for development, or an IAM role when running on AWS. Do not replace fake with a long-lived key pasted into source code.
2. Give the application's identity dynamodb:GetItem, PutItem, UpdateItem, DeleteItem and Query on the tutorial table ARN. Also allow dynamodb:Query on its index/StatusIndex ARN. The AWS table-access policy example shows the resource structure.
3. The identity running the setup and cleanup scripts additionally needs CreateTable, DescribeTable, UpdateTable and DeleteTable for the table. Only the connection-check script needs ListTables. Keep these administrative permissions separate from the application's runtime role.
4. Clear any dummy credential environment variables, select your authenticated development profile, and clear local endpoint overrides such as AWS_ENDPOINT_URL or AWS_ENDPOINT_URL_DYNAMODB. Both SDKs can then use their default credential chains. Confirm the account and Region before running a write or cleanup script.

DynamoDB Local cannot validate your cloud IAM permissions. Test those in the intended AWS development account.

JavaScript: replace client.mjs

Replace the entire local client file with this version. The SDK selects the AWS endpoint and obtains credentials from the Node.js credential provider chain.

// client.mjs (AWS replacement)
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb"

export const TABLE = "BeginnerOrders"
export const raw = new DynamoDBClient({ region: "us-east-1" })
export const db = DynamoDBDocumentClient.from(raw)
// client.mjs (AWS replacement)
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb"

export const TABLE = "BeginnerOrders"
export const raw = new DynamoDBClient({ region: "us-east-1" })
export const db = DynamoDBDocumentClient.from(raw)

Python: replace client.py

Boto3's credential chain supplies the authenticated profile or role:

# client.py (AWS replacement)
import boto3

TABLE = "BeginnerOrders"
ddb = boto3.resource("dynamodb", region_name="us-east-1")
raw = ddb.meta.client
table = ddb.Table(TABLE)
# client.py (AWS replacement)
import boto3

TABLE = "BeginnerOrders"
ddb = boto3.resource("dynamodb", region_name="us-east-1")
raw = ddb.meta.client
table = ddb.Table(TABLE)

Run steps 2-8 again in your chosen language to create the cloud table and seed the three example orders. The AWS CLI alternative would also need its local endpoint and dummy credential assignments removed; changing the SDK client file does not change CLI commands. Switching endpoints does not upload local data. For this small exercise, rerunning the fixture is the migration.

Cloud table creation and index backfill are asynchronous. If the step 2 waiter times out, check the existing table's status before continuing; do not blindly recreate it. For step 7, rerun only the query script while the index finishes. When finished experimenting, run step 9 with the AWS client to remove the cloud table and index too. Stopping Docker affects only the local database.

Common beginner mistakes

Local testing proves that these requests work against the local API. It does not prove AWS throttling, billing, IAM enforcement or propagation timing. AWS lists the differences from the managed service.

What should you learn next?

Use this as the first lab in a DynamoDB course, then extend the same project:

1. Read DynamoDB keys and data types. Add a second order on the same date without overwriting the first.
2. Compare Scan and Query. Explain why a status filter on a full-table scan is different from querying StatusIndex.
3. Work through single-table design. Add customer profile items and decide which access patterns need an index before writing code.
4. Apply the DynamoDB best practices to key distribution, item sizes and operational checks.

Keep the Node.js examples or boto3 examples nearby as a reference. For additional projects, browse more tutorials.