Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 37 ยท SDKs and Local Development

AWS CLI and SDKs

Call DynamoDB from the AWS CLI, Python boto3 and the JavaScript SDK v3: low-level versus document clients, attribute type descriptors, pagination, retries and errors.

Every DynamoDB feature is an HTTPS API call, and AWS wraps it in tools for each language. In practice you meet three layers: the AWS CLI for scripts and exploration, low-level SDK clients that mirror the API exactly, and document-style clients that convert normal language values into DynamoDB's typed JSON. This lesson shows the same operations in each, explains the typed format, and covers pagination, retries and error handling.

None of the AWS calls here can run in your browser, so they are shown as read-only code. The runnable examples are stand-ins that reproduce the typed JSON conversion and the paging loop.

The typed attribute format

On the wire, every value carries a type descriptor:

Descriptor Type Example
S string {"S": "Ana"}
N number, sent as a string {"N": "42"}
B binary (base64) {"B": "AAEC"}
BOOL boolean {"BOOL": true}
NULL null {"NULL": true}
L list {"L": [{"S": "a"}, {"N": "1"}]}
M map {"M": {"city": {"S": "Lisbon"}}}
SS, NS, BS sets of strings, numbers, binary {"SS": ["a", "b"]}

Numbers travel as strings so that they keep full precision (up to 38 digits). Low-level clients make you write this JSON yourself. Document clients (boto3.resource, @aws-sdk/lib-dynamodb, the Java Enhanced Client) convert for you.

Python Marshal and unmarshal typed JSON

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that numbers come back as Decimal in Python (the real SDK does the same), not float. Passing a Python float to boto3's resource API raises an error because binary floats are inexact; use Decimal or int.

AWS CLI

The CLI uses the typed JSON. Credentials and Region come from aws configure or environment variables.

Terminal
aws dynamodb create-table --table-name Shop \
  --attribute-definitions AttributeName=PK,AttributeType=S AttributeName=SK,AttributeType=S \
  --key-schema AttributeName=PK,KeyType=HASH AttributeName=SK,KeyType=RANGE \
  --billing-mode PAY_PER_REQUEST

aws dynamodb put-item --table-name Shop \
  --item '{"PK":{"S":"CUSTOMER#c1"},"SK":{"S":"PROFILE"},"name":{"S":"Ana"}}'

aws dynamodb get-item --table-name Shop \
  --key '{"PK":{"S":"CUSTOMER#c1"},"SK":{"S":"PROFILE"}}' --consistent-read

aws dynamodb query --table-name Shop \
  --key-condition-expression "PK = :p" \
  --expression-attribute-values '{":p":{"S":"CUSTOMER#c1"}}' \
  --output json

There is also PartiQL (aws dynamodb execute-statement --statement "SELECT * FROM Shop WHERE PK='CUSTOMER#c1'"), which looks like SQL but follows the same key rules; a SELECT without a key condition becomes a scan. Add --endpoint-url http://localhost:8000 to target DynamoDB Local (next lesson).

Python with boto3

boto3.resource("dynamodb") converts types and Key/Attr helpers build expressions.

Python
import boto3
from boto3.dynamodb.conditions import Key

table = boto3.resource("dynamodb", region_name="eu-west-1").Table("Shop")

table.put_item(Item={"PK": "CUSTOMER#c1", "SK": "PROFILE", "name": "Ana", "credits": 10})

item = table.get_item(Key={"PK": "CUSTOMER#c1", "SK": "PROFILE"}).get("Item")

resp = table.query(
    KeyConditionExpression=Key("PK").eq("CUSTOMER#c1") & Key("SK").begins_with("ORDER#"),
    ScanIndexForward=False,
    Limit=20,
)
orders = resp["Items"]

table.update_item(
    Key={"PK": "CUSTOMER#c1", "SK": "PROFILE"},
    UpdateExpression="SET credits = credits + :n",
    ExpressionAttributeValues={":n": 5},
)

boto3.client("dynamodb") is the low-level client that wants the typed JSON. Use batch_writer() on a resource table to write many items with automatic batching and retries of unprocessed items.

JavaScript SDK v3

SDK v3 is modular. Use DynamoDBClient plus the document wrapper from @aws-sdk/lib-dynamodb:

JavaScript
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, GetCommand, QueryCommand, PutCommand } from "@aws-sdk/lib-dynamodb";

const client = new DynamoDBClient({ region: "eu-west-1" });
const doc = DynamoDBDocumentClient.from(client, {
  marshallOptions: { removeUndefinedValues: true },
});

await doc.send(new PutCommand({
  TableName: "Shop",
  Item: { PK: "CUSTOMER#c1", SK: "PROFILE", name: "Ana" },
}));

const { Item } = await doc.send(new GetCommand({
  TableName: "Shop",
  Key: { PK: "CUSTOMER#c1", SK: "PROFILE" },
}));

const { Items } = await doc.send(new QueryCommand({
  TableName: "Shop",
  KeyConditionExpression: "PK = :p AND begins_with(SK, :o)",
  ExpressionAttributeValues: { ":p": "CUSTOMER#c1", ":o": "ORDER#" },
}));

The Java SDK v2 has the Enhanced Client with annotated beans, .NET has the object persistence model, and Go has attributevalue.MarshalMap. They all do the same job: map objects to typed items.

Three layers

CLI Typed JSON, scripts
Low-level client Mirrors the API
Document client Normal language values

Pick the highest layer that does what you need.

1 / 2

Pagination

A Query or Scan returns at most 1 MB of data per call. If more remains, the response has LastEvaluatedKey. Pass it back as ExclusiveStartKey to get the next page. Limit caps the items evaluated per call, not total results. Never assume one call returns everything.

Python Paging loop with LastEvaluatedKey

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

In boto3 you can use a paginator on the low-level client (client.get_paginator("query").paginate(...)) to hide this loop.

Retries and errors

AWS SDKs retry throttling and transient failures with exponential backoff and jitter. Know the errors that matter:

  • ProvisionedThroughputExceededException / ThrottlingException: back off; check for hot keys (hot partitions).
  • ConditionalCheckFailedException: not an error to retry; it is a business answer (conditional writes).
  • TransactionCanceledException: inspect CancellationReasons.
  • ValidationException: your request is malformed (reserved word, empty string key, item over 400 KB).
  • ResourceNotFoundException: wrong table, Region or still creating.

Reuse the client object across requests (create it once at startup, outside a Lambda handler) so connections stay open, and keep credentials out of code: use IAM roles, environment variables or SSO profiles.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In the low-level API, how is the number 42 represented?

    Numbers use the N descriptor and travel as strings to preserve precision.
  2. 2. What does LastEvaluatedKey in a Query response mean?

    A response is capped at 1 MB. If the result is cut, LastEvaluatedKey is the cursor for the next call.
  3. 3. Which SDK layer converts normal values to typed JSON for you?

    Document-style clients marshal and unmarshal values so your code uses plain strings, numbers, lists and maps.
  4. 4. How should an application treat ConditionalCheckFailedException?

    The exception means the condition did not hold. Retrying the same request will fail again unless the data changes.

Summary

  • DynamoDB values are typed JSON (S, N, BOOL, L, M, sets...); document clients hide this.
  • The CLI, boto3 and the JavaScript SDK v3 all expose the same operations: PutItem, GetItem, Query, UpdateItem.
  • Responses are paged at 1 MB: loop on LastEvaluatedKey.
  • SDKs retry throttling automatically; treat conditional failures as answers, not faults.
  • Reuse clients and rely on IAM roles instead of keys in code.

Next: Local Development and Testing