Use BatchGetItem
with an Amazon SDK or CLI
The following code examples show how to use BatchGetItem
.
- .NET
-
- Amazon SDK for .NET
-
Note
There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository
. using System; using System.Collections.Generic; using Amazon.DynamoDBv2; using Amazon.DynamoDBv2.Model; namespace LowLevelBatchGet { public class LowLevelBatchGet { private static readonly string _table1Name = "Forum"; private static readonly string _table2Name = "Thread"; public static async void RetrieveMultipleItemsBatchGet(AmazonDynamoDBClient client) { var request = new BatchGetItemRequest { RequestItems = new Dictionary<string, KeysAndAttributes>() { { _table1Name, new KeysAndAttributes { Keys = new List<Dictionary<string, AttributeValue> >() { new Dictionary<string, AttributeValue>() { { "Name", new AttributeValue { S = "Amazon DynamoDB" } } }, new Dictionary<string, AttributeValue>() { { "Name", new AttributeValue { S = "Amazon S3" } } } } }}, { _table2Name, new KeysAndAttributes { Keys = new List<Dictionary<string, AttributeValue> >() { new Dictionary<string, AttributeValue>() { { "ForumName", new AttributeValue { S = "Amazon DynamoDB" } }, { "Subject", new AttributeValue { S = "DynamoDB Thread 1" } } }, new Dictionary<string, AttributeValue>() { { "ForumName", new AttributeValue { S = "Amazon DynamoDB" } }, { "Subject", new AttributeValue { S = "DynamoDB Thread 2" } } }, new Dictionary<string, AttributeValue>() { { "ForumName", new AttributeValue { S = "Amazon S3" } }, { "Subject", new AttributeValue { S = "S3 Thread 1" } } } } } } } }; BatchGetItemResponse response; do { Console.WriteLine("Making request"); response = await client.BatchGetItemAsync(request); // Check the response. var responses = response.Responses; // Attribute list in the response. foreach (var tableResponse in responses) { var tableResults = tableResponse.Value; Console.WriteLine("Items retrieved from table {0}", tableResponse.Key); foreach (var item1 in tableResults) { PrintItem(item1); } } // Any unprocessed keys? could happen if you exceed ProvisionedThroughput or some other error. Dictionary<string, KeysAndAttributes> unprocessedKeys = response.UnprocessedKeys; foreach (var unprocessedTableKeys in unprocessedKeys) { // Print table name. Console.WriteLine(unprocessedTableKeys.Key); // Print unprocessed primary keys. foreach (var key in unprocessedTableKeys.Value.Keys) { PrintItem(key); } } request.RequestItems = unprocessedKeys; } while (response.UnprocessedKeys.Count > 0); } private static void PrintItem(Dictionary<string, AttributeValue> attributeList) { foreach (KeyValuePair<string, AttributeValue> kvp in attributeList) { string attributeName = kvp.Key; AttributeValue value = kvp.Value; Console.WriteLine( attributeName + " " + (value.S == null ? "" : "S=[" + value.S + "]") + (value.N == null ? "" : "N=[" + value.N + "]") + (value.SS == null ? "" : "SS=[" + string.Join(",", value.SS.ToArray()) + "]") + (value.NS == null ? "" : "NS=[" + string.Join(",", value.NS.ToArray()) + "]") ); } Console.WriteLine("************************************************"); } static void Main() { var client = new AmazonDynamoDBClient(); RetrieveMultipleItemsBatchGet(client); } } }
-
For API details, see BatchGetItem in Amazon SDK for .NET API Reference.
-
- Bash
-
- Amazon CLI with Bash script
-
Note
There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository
. ############################################################################# # function dynamodb_batch_get_item # # This function gets a batch of items from a DynamoDB table. # # Parameters: # -i item -- Path to json file containing the keys of the items to get. # # Returns: # The items as json output. # And: # 0 - If successful. # 1 - If it fails. ########################################################################## function dynamodb_batch_get_item() { local item response local option OPTARG # Required to use getopts command in a function. ####################################### # Function usage explanation ####################################### function usage() { echo "function dynamodb_batch_get_item" echo "Get a batch of items from a DynamoDB table." echo " -i item -- Path to json file containing the keys of the items to get." echo "" } while getopts "i:h" option; do case "${option}" in i) item="${OPTARG}" ;; h) usage return 0 ;; \?) echo "Invalid parameter" usage return 1 ;; esac done export OPTIND=1 if [[ -z "$item" ]]; then errecho "ERROR: You must provide an item with the -i parameter." usage return 1 fi response=$(aws dynamodb batch-get-item \ --request-items file://"$item") local error_code=${?} if [[ $error_code -ne 0 ]]; then aws_cli_error_log $error_code errecho "ERROR: AWS reports batch-get-item operation failed.$response" return 1 fi echo "$response" return 0 }
The utility functions used in this example.
############################################################################### # function errecho # # This function outputs everything sent to it to STDERR (standard error output). ############################################################################### function errecho() { printf "%s\n" "$*" 1>&2 } ############################################################################## # function aws_cli_error_log() # # This function is used to log the error messages from the AWS CLI. # # See https://docs.aws.amazon.com/cli/latest/topic/return-codes.html#cli-aws-help-return-codes. # # The function expects the following argument: # $1 - The error code returned by the AWS CLI. # # Returns: # 0: - Success. # ############################################################################## function aws_cli_error_log() { local err_code=$1 errecho "Error code : $err_code" if [ "$err_code" == 1 ]; then errecho " One or more S3 transfers failed." elif [ "$err_code" == 2 ]; then errecho " Command line failed to parse." elif [ "$err_code" == 130 ]; then errecho " Process received SIGINT." elif [ "$err_code" == 252 ]; then errecho " Command syntax invalid." elif [ "$err_code" == 253 ]; then errecho " The system environment or configuration was invalid." elif [ "$err_code" == 254 ]; then errecho " The service returned an error." elif [ "$err_code" == 255 ]; then errecho " 255 is a catch-all error." fi return 0 }
-
For API details, see BatchGetItem in Amazon CLI Command Reference.
-
- C++
-
- SDK for C++
-
Note
There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository
. //! Batch get items from different Amazon DynamoDB tables. /*! \sa batchGetItem() \param clientConfiguration: AWS client configuration. \return bool: Function succeeded. */ bool AwsDoc::DynamoDB::batchGetItem( const Aws::Client::ClientConfiguration &clientConfiguration) { Aws::DynamoDB::DynamoDBClient dynamoClient(clientConfiguration); Aws::DynamoDB::Model::BatchGetItemRequest request; // Table1: Forum. Aws::String table1Name = "Forum"; Aws::DynamoDB::Model::KeysAndAttributes table1KeysAndAttributes; // Table1: Projection expression. table1KeysAndAttributes.SetProjectionExpression("#n, Category, Messages, #v"); // Table1: Expression attribute names. Aws::Http::HeaderValueCollection headerValueCollection; headerValueCollection.emplace("#n", "Name"); headerValueCollection.emplace("#v", "Views"); table1KeysAndAttributes.SetExpressionAttributeNames(headerValueCollection); // Table1: Set key name, type, and value to search. std::vector<Aws::String> nameValues = {"Amazon DynamoDB", "Amazon S3"}; for (const Aws::String &name: nameValues) { Aws::Map<Aws::String, Aws::DynamoDB::Model::AttributeValue> keys; Aws::DynamoDB::Model::AttributeValue key; key.SetS(name); keys.emplace("Name", key); table1KeysAndAttributes.AddKeys(keys); } Aws::Map<Aws::String, Aws::DynamoDB::Model::KeysAndAttributes> requestItems; requestItems.emplace(table1Name, table1KeysAndAttributes); // Table2: ProductCatalog. Aws::String table2Name = "ProductCatalog"; Aws::DynamoDB::Model::KeysAndAttributes table2KeysAndAttributes; table2KeysAndAttributes.SetProjectionExpression("Title, Price, Color"); // Table2: Set key name, type, and value to search. std::vector<Aws::String> idValues = {"102", "103", "201"}; for (const Aws::String &id: idValues) { Aws::Map<Aws::String, Aws::DynamoDB::Model::AttributeValue> keys; Aws::DynamoDB::Model::AttributeValue key; key.SetN(id); keys.emplace("Id", key); table2KeysAndAttributes.AddKeys(keys); } requestItems.emplace(table2Name, table2KeysAndAttributes); bool result = true; do { // Use a do loop to handle pagination. request.SetRequestItems(requestItems); const Aws::DynamoDB::Model::BatchGetItemOutcome &outcome = dynamoClient.BatchGetItem( request); if (outcome.IsSuccess()) { for (const auto &responsesMapEntry: outcome.GetResult().GetResponses()) { Aws::String tableName = responsesMapEntry.first; const Aws::Vector<Aws::Map<Aws::String, Aws::DynamoDB::Model::AttributeValue>> &tableResults = responsesMapEntry.second; std::cout << "Retrieved " << tableResults.size() << " responses for table '" << tableName << "'.\n" << std::endl; if (tableName == "Forum") { std::cout << "Name | Category | Message | Views" << std::endl; for (const Aws::Map<Aws::String, Aws::DynamoDB::Model::AttributeValue> &item: tableResults) { std::cout << item.at("Name").GetS() << " | "; std::cout << item.at("Category").GetS() << " | "; std::cout << (item.count("Message") == 0 ? "" : item.at( "Messages").GetN()) << " | "; std::cout << (item.count("Views") == 0 ? "" : item.at( "Views").GetN()) << std::endl; } } else { std::cout << "Title | Price | Color" << std::endl; for (const Aws::Map<Aws::String, Aws::DynamoDB::Model::AttributeValue> &item: tableResults) { std::cout << item.at("Title").GetS() << " | "; std::cout << (item.count("Price") == 0 ? "" : item.at( "Price").GetN()); if (item.count("Color")) { std::cout << " | "; for (const std::shared_ptr<Aws::DynamoDB::Model::AttributeValue> &listItem: item.at( "Color").GetL()) std::cout << listItem->GetS() << " "; } std::cout << std::endl; } } std::cout << std::endl; } // If necessary, repeat request for remaining items. requestItems = outcome.GetResult().GetUnprocessedKeys(); } else { std::cerr << "Batch get item failed: " << outcome.GetError().GetMessage() << std::endl; result = false; break; } } while (!requestItems.empty()); return result; }
-
For API details, see BatchGetItem in Amazon SDK for C++ API Reference.
-
- CLI
-
- Amazon CLI
-
To retrieve multiple items from a table
The following
batch-get-items
example reads multiple items from theMusicCollection
table using a batch of threeGetItem
requests, and requests the number of read capacity units consumed by the operation. The command returns only theAlbumTitle
attribute.aws dynamodb batch-get-item \ --request-items
file://request-items.json
\ --return-consumed-capacityTOTAL
Contents of
request-items.json
:{ "MusicCollection": { "Keys": [ { "Artist": {"S": "No One You Know"}, "SongTitle": {"S": "Call Me Today"} }, { "Artist": {"S": "Acme Band"}, "SongTitle": {"S": "Happy Day"} }, { "Artist": {"S": "No One You Know"}, "SongTitle": {"S": "Scared of My Shadow"} } ], "ProjectionExpression":"AlbumTitle" } }
Output:
{ "Responses": { "MusicCollection": [ { "AlbumTitle": { "S": "Somewhat Famous" } }, { "AlbumTitle": { "S": "Blue Sky Blues" } }, { "AlbumTitle": { "S": "Louder Than Ever" } } ] }, "UnprocessedKeys": {}, "ConsumedCapacity": [ { "TableName": "MusicCollection", "CapacityUnits": 1.5 } ] }
For more information, see Batch Operations
in the Amazon DynamoDB Developer Guide. -
For API details, see BatchGetItem
in Amazon CLI Command Reference.
-
- Java
-
- SDK for Java 2.x
-
Note
There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository
. Shows how to get batch items using the service client.
import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.dynamodb.DynamoDbClient; import software.amazon.awssdk.services.dynamodb.model.AttributeValue; import software.amazon.awssdk.services.dynamodb.model.BatchGetItemRequest; import software.amazon.awssdk.services.dynamodb.model.BatchGetItemResponse; import software.amazon.awssdk.services.dynamodb.model.KeysAndAttributes; import java.util.HashMap; import java.util.List; import java.util.Map; /** * Before running this Java V2 code example, set up your development environment, including your credentials. * * For more information, see the following documentation topic: * * https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html */ public class BatchReadItems { public static void main(String[] args){ final String usage = """ Usage: <tableName> Where: tableName - The Amazon DynamoDB table (for example, Music).\s """; String tableName = "Music"; Region region = Region.US_EAST_1; DynamoDbClient dynamoDbClient = DynamoDbClient.builder() .region(region) .build(); getBatchItems(dynamoDbClient, tableName); } public static void getBatchItems(DynamoDbClient dynamoDbClient, String tableName) { // Define the primary key values for the items you want to retrieve. Map<String, AttributeValue> key1 = new HashMap<>(); key1.put("Artist", AttributeValue.builder().s("Artist1").build()); Map<String, AttributeValue> key2 = new HashMap<>(); key2.put("Artist", AttributeValue.builder().s("Artist2").build()); // Construct the batchGetItem request. Map<String, KeysAndAttributes> requestItems = new HashMap<>(); requestItems.put(tableName, KeysAndAttributes.builder() .keys(List.of(key1, key2)) .projectionExpression("Artist, SongTitle") .build()); BatchGetItemRequest batchGetItemRequest = BatchGetItemRequest.builder() .requestItems(requestItems) .build(); // Make the batchGetItem request. BatchGetItemResponse batchGetItemResponse = dynamoDbClient.batchGetItem(batchGetItemRequest); // Extract and print the retrieved items. Map<String, List<Map<String, AttributeValue>>> responses = batchGetItemResponse.responses(); if (responses.containsKey(tableName)) { List<Map<String, AttributeValue>> musicItems = responses.get(tableName); for (Map<String, AttributeValue> item : musicItems) { System.out.println("Artist: " + item.get("Artist").s() + ", SongTitle: " + item.get("SongTitle").s()); } } else { System.out.println("No items retrieved."); } } }
Shows how to get batch items using the service client and a paginator.
import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.dynamodb.DynamoDbClient; import software.amazon.awssdk.services.dynamodb.model.AttributeValue; import software.amazon.awssdk.services.dynamodb.model.BatchGetItemRequest; import software.amazon.awssdk.services.dynamodb.model.KeysAndAttributes; import java.util.Collections; import java.util.HashMap; import java.util.List; import java.util.Map; public class BatchGetItemsPaginator { public static void main(String[] args){ final String usage = """ Usage: <tableName> Where: tableName - The Amazon DynamoDB table (for example, Music).\s """; String tableName = "Music"; Region region = Region.US_EAST_1; DynamoDbClient dynamoDbClient = DynamoDbClient.builder() .region(region) .build(); getBatchItemsPaginator(dynamoDbClient, tableName) ; } public static void getBatchItemsPaginator(DynamoDbClient dynamoDbClient, String tableName) { // Define the primary key values for the items you want to retrieve. Map<String, AttributeValue> key1 = new HashMap<>(); key1.put("Artist", AttributeValue.builder().s("Artist1").build()); Map<String, AttributeValue> key2 = new HashMap<>(); key2.put("Artist", AttributeValue.builder().s("Artist2").build()); // Construct the batchGetItem request. Map<String, KeysAndAttributes> requestItems = new HashMap<>(); requestItems.put(tableName, KeysAndAttributes.builder() .keys(List.of(key1, key2)) .projectionExpression("Artist, SongTitle") .build()); BatchGetItemRequest batchGetItemRequest = BatchGetItemRequest.builder() .requestItems(requestItems) .build(); // Use batchGetItemPaginator for paginated requests. dynamoDbClient.batchGetItemPaginator(batchGetItemRequest).stream() .flatMap(response -> response.responses().getOrDefault(tableName, Collections.emptyList()).stream()) .forEach(item -> { System.out.println("Artist: " + item.get("Artist").s() + ", SongTitle: " + item.get("SongTitle").s()); }); } }
-
For API details, see BatchGetItem in Amazon SDK for Java 2.x API Reference.
-
- JavaScript
-
- SDK for JavaScript (v3)
-
Note
There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository
. This example uses the document client to simplify working with items in DynamoDB. For API details see BatchGet.
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; import { BatchGetCommand, DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb"; const client = new DynamoDBClient({}); const docClient = DynamoDBDocumentClient.from(client); export const main = async () => { const command = new BatchGetCommand({ // Each key in this object is the name of a table. This example refers // to a Books table. RequestItems: { Books: { // Each entry in Keys is an object that specifies a primary key. Keys: [ { Title: "How to AWS", }, { Title: "DynamoDB for DBAs", }, ], // Only return the "Title" and "PageCount" attributes. ProjectionExpression: "Title, PageCount", }, }, }); const response = await docClient.send(command); console.log(response.Responses.Books); return response; };
-
For more information, see Amazon SDK for JavaScript Developer Guide.
-
For API details, see BatchGetItem in Amazon SDK for JavaScript API Reference.
-
- SDK for JavaScript (v2)
-
Note
There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository
. // Load the AWS SDK for Node.js var AWS = require("aws-sdk"); // Set the region AWS.config.update({ region: "REGION" }); // Create DynamoDB service object var ddb = new AWS.DynamoDB({ apiVersion: "2012-08-10" }); var params = { RequestItems: { TABLE_NAME: { Keys: [ { KEY_NAME: { N: "KEY_VALUE_1" } }, { KEY_NAME: { N: "KEY_VALUE_2" } }, { KEY_NAME: { N: "KEY_VALUE_3" } }, ], ProjectionExpression: "KEY_NAME, ATTRIBUTE", }, }, }; ddb.batchGetItem(params, function (err, data) { if (err) { console.log("Error", err); } else { data.Responses.TABLE_NAME.forEach(function (element, index, array) { console.log(element); }); } });
-
For more information, see Amazon SDK for JavaScript Developer Guide.
-
For API details, see BatchGetItem in Amazon SDK for JavaScript API Reference.
-
- PowerShell
-
- Tools for PowerShell
-
Example 1: Gets the item with the SongTitle "Somewhere Down The Road" from the DynamoDB tables 'Music' and 'Songs'.
$key = @{ SongTitle = 'Somewhere Down The Road' Artist = 'No One You Know' } | ConvertTo-DDBItem $keysAndAttributes = New-Object Amazon.DynamoDBv2.Model.KeysAndAttributes $list = New-Object 'System.Collections.Generic.List[System.Collections.Generic.Dictionary[String, Amazon.DynamoDBv2.Model.AttributeValue]]' $list.Add($key) $keysAndAttributes.Keys = $list $requestItem = @{ 'Music' = [Amazon.DynamoDBv2.Model.KeysAndAttributes]$keysAndAttributes 'Songs' = [Amazon.DynamoDBv2.Model.KeysAndAttributes]$keysAndAttributes } $batchItems = Get-DDBBatchItem -RequestItem $requestItem $batchItems.GetEnumerator() | ForEach-Object {$PSItem.Value} | ConvertFrom-DDBItem
Output:
Name Value ---- ----- Artist No One You Know SongTitle Somewhere Down The Road AlbumTitle Somewhat Famous CriticRating 10 Genre Country Price 1.94 Artist No One You Know SongTitle Somewhere Down The Road AlbumTitle Somewhat Famous CriticRating 10 Genre Country Price 1.94
-
For API details, see BatchGetItem
in Amazon Tools for PowerShell Cmdlet Reference.
-
- Python
-
- SDK for Python (Boto3)
-
Note
There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository
. import decimal import json import logging import os import pprint import time import boto3 from botocore.exceptions import ClientError logger = logging.getLogger(__name__) dynamodb = boto3.resource("dynamodb") MAX_GET_SIZE = 100 # Amazon DynamoDB rejects a get batch larger than 100 items. def do_batch_get(batch_keys): """ Gets a batch of items from Amazon DynamoDB. Batches can contain keys from more than one table. When Amazon DynamoDB cannot process all items in a batch, a set of unprocessed keys is returned. This function uses an exponential backoff algorithm to retry getting the unprocessed keys until all are retrieved or the specified number of tries is reached. :param batch_keys: The set of keys to retrieve. A batch can contain at most 100 keys. Otherwise, Amazon DynamoDB returns an error. :return: The dictionary of retrieved items grouped under their respective table names. """ tries = 0 max_tries = 5 sleepy_time = 1 # Start with 1 second of sleep, then exponentially increase. retrieved = {key: [] for key in batch_keys} while tries < max_tries: response = dynamodb.batch_get_item(RequestItems=batch_keys) # Collect any retrieved items and retry unprocessed keys. for key in response.get("Responses", []): retrieved[key] += response["Responses"][key] unprocessed = response["UnprocessedKeys"] if len(unprocessed) > 0: batch_keys = unprocessed unprocessed_count = sum( [len(batch_key["Keys"]) for batch_key in batch_keys.values()] ) logger.info( "%s unprocessed keys returned. Sleep, then retry.", unprocessed_count ) tries += 1 if tries < max_tries: logger.info("Sleeping for %s seconds.", sleepy_time) time.sleep(sleepy_time) sleepy_time = min(sleepy_time * 2, 32) else: break return retrieved
-
For API details, see BatchGetItem in Amazon SDK for Python (Boto3) API Reference.
-
- Swift
-
- SDK for Swift
-
Note
There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository
. import AWSDynamoDB /// Gets an array of `Movie` objects describing all the movies in the /// specified list. Any movies that aren't found in the list have no /// corresponding entry in the resulting array. /// /// - Parameters /// - keys: An array of tuples, each of which specifies the title and /// release year of a movie to fetch from the table. /// /// - Returns: /// - An array of `Movie` objects describing each match found in the /// table. /// /// - Throws: /// - `MovieError.ClientUninitialized` if the DynamoDB client has not /// been initialized. /// - DynamoDB errors are thrown without change. func batchGet(keys: [(title: String, year: Int)]) async throws -> [Movie] { do { guard let client = self.ddbClient else { throw MovieError.ClientUninitialized } var movieList: [Movie] = [] var keyItems: [[Swift.String: DynamoDBClientTypes.AttributeValue]] = [] // Convert the list of keys into the form used by DynamoDB. for key in keys { let item: [Swift.String: DynamoDBClientTypes.AttributeValue] = [ "title": .s(key.title), "year": .n(String(key.year)) ] keyItems.append(item) } // Create the input record for `batchGetItem()`. The list of requested // items is in the `requestItems` property. This array contains one // entry for each table from which items are to be fetched. In this // example, there's only one table containing the movie data. // // If we wanted this program to also support searching for matches // in a table of book data, we could add a second `requestItem` // mapping the name of the book table to the list of items we want to // find in it. let input = BatchGetItemInput( requestItems: [ self.tableName: .init( consistentRead: true, keys: keyItems ) ] ) // Fetch the matching movies from the table. let output = try await client.batchGetItem(input: input) // Get the set of responses. If there aren't any, return the empty // movie list. guard let responses = output.responses else { return movieList } // Get the list of matching items for the table with the name // `tableName`. guard let responseList = responses[self.tableName] else { return movieList } // Create `Movie` items for each of the matching movies in the table // and add them to the `MovieList` array. for response in responseList { try movieList.append(Movie(withItem: response)) } return movieList } catch { print("ERROR: batchGet", dump(error)) throw error } }
-
For API details, see BatchGetItem
in Amazon SDK for Swift API reference.
-
For a complete list of Amazon SDK developer guides and code examples, see Using DynamoDB with an Amazon SDK. This topic also includes information about getting started and details about previous SDK versions.