DynamoDB GetItem in Node.js (AWS SDK v3)

GetItem reads a single item by its full primary key. In AWS SDK v3 you send a GetItemCommand on a DynamoDBClient; the key values use the low-level attribute-value format ({ S: "..." }, { N: "..." }).

Code

import {DynamoDBClient, GetItemCommand} from '@aws-sdk/client-dynamodb';

const client = new DynamoDBClient({region: 'us-east-1'});

const command = new GetItemCommand({
  TableName: 'Music',
  Key: {
    Artist: {S: 'Arturo Sandoval'},
    SongTitle: {S: 'Cubano Chant'}
  },
  ProjectionExpression: '#proj0, #proj1, #proj2, #proj3',
  ExpressionAttributeNames: {
    '#proj0': 'Artist',
    '#proj1': 'SongTitle',
    '#proj2': 'AlbumTitle',
    '#proj3': 'Year'
  }
});

const response = await client.send(command);

if (!response.Item) {
  console.log('Item not found');
} else {
  console.log(response.Item);
}

To get plain JavaScript values instead of { S: "..." } wrappers, pass response.Item through unmarshall from @aws-sdk/util-dynamodb, or use the DynamoDBDocumentClient from @aws-sdk/lib-dynamodb.

Explanation

• TableName — the table to read from.
• Key — must include every primary-key attribute: the partition key alone for a simple key, or partition and sort key for a composite key. GetItem will not accept a partial key.
• ProjectionExpression — optional; limits which attributes come back (saves bandwidth, not read cost). Every projected attribute is aliased (#proj0…#proj3) via ExpressionAttributeNames, which keeps reserved words like Year safe.
• response.Item — undefined when no item matches; always check before using it.
• By default reads are eventually consistent. Add ConsistentRead: true for a strongly-consistent read (costs 2× the RCU, base table only).

Do it visually

Building the projection or a conditional read by hand? Use the free DynamoDB Expression Builder to assemble the expression and copy the exact ProjectionExpression / ExpressionAttributeNames values.

To browse tables and run GetItem in a GUI — key form, results grid, one-click copy of the generated code — download DynoTable.

Related guides

• Query vs. Scan — when a single GetItem beats a Query.
• How DynamoDB partition keys work — why GetItem 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
• GetItemCommand — AWS SDK for JavaScript v3 Reference
• Read consistency — Amazon DynamoDB Developer Guide
• Capacity unit consumption — Amazon DynamoDB Developer Guide

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