DynamoDB GetItem with the AWS CLI

On the CLI the key is a DynamoDB JSON string, each value wrapped with its type ({"S": "..."}, {"N": "..."}), which means most of the difficulty in an aws dynamodb get-item is shell quoting rather than DynamoDB. The key itself still has to be the full primary key.

Code

aws dynamodb get-item \
  --table-name 'Music' \
  --key '{"Artist":{"S":"Arturo Sandoval"},"SongTitle":{"S":"Cubano Chant"}}' \
  --projection-expression '#proj0, #proj1, #proj2, #proj3' \
  --expression-attribute-names '{"#proj0":"Artist","#proj1":"SongTitle","#proj2":"AlbumTitle","#proj3":"Year"}'

The response prints the item in DynamoDB JSON:

{
  "Item": {
    "Artist": {"S": "Arturo Sandoval"},
    "SongTitle": {"S": "Cubano Chant"},
    "AlbumTitle": {"S": "Danzon"},
    "Year": {"N": "1994"}
  }
}

Explanation

• A miss prints nothing at all — no Item, no empty object, exit code 0. Piping that straight into jq fails on empty input, so capture the output and test the string before you parse it.
• Quoting is the real work — single-quote the JSON on bash and zsh so $ and ! stay literal. Windows cmd and PowerShell follow different rules; put the key in a file and pass --key file://key.json rather than fighting them.
• --query is not --projection-expression — --query is JMESPath, applied on your machine after the item has been read and billed. --projection-expression is the one DynamoDB sees. Neither reduces the read cost (why).
• The #proj0 aliases are required, not stylistic — Year is on AWS's reserved-word list, and naming it directly in a projection is rejected.
• Ask what it cost — add --return-consumed-capacity TOTAL and the response gains a ConsumedCapacity block. For this item, under 4 KB, that reads 0.5 capacity units, or 1.0 once you add --consistent-read (the trade-off).
• CLI v2 pages your output — by default everything goes through less on macOS and Linux (with the FRX flags) or more on Windows. In a script that is rarely what you want: pass --no-cli-pager, or set AWS_PAGER to an empty string.

Do it visually

Hand-typing that --key blob is where the time goes. The DynamoDB Expression Builder builds the DynamoDB JSON and the alias maps from a form, then hands back a ready-to-run aws dynamodb command.

DynoTable does the same thing against a real table: browse rows in a grid, then export the query behind them back out as a CLI command. Download DynoTable.

Related guides

• Query vs. Scan — when a single get-item beats a query.
• How DynamoDB partition keys work — why get-item needs the full key.
• DynamoDB ResourceNotFoundException — the usual first error here: wrong table name or region.
• "The provided key element does not match the schema" — the key you pass doesn't match the table's key schema.

References

• GetItem — Amazon DynamoDB API Reference
• get-item — AWS CLI Command Reference
• Read consistency — Amazon DynamoDB Developer Guide
• Using the pagination options in the AWS CLI (client-side pager) — AWS CLI User Guide

Last verified 2026-07-28 against the official AWS documentation linked above.