How to Use GetItem in DynamoDB: Syntax and Example

Use the GetItem operation in DynamoDB to retrieve a single item by specifying its primary key in the request. You provide the table name and key attributes, and DynamoDB returns the matching item if it exists.

Syntax

The GetItem operation requires the TableName and the Key of the item you want to retrieve. The Key is a map of attribute names to their values that uniquely identify the item.

You can also specify ProjectionExpression to get only certain attributes.

plaintext

GetItem({
  TableName: 'YourTableName',
  Key: {
    'PrimaryKeyAttributeName': { S: 'PrimaryKeyValue' }
  },
  ProjectionExpression: 'Attribute1, Attribute2' // optional
})

Example

This example shows how to use the AWS SDK for JavaScript (v3) to get an item from a DynamoDB table named Users by its primary key UserId.

javascript

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

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

async function getUser(userId) {
  const params = {
    TableName: "Users",
    Key: {
      "UserId": { S: userId }
    }
  };

  try {
    const command = new GetItemCommand(params);
    const data = await client.send(command);
    if (data.Item) {
      console.log("User found:", data.Item);
    } else {
      console.log("User not found.");
    }
  } catch (err) {
    console.error("Error", err);
  }
}

getUser("12345");

Output

User found: { UserId: { S: '12345' }, Name: { S: 'Alice' }, Age: { N: '30' } }

Common Pitfalls

• Not specifying the full primary key (partition key and sort key if applicable) will cause GetItem to fail or return no data.
• Using incorrect attribute types in the Key (e.g., string vs number) will cause no match.
• Expecting GetItem to return multiple items; it only returns one item or none.
• Not handling the case when the item does not exist (result is empty).

javascript

/* Wrong: Missing sort key if table has one */
const paramsWrong = {
  TableName: "Orders",
  Key: {
    "OrderId": { S: "123" }
    // Missing SortKey attribute here
  }
};

/* Correct: Include both partition and sort key */
const paramsRight = {
  TableName: "Orders",
  Key: {
    "OrderId": { S: "123" },
    "OrderDate": { S: "2023-06-01" }
  }
};

Quick Reference

Parameter	Description
TableName	Name of the DynamoDB table
Key	Map of primary key attribute(s) and their values to identify the item
ProjectionExpression	Optional list of attributes to retrieve
ConsistentRead	Optional boolean to request strongly consistent read (default false)

Key Takeaways

GetItem retrieves a single item by its full primary key from a DynamoDB table.

Always provide the correct attribute types and all key attributes in the Key parameter.

GetItem returns null if the item does not exist; handle this case in your code.

Use ProjectionExpression to fetch only needed attributes and reduce data transfer.

GetItem is simple and fast for fetching one item, but not for multiple items.