Learn the basics of DynamoDB with an Amazon SDK
The following code examples show how to:
Create a table that can hold movie data.
Put, get, and update a single movie in the table.
Write movie data to the table from a sample JSON file.
Query for movies that were released in a given year.
Scan for movies that were released in a range of years.
Delete a movie from the table, then delete the table.
- .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
. // This example application performs the following basic Amazon DynamoDB // functions: // // CreateTableAsync // PutItemAsync // UpdateItemAsync // BatchWriteItemAsync // GetItemAsync // DeleteItemAsync // Query // Scan // DeleteItemAsync // using Amazon.DynamoDBv2; using DynamoDB_Actions; public class DynamoDB_Basics { // Separator for the console display. private static readonly string SepBar = new string('-', 80); public static async Task Main() { var client = new AmazonDynamoDBClient(); var tableName = "movie_table"; // Relative path to moviedata.json in the local repository. var movieFileName = @"..\..\..\..\..\..\..\..\resources\sample_files\movies.json"; DisplayInstructions(); // Create a new table and wait for it to be active. Console.WriteLine($"Creating the new table: {tableName}"); var success = await DynamoDbMethods.CreateMovieTableAsync(client, tableName); if (success) { Console.WriteLine($"\nTable: {tableName} successfully created."); } else { Console.WriteLine($"\nCould not create {tableName}."); } WaitForEnter(); // Add a single new movie to the table. var newMovie = new Movie { Year = 2021, Title = "Spider-Man: No Way Home", }; success = await DynamoDbMethods.PutItemAsync(client, newMovie, tableName); if (success) { Console.WriteLine($"Added {newMovie.Title} to the table."); } else { Console.WriteLine("Could not add movie to table."); } WaitForEnter(); // Update the new movie by adding a plot and rank. var newInfo = new MovieInfo { Plot = "With Spider-Man's identity now revealed, Peter asks" + "Doctor Strange for help. When a spell goes wrong, dangerous" + "foes from other worlds start to appear, forcing Peter to" + "discover what it truly means to be Spider-Man.", Rank = 9, }; success = await DynamoDbMethods.UpdateItemAsync(client, newMovie, newInfo, tableName); if (success) { Console.WriteLine($"Successfully updated the movie: {newMovie.Title}"); } else { Console.WriteLine("Could not update the movie."); } WaitForEnter(); // Add a batch of movies to the DynamoDB table from a list of // movies in a JSON file. var itemCount = await DynamoDbMethods.BatchWriteItemsAsync(client, movieFileName); Console.WriteLine($"Added {itemCount} movies to the table."); WaitForEnter(); // Get a movie by key. (partition + sort) var lookupMovie = new Movie { Title = "Jurassic Park", Year = 1993, }; Console.WriteLine("Looking for the movie \"Jurassic Park\"."); var item = await DynamoDbMethods.GetItemAsync(client, lookupMovie, tableName); if (item.Count > 0) { DynamoDbMethods.DisplayItem(item); } else { Console.WriteLine($"Couldn't find {lookupMovie.Title}"); } WaitForEnter(); // Delete a movie. var movieToDelete = new Movie { Title = "The Town", Year = 2010, }; success = await DynamoDbMethods.DeleteItemAsync(client, tableName, movieToDelete); if (success) { Console.WriteLine($"Successfully deleted {movieToDelete.Title}."); } else { Console.WriteLine($"Could not delete {movieToDelete.Title}."); } WaitForEnter(); // Use Query to find all the movies released in 2010. int findYear = 2010; Console.WriteLine($"Movies released in {findYear}"); var queryCount = await DynamoDbMethods.QueryMoviesAsync(client, tableName, findYear); Console.WriteLine($"Found {queryCount} movies released in {findYear}"); WaitForEnter(); // Use Scan to get a list of movies from 2001 to 2011. int startYear = 2001; int endYear = 2011; var scanCount = await DynamoDbMethods.ScanTableAsync(client, tableName, startYear, endYear); Console.WriteLine($"Found {scanCount} movies released between {startYear} and {endYear}"); WaitForEnter(); // Delete the table. success = await DynamoDbMethods.DeleteTableAsync(client, tableName); if (success) { Console.WriteLine($"Successfully deleted {tableName}"); } else { Console.WriteLine($"Could not delete {tableName}"); } Console.WriteLine("The DynamoDB Basics example application is done."); WaitForEnter(); } /// <summary> /// Displays the description of the application on the console. /// </summary> private static void DisplayInstructions() { Console.Clear(); Console.WriteLine(); Console.Write(new string(' ', 28)); Console.WriteLine("DynamoDB Basics Example"); Console.WriteLine(SepBar); Console.WriteLine("This demo application shows the basics of using DynamoDB with the AWS SDK."); Console.WriteLine(SepBar); Console.WriteLine("The application does the following:"); Console.WriteLine("\t1. Creates a table with partition: year and sort:title."); Console.WriteLine("\t2. Adds a single movie to the table."); Console.WriteLine("\t3. Adds movies to the table from moviedata.json."); Console.WriteLine("\t4. Updates the rating and plot of the movie that was just added."); Console.WriteLine("\t5. Gets a movie using its key (partition + sort)."); Console.WriteLine("\t6. Deletes a movie."); Console.WriteLine("\t7. Uses QueryAsync to return all movies released in a given year."); Console.WriteLine("\t8. Uses ScanAsync to return all movies released within a range of years."); Console.WriteLine("\t9. Finally, it deletes the table that was just created."); WaitForEnter(); } /// <summary> /// Simple method to wait for the Enter key to be pressed. /// </summary> private static void WaitForEnter() { Console.WriteLine("\nPress <Enter> to continue."); Console.WriteLine(SepBar); _ = Console.ReadLine(); } }
Creates a table to contain movie data.
/// <summary> /// Creates a new Amazon DynamoDB table and then waits for the new /// table to become active. /// </summary> /// <param name="client">An initialized Amazon DynamoDB client object.</param> /// <param name="tableName">The name of the table to create.</param> /// <returns>A Boolean value indicating the success of the operation.</returns> public static async Task<bool> CreateMovieTableAsync(AmazonDynamoDBClient client, string tableName) { var response = await client.CreateTableAsync(new CreateTableRequest { TableName = tableName, AttributeDefinitions = new List<AttributeDefinition>() { new AttributeDefinition { AttributeName = "title", AttributeType = ScalarAttributeType.S, }, new AttributeDefinition { AttributeName = "year", AttributeType = ScalarAttributeType.N, }, }, KeySchema = new List<KeySchemaElement>() { new KeySchemaElement { AttributeName = "year", KeyType = KeyType.HASH, }, new KeySchemaElement { AttributeName = "title", KeyType = KeyType.RANGE, }, }, ProvisionedThroughput = new ProvisionedThroughput { ReadCapacityUnits = 5, WriteCapacityUnits = 5, }, }); // Wait until the table is ACTIVE and then report success. Console.Write("Waiting for table to become active..."); var request = new DescribeTableRequest { TableName = response.TableDescription.TableName, }; TableStatus status; int sleepDuration = 2000; do { System.Threading.Thread.Sleep(sleepDuration); var describeTableResponse = await client.DescribeTableAsync(request); status = describeTableResponse.Table.TableStatus; Console.Write("."); } while (status != "ACTIVE"); return status == TableStatus.ACTIVE; }
Adds a single movie to the table.
/// <summary> /// Adds a new item to the table. /// </summary> /// <param name="client">An initialized Amazon DynamoDB client object.</param> /// <param name="newMovie">A Movie object containing informtation for /// the movie to add to the table.</param> /// <param name="tableName">The name of the table where the item will be added.</param> /// <returns>A Boolean value that indicates the results of adding the item.</returns> public static async Task<bool> PutItemAsync(AmazonDynamoDBClient client, Movie newMovie, string tableName) { var item = new Dictionary<string, AttributeValue> { ["title"] = new AttributeValue { S = newMovie.Title }, ["year"] = new AttributeValue { N = newMovie.Year.ToString() }, }; var request = new PutItemRequest { TableName = tableName, Item = item, }; var response = await client.PutItemAsync(request); return response.HttpStatusCode == System.Net.HttpStatusCode.OK; }
Updates a single item in a table.
/// <summary> /// Updates an existing item in the movies table. /// </summary> /// <param name="client">An initialized Amazon DynamoDB client object.</param> /// <param name="newMovie">A Movie object containing information for /// the movie to update.</param> /// <param name="newInfo">A MovieInfo object that contains the /// information that will be changed.</param> /// <param name="tableName">The name of the table that contains the movie.</param> /// <returns>A Boolean value that indicates the success of the operation.</returns> public static async Task<bool> UpdateItemAsync( AmazonDynamoDBClient client, Movie newMovie, MovieInfo newInfo, string tableName) { var key = new Dictionary<string, AttributeValue> { ["title"] = new AttributeValue { S = newMovie.Title }, ["year"] = new AttributeValue { N = newMovie.Year.ToString() }, }; var updates = new Dictionary<string, AttributeValueUpdate> { ["info.plot"] = new AttributeValueUpdate { Action = AttributeAction.PUT, Value = new AttributeValue { S = newInfo.Plot }, }, ["info.rating"] = new AttributeValueUpdate { Action = AttributeAction.PUT, Value = new AttributeValue { N = newInfo.Rank.ToString() }, }, }; var request = new UpdateItemRequest { AttributeUpdates = updates, Key = key, TableName = tableName, }; var response = await client.UpdateItemAsync(request); return response.HttpStatusCode == System.Net.HttpStatusCode.OK; }
Retrieves a single item from the movie table.
/// <summary> /// Gets information about an existing movie from the table. /// </summary> /// <param name="client">An initialized Amazon DynamoDB client object.</param> /// <param name="newMovie">A Movie object containing information about /// the movie to retrieve.</param> /// <param name="tableName">The name of the table containing the movie.</param> /// <returns>A Dictionary object containing information about the item /// retrieved.</returns> public static async Task<Dictionary<string, AttributeValue>> GetItemAsync(AmazonDynamoDBClient client, Movie newMovie, string tableName) { var key = new Dictionary<string, AttributeValue> { ["title"] = new AttributeValue { S = newMovie.Title }, ["year"] = new AttributeValue { N = newMovie.Year.ToString() }, }; var request = new GetItemRequest { Key = key, TableName = tableName, }; var response = await client.GetItemAsync(request); return response.Item; }
Writes a batch of items to the movie table.
/// <summary> /// Loads the contents of a JSON file into a list of movies to be /// added to the DynamoDB table. /// </summary> /// <param name="movieFileName">The full path to the JSON file.</param> /// <returns>A generic list of movie objects.</returns> public static List<Movie> ImportMovies(string movieFileName) { if (!File.Exists(movieFileName)) { return null; } using var sr = new StreamReader(movieFileName); string json = sr.ReadToEnd(); var allMovies = JsonSerializer.Deserialize<List<Movie>>( json, new JsonSerializerOptions { PropertyNameCaseInsensitive = true }); // Now return the first 250 entries. return allMovies.GetRange(0, 250); } /// <summary> /// Writes 250 items to the movie table. /// </summary> /// <param name="client">The initialized DynamoDB client object.</param> /// <param name="movieFileName">A string containing the full path to /// the JSON file containing movie data.</param> /// <returns>A long integer value representing the number of movies /// imported from the JSON file.</returns> public static async Task<long> BatchWriteItemsAsync( AmazonDynamoDBClient client, string movieFileName) { var movies = ImportMovies(movieFileName); if (movies is null) { Console.WriteLine("Couldn't find the JSON file with movie data."); return 0; } var context = new DynamoDBContext(client); var movieBatch = context.CreateBatchWrite<Movie>(); movieBatch.AddPutItems(movies); Console.WriteLine("Adding imported movies to the table."); await movieBatch.ExecuteAsync(); return movies.Count; }
Deletes a single item from the table.
/// <summary> /// Deletes a single item from a DynamoDB table. /// </summary> /// <param name="client">The initialized DynamoDB client object.</param> /// <param name="tableName">The name of the table from which the item /// will be deleted.</param> /// <param name="movieToDelete">A movie object containing the title and /// year of the movie to delete.</param> /// <returns>A Boolean value indicating the success or failure of the /// delete operation.</returns> public static async Task<bool> DeleteItemAsync( AmazonDynamoDBClient client, string tableName, Movie movieToDelete) { var key = new Dictionary<string, AttributeValue> { ["title"] = new AttributeValue { S = movieToDelete.Title }, ["year"] = new AttributeValue { N = movieToDelete.Year.ToString() }, }; var request = new DeleteItemRequest { TableName = tableName, Key = key, }; var response = await client.DeleteItemAsync(request); return response.HttpStatusCode == System.Net.HttpStatusCode.OK; }
Queries the table for movies released in a particular year.
/// <summary> /// Queries the table for movies released in a particular year and /// then displays the information for the movies returned. /// </summary> /// <param name="client">The initialized DynamoDB client object.</param> /// <param name="tableName">The name of the table to query.</param> /// <param name="year">The release year for which we want to /// view movies.</param> /// <returns>The number of movies that match the query.</returns> public static async Task<int> QueryMoviesAsync(AmazonDynamoDBClient client, string tableName, int year) { var movieTable = Table.LoadTable(client, tableName); var filter = new QueryFilter("year", QueryOperator.Equal, year); Console.WriteLine("\nFind movies released in: {year}:"); var config = new QueryOperationConfig() { Limit = 10, // 10 items per page. Select = SelectValues.SpecificAttributes, AttributesToGet = new List<string> { "title", "year", }, ConsistentRead = true, Filter = filter, }; // Value used to track how many movies match the // supplied criteria. var moviesFound = 0; Search search = movieTable.Query(config); do { var movieList = await search.GetNextSetAsync(); moviesFound += movieList.Count; foreach (var movie in movieList) { DisplayDocument(movie); } } while (!search.IsDone); return moviesFound; }
Scans the table for movies released in a range of years.
public static async Task<int> ScanTableAsync( AmazonDynamoDBClient client, string tableName, int startYear, int endYear) { var request = new ScanRequest { TableName = tableName, ExpressionAttributeNames = new Dictionary<string, string> { { "#yr", "year" }, }, ExpressionAttributeValues = new Dictionary<string, AttributeValue> { { ":y_a", new AttributeValue { N = startYear.ToString() } }, { ":y_z", new AttributeValue { N = endYear.ToString() } }, }, FilterExpression = "#yr between :y_a and :y_z", ProjectionExpression = "#yr, title, info.actors[0], info.directors, info.running_time_secs", Limit = 10 // Set a limit to demonstrate using the LastEvaluatedKey. }; // Keep track of how many movies were found. int foundCount = 0; var response = new ScanResponse(); do { response = await client.ScanAsync(request); foundCount += response.Items.Count; response.Items.ForEach(i => DisplayItem(i)); request.ExclusiveStartKey = response.LastEvaluatedKey; } while (response.LastEvaluatedKey.Count > 0); return foundCount; }
Deletes the movie table.
public static async Task<bool> DeleteTableAsync(AmazonDynamoDBClient client, string tableName) { var request = new DeleteTableRequest { TableName = tableName, }; var response = await client.DeleteTableAsync(request); if (response.HttpStatusCode == System.Net.HttpStatusCode.OK) { Console.WriteLine($"Table {response.TableDescription.TableName} successfully deleted."); return true; } else { Console.WriteLine("Could not delete table."); return false; } }
-
For API details, see the following topics 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
. The DynamoDB getting started scenario.
############################################################################### # function dynamodb_getting_started_movies # # Scenario to create an Amazon DynamoDB table and perform a series of operations on the table. # # Returns: # 0 - If successful. # 1 - If an error occurred. ############################################################################### function dynamodb_getting_started_movies() { source ./dynamodb_operations.sh key_schema_json_file="dynamodb_key_schema.json" attribute_definitions_json_file="dynamodb_attr_def.json" item_json_file="movie_item.json" key_json_file="movie_key.json" batch_json_file="batch.json" attribute_names_json_file="attribute_names.json" attributes_values_json_file="attribute_values.json" echo_repeat "*" 88 echo echo "Welcome to the Amazon DynamoDB getting started demo." echo echo_repeat "*" 88 echo local table_name echo -n "Enter a name for a new DynamoDB table: " get_input table_name=$get_input_result local provisioned_throughput="ReadCapacityUnits=5,WriteCapacityUnits=5" echo '[ {"AttributeName": "year", "KeyType": "HASH"}, {"AttributeName": "title", "KeyType": "RANGE"} ]' >"$key_schema_json_file" echo '[ {"AttributeName": "year", "AttributeType": "N"}, {"AttributeName": "title", "AttributeType": "S"} ]' >"$attribute_definitions_json_file" if dynamodb_create_table -n "$table_name" -a "$attribute_definitions_json_file" \ -k "$key_schema_json_file" -p "$provisioned_throughput" 1>/dev/null; then echo "Created a DynamoDB table named $table_name" else errecho "The table failed to create. This demo will exit." clean_up return 1 fi echo "Waiting for the table to become active...." if dynamodb_wait_table_active -n "$table_name"; then echo "The table is now active." else errecho "The table failed to become active. This demo will exit." cleanup "$table_name" return 1 fi echo echo_repeat "*" 88 echo echo -n "Enter the title of a movie you want to add to the table: " get_input local added_title added_title=$get_input_result local added_year get_int_input "What year was it released? " added_year=$get_input_result local rating get_float_input "On a scale of 1 - 10, how do you rate it? " "1" "10" rating=$get_input_result local plot echo -n "Summarize the plot for me: " get_input plot=$get_input_result echo '{ "year": {"N" :"'"$added_year"'"}, "title": {"S" : "'"$added_title"'"}, "info": {"M" : {"plot": {"S" : "'"$plot"'"}, "rating": {"N" :"'"$rating"'"} } } }' >"$item_json_file" if dynamodb_put_item -n "$table_name" -i "$item_json_file"; then echo "The movie '$added_title' was successfully added to the table '$table_name'." else errecho "Put item failed. This demo will exit." clean_up "$table_name" return 1 fi echo echo_repeat "*" 88 echo echo "Let's update your movie '$added_title'." get_float_input "You rated it $rating, what new rating would you give it? " "1" "10" rating=$get_input_result echo -n "You summarized the plot as '$plot'." echo "What would you say now? " get_input plot=$get_input_result echo '{ "year": {"N" :"'"$added_year"'"}, "title": {"S" : "'"$added_title"'"} }' >"$key_json_file" echo '{ ":r": {"N" :"'"$rating"'"}, ":p": {"S" : "'"$plot"'"} }' >"$item_json_file" local update_expression="SET info.rating = :r, info.plot = :p" if dynamodb_update_item -n "$table_name" -k "$key_json_file" -e "$update_expression" -v "$item_json_file"; then echo "Updated '$added_title' with new attributes." else errecho "Update item failed. This demo will exit." clean_up "$table_name" return 1 fi echo echo_repeat "*" 88 echo echo "We will now use batch write to upload 150 movie entries into the table." local batch_json for batch_json in movie_files/movies_*.json; do echo "{ \"$table_name\" : $(<"$batch_json") }" >"$batch_json_file" if dynamodb_batch_write_item -i "$batch_json_file" 1>/dev/null; then echo "Entries in $batch_json added to table." else errecho "Batch write failed. This demo will exit." clean_up "$table_name" return 1 fi done local title="The Lord of the Rings: The Fellowship of the Ring" local year="2001" if get_yes_no_input "Let's move on...do you want to get info about '$title'? (y/n) "; then echo '{ "year": {"N" :"'"$year"'"}, "title": {"S" : "'"$title"'"} }' >"$key_json_file" local info info=$(dynamodb_get_item -n "$table_name" -k "$key_json_file") # shellcheck disable=SC2181 if [[ ${?} -ne 0 ]]; then errecho "Get item failed. This demo will exit." clean_up "$table_name" return 1 fi echo "Here is what I found:" echo "$info" fi local ask_for_year=true while [[ "$ask_for_year" == true ]]; do echo "Let's get a list of movies released in a given year." get_int_input "Enter a year between 1972 and 2018: " "1972" "2018" year=$get_input_result echo '{ "#n": "year" }' >"$attribute_names_json_file" echo '{ ":v": {"N" :"'"$year"'"} }' >"$attributes_values_json_file" response=$(dynamodb_query -n "$table_name" -k "#n=:v" -a "$attribute_names_json_file" -v "$attributes_values_json_file") # shellcheck disable=SC2181 if [[ ${?} -ne 0 ]]; then errecho "Query table failed. This demo will exit." clean_up "$table_name" return 1 fi echo "Here is what I found:" echo "$response" if ! get_yes_no_input "Try another year? (y/n) "; then ask_for_year=false fi done echo "Now let's scan for movies released in a range of years. Enter a year: " get_int_input "Enter a year between 1972 and 2018: " "1972" "2018" local start=$get_input_result get_int_input "Enter another year: " "1972" "2018" local end=$get_input_result echo '{ "#n": "year" }' >"$attribute_names_json_file" echo '{ ":v1": {"N" : "'"$start"'"}, ":v2": {"N" : "'"$end"'"} }' >"$attributes_values_json_file" response=$(dynamodb_scan -n "$table_name" -f "#n BETWEEN :v1 AND :v2" -a "$attribute_names_json_file" -v "$attributes_values_json_file") # shellcheck disable=SC2181 if [[ ${?} -ne 0 ]]; then errecho "Scan table failed. This demo will exit." clean_up "$table_name" return 1 fi echo "Here is what I found:" echo "$response" echo echo_repeat "*" 88 echo echo "Let's remove your movie '$added_title' from the table." if get_yes_no_input "Do you want to remove '$added_title'? (y/n) "; then echo '{ "year": {"N" :"'"$added_year"'"}, "title": {"S" : "'"$added_title"'"} }' >"$key_json_file" if ! dynamodb_delete_item -n "$table_name" -k "$key_json_file"; then errecho "Delete item failed. This demo will exit." clean_up "$table_name" return 1 fi fi if get_yes_no_input "Do you want to delete the table '$table_name'? (y/n) "; then if ! clean_up "$table_name"; then return 1 fi else if ! clean_up; then return 1 fi fi return 0 }
The DynamoDB functions used in this scenario.
############################################################################### # function dynamodb_create_table # # This function creates an Amazon DynamoDB table. # # Parameters: # -n table_name -- The name of the table to create. # -a attribute_definitions -- JSON file path of a list of attributes and their types. # -k key_schema -- JSON file path of a list of attributes and their key types. # -p provisioned_throughput -- Provisioned throughput settings for the table. # # Returns: # 0 - If successful. # 1 - If it fails. ############################################################################### function dynamodb_create_table() { local table_name attribute_definitions key_schema provisioned_throughput response local option OPTARG # Required to use getopts command in a function. ####################################### # Function usage explanation ####################################### function usage() { echo "function dynamodb_create_table" echo "Creates an Amazon DynamoDB table." echo " -n table_name -- The name of the table to create." echo " -a attribute_definitions -- JSON file path of a list of attributes and their types." echo " -k key_schema -- JSON file path of a list of attributes and their key types." echo " -p provisioned_throughput -- Provisioned throughput settings for the table." echo "" } # Retrieve the calling parameters. while getopts "n:a:k:p:h" option; do case "${option}" in n) table_name="${OPTARG}" ;; a) attribute_definitions="${OPTARG}" ;; k) key_schema="${OPTARG}" ;; p) provisioned_throughput="${OPTARG}" ;; h) usage return 0 ;; \?) echo "Invalid parameter" usage return 1 ;; esac done export OPTIND=1 if [[ -z "$table_name" ]]; then errecho "ERROR: You must provide a table name with the -n parameter." usage return 1 fi if [[ -z "$attribute_definitions" ]]; then errecho "ERROR: You must provide an attribute definitions json file path the -a parameter." usage return 1 fi if [[ -z "$key_schema" ]]; then errecho "ERROR: You must provide a key schema json file path the -k parameter." usage return 1 fi if [[ -z "$provisioned_throughput" ]]; then errecho "ERROR: You must provide a provisioned throughput json file path the -p parameter." usage return 1 fi iecho "Parameters:\n" iecho " table_name: $table_name" iecho " attribute_definitions: $attribute_definitions" iecho " key_schema: $key_schema" iecho " provisioned_throughput: $provisioned_throughput" iecho "" response=$(aws dynamodb create-table \ --table-name "$table_name" \ --attribute-definitions file://"$attribute_definitions" \ --key-schema file://"$key_schema" \ --provisioned-throughput "$provisioned_throughput") local error_code=${?} if [[ $error_code -ne 0 ]]; then aws_cli_error_log $error_code errecho "ERROR: AWS reports create-table operation failed.$response" return 1 fi return 0 } ############################################################################### # function dynamodb_describe_table # # This function returns the status of a DynamoDB table. # # Parameters: # -n table_name -- The name of the table. # # Response: # - TableStatus: # And: # 0 - Table is active. # 1 - If it fails. ############################################################################### function dynamodb_describe_table { local table_name local option OPTARG # Required to use getopts command in a function. ####################################### # Function usage explanation ####################################### function usage() { echo "function dynamodb_describe_table" echo "Describe the status of a DynamoDB table." echo " -n table_name -- The name of the table." echo "" } # Retrieve the calling parameters. while getopts "n:h" option; do case "${option}" in n) table_name="${OPTARG}" ;; h) usage return 0 ;; \?) echo "Invalid parameter" usage return 1 ;; esac done export OPTIND=1 if [[ -z "$table_name" ]]; then errecho "ERROR: You must provide a table name with the -n parameter." usage return 1 fi local table_status table_status=$( aws dynamodb describe-table \ --table-name "$table_name" \ --output text \ --query 'Table.TableStatus' ) local error_code=${?} if [[ $error_code -ne 0 ]]; then aws_cli_error_log "$error_code" errecho "ERROR: AWS reports describe-table operation failed.$table_status" return 1 fi echo "$table_status" return 0 } ############################################################################## # function dynamodb_put_item # # This function puts an item into a DynamoDB table. # # Parameters: # -n table_name -- The name of the table. # -i item -- Path to json file containing the item values. # # Returns: # 0 - If successful. # 1 - If it fails. ############################################################################## function dynamodb_put_item() { local table_name item response local option OPTARG # Required to use getopts command in a function. ####################################### # Function usage explanation ####################################### function usage() { echo "function dynamodb_put_item" echo "Put an item into a DynamoDB table." echo " -n table_name -- The name of the table." echo " -i item -- Path to json file containing the item values." echo "" } while getopts "n:i:h" option; do case "${option}" in n) table_name="${OPTARG}" ;; i) item="${OPTARG}" ;; h) usage return 0 ;; \?) echo "Invalid parameter" usage return 1 ;; esac done export OPTIND=1 if [[ -z "$table_name" ]]; then errecho "ERROR: You must provide a table name with the -n parameter." usage return 1 fi if [[ -z "$item" ]]; then errecho "ERROR: You must provide an item with the -i parameter." usage return 1 fi iecho "Parameters:\n" iecho " table_name: $table_name" iecho " item: $item" iecho "" iecho "" response=$(aws dynamodb put-item \ --table-name "$table_name" \ --item file://"$item") local error_code=${?} if [[ $error_code -ne 0 ]]; then aws_cli_error_log $error_code errecho "ERROR: AWS reports put-item operation failed.$response" return 1 fi return 0 } ############################################################################## # function dynamodb_update_item # # This function updates an item in a DynamoDB table. # # # Parameters: # -n table_name -- The name of the table. # -k keys -- Path to json file containing the keys that identify the item to update. # -e update expression -- An expression that defines one or more attributes to be updated. # -v values -- Path to json file containing the update values. # # Returns: # 0 - If successful. # 1 - If it fails. ############################################################################# function dynamodb_update_item() { local table_name keys update_expression values response local option OPTARG # Required to use getopts command in a function. ####################################### # Function usage explanation ####################################### function usage() { echo "function dynamodb_update_item" echo "Update an item in a DynamoDB table." echo " -n table_name -- The name of the table." echo " -k keys -- Path to json file containing the keys that identify the item to update." echo " -e update expression -- An expression that defines one or more attributes to be updated." echo " -v values -- Path to json file containing the update values." echo "" } while getopts "n:k:e:v:h" option; do case "${option}" in n) table_name="${OPTARG}" ;; k) keys="${OPTARG}" ;; e) update_expression="${OPTARG}" ;; v) values="${OPTARG}" ;; h) usage return 0 ;; \?) echo "Invalid parameter" usage return 1 ;; esac done export OPTIND=1 if [[ -z "$table_name" ]]; then errecho "ERROR: You must provide a table name with the -n parameter." usage return 1 fi if [[ -z "$keys" ]]; then errecho "ERROR: You must provide a keys json file path the -k parameter." usage return 1 fi if [[ -z "$update_expression" ]]; then errecho "ERROR: You must provide an update expression with the -e parameter." usage return 1 fi if [[ -z "$values" ]]; then errecho "ERROR: You must provide a values json file path the -v parameter." usage return 1 fi iecho "Parameters:\n" iecho " table_name: $table_name" iecho " keys: $keys" iecho " update_expression: $update_expression" iecho " values: $values" response=$(aws dynamodb update-item \ --table-name "$table_name" \ --key file://"$keys" \ --update-expression "$update_expression" \ --expression-attribute-values file://"$values") local error_code=${?} if [[ $error_code -ne 0 ]]; then aws_cli_error_log $error_code errecho "ERROR: AWS reports update-item operation failed.$response" return 1 fi return 0 } ############################################################################## # function dynamodb_batch_write_item # # This function writes a batch of items into a DynamoDB table. # # Parameters: # -i item -- Path to json file containing the items to write. # # Returns: # 0 - If successful. # 1 - If it fails. ############################################################################ function dynamodb_batch_write_item() { local item response local option OPTARG # Required to use getopts command in a function. ####################################### # Function usage explanation ####################################### function usage() { echo "function dynamodb_batch_write_item" echo "Write a batch of items into a DynamoDB table." echo " -i item -- Path to json file containing the items to write." 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 iecho "Parameters:\n" iecho " table_name: $table_name" iecho " item: $item" iecho "" response=$(aws dynamodb batch-write-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-write-item operation failed.$response" return 1 fi return 0 } ############################################################################# # function dynamodb_get_item # # This function gets an item from a DynamoDB table. # # Parameters: # -n table_name -- The name of the table. # -k keys -- Path to json file containing the keys that identify the item to get. # [-q query] -- Optional JMESPath query expression. # # Returns: # The item as text output. # And: # 0 - If successful. # 1 - If it fails. ############################################################################ function dynamodb_get_item() { local table_name keys query response local option OPTARG # Required to use getopts command in a function. # ###################################### # Function usage explanation ####################################### function usage() { echo "function dynamodb_get_item" echo "Get an item from a DynamoDB table." echo " -n table_name -- The name of the table." echo " -k keys -- Path to json file containing the keys that identify the item to get." echo " [-q query] -- Optional JMESPath query expression." echo "" } query="" while getopts "n:k:q:h" option; do case "${option}" in n) table_name="${OPTARG}" ;; k) keys="${OPTARG}" ;; q) query="${OPTARG}" ;; h) usage return 0 ;; \?) echo "Invalid parameter" usage return 1 ;; esac done export OPTIND=1 if [[ -z "$table_name" ]]; then errecho "ERROR: You must provide a table name with the -n parameter." usage return 1 fi if [[ -z "$keys" ]]; then errecho "ERROR: You must provide a keys json file path the -k parameter." usage return 1 fi if [[ -n "$query" ]]; then response=$(aws dynamodb get-item \ --table-name "$table_name" \ --key file://"$keys" \ --output text \ --query "$query") else response=$( aws dynamodb get-item \ --table-name "$table_name" \ --key file://"$keys" \ --output text ) fi local error_code=${?} if [[ $error_code -ne 0 ]]; then aws_cli_error_log $error_code errecho "ERROR: AWS reports get-item operation failed.$response" return 1 fi if [[ -n "$query" ]]; then echo "$response" | sed "/^\t/s/\t//1" # Remove initial tab that the JMSEPath query inserts on some strings. else echo "$response" fi return 0 } ############################################################################# # function dynamodb_query # # This function queries a DynamoDB table. # # Parameters: # -n table_name -- The name of the table. # -k key_condition_expression -- The key condition expression. # -a attribute_names -- Path to JSON file containing the attribute names. # -v attribute_values -- Path to JSON file containing the attribute values. # [-p projection_expression] -- Optional projection expression. # # Returns: # The items as json output. # And: # 0 - If successful. # 1 - If it fails. ########################################################################### function dynamodb_query() { local table_name key_condition_expression attribute_names attribute_values projection_expression response local option OPTARG # Required to use getopts command in a function. # ###################################### # Function usage explanation ####################################### function usage() { echo "function dynamodb_query" echo "Query a DynamoDB table." echo " -n table_name -- The name of the table." echo " -k key_condition_expression -- The key condition expression." echo " -a attribute_names -- Path to JSON file containing the attribute names." echo " -v attribute_values -- Path to JSON file containing the attribute values." echo " [-p projection_expression] -- Optional projection expression." echo "" } while getopts "n:k:a:v:p:h" option; do case "${option}" in n) table_name="${OPTARG}" ;; k) key_condition_expression="${OPTARG}" ;; a) attribute_names="${OPTARG}" ;; v) attribute_values="${OPTARG}" ;; p) projection_expression="${OPTARG}" ;; h) usage return 0 ;; \?) echo "Invalid parameter" usage return 1 ;; esac done export OPTIND=1 if [[ -z "$table_name" ]]; then errecho "ERROR: You must provide a table name with the -n parameter." usage return 1 fi if [[ -z "$key_condition_expression" ]]; then errecho "ERROR: You must provide a key condition expression with the -k parameter." usage return 1 fi if [[ -z "$attribute_names" ]]; then errecho "ERROR: You must provide a attribute names with the -a parameter." usage return 1 fi if [[ -z "$attribute_values" ]]; then errecho "ERROR: You must provide a attribute values with the -v parameter." usage return 1 fi if [[ -z "$projection_expression" ]]; then response=$(aws dynamodb query \ --table-name "$table_name" \ --key-condition-expression "$key_condition_expression" \ --expression-attribute-names file://"$attribute_names" \ --expression-attribute-values file://"$attribute_values") else response=$(aws dynamodb query \ --table-name "$table_name" \ --key-condition-expression "$key_condition_expression" \ --expression-attribute-names file://"$attribute_names" \ --expression-attribute-values file://"$attribute_values" \ --projection-expression "$projection_expression") fi local error_code=${?} if [[ $error_code -ne 0 ]]; then aws_cli_error_log $error_code errecho "ERROR: AWS reports query operation failed.$response" return 1 fi echo "$response" return 0 } ############################################################################# # function dynamodb_scan # # This function scans a DynamoDB table. # # Parameters: # -n table_name -- The name of the table. # -f filter_expression -- The filter expression. # -a expression_attribute_names -- Path to JSON file containing the expression attribute names. # -v expression_attribute_values -- Path to JSON file containing the expression attribute values. # [-p projection_expression] -- Optional projection expression. # # Returns: # The items as json output. # And: # 0 - If successful. # 1 - If it fails. ########################################################################### function dynamodb_scan() { local table_name filter_expression expression_attribute_names expression_attribute_values projection_expression response local option OPTARG # Required to use getopts command in a function. # ###################################### # Function usage explanation ####################################### function usage() { echo "function dynamodb_scan" echo "Scan a DynamoDB table." echo " -n table_name -- The name of the table." echo " -f filter_expression -- The filter expression." echo " -a expression_attribute_names -- Path to JSON file containing the expression attribute names." echo " -v expression_attribute_values -- Path to JSON file containing the expression attribute values." echo " [-p projection_expression] -- Optional projection expression." echo "" } while getopts "n:f:a:v:p:h" option; do case "${option}" in n) table_name="${OPTARG}" ;; f) filter_expression="${OPTARG}" ;; a) expression_attribute_names="${OPTARG}" ;; v) expression_attribute_values="${OPTARG}" ;; p) projection_expression="${OPTARG}" ;; h) usage return 0 ;; \?) echo "Invalid parameter" usage return 1 ;; esac done export OPTIND=1 if [[ -z "$table_name" ]]; then errecho "ERROR: You must provide a table name with the -n parameter." usage return 1 fi if [[ -z "$filter_expression" ]]; then errecho "ERROR: You must provide a filter expression with the -f parameter." usage return 1 fi if [[ -z "$expression_attribute_names" ]]; then errecho "ERROR: You must provide expression attribute names with the -a parameter." usage return 1 fi if [[ -z "$expression_attribute_values" ]]; then errecho "ERROR: You must provide expression attribute values with the -v parameter." usage return 1 fi if [[ -z "$projection_expression" ]]; then response=$(aws dynamodb scan \ --table-name "$table_name" \ --filter-expression "$filter_expression" \ --expression-attribute-names file://"$expression_attribute_names" \ --expression-attribute-values file://"$expression_attribute_values") else response=$(aws dynamodb scan \ --table-name "$table_name" \ --filter-expression "$filter_expression" \ --expression-attribute-names file://"$expression_attribute_names" \ --expression-attribute-values file://"$expression_attribute_values" \ --projection-expression "$projection_expression") fi local error_code=${?} if [[ $error_code -ne 0 ]]; then aws_cli_error_log $error_code errecho "ERROR: AWS reports scan operation failed.$response" return 1 fi echo "$response" return 0 } ############################################################################## # function dynamodb_delete_item # # This function deletes an item from a DynamoDB table. # # Parameters: # -n table_name -- The name of the table. # -k keys -- Path to json file containing the keys that identify the item to delete. # # Returns: # 0 - If successful. # 1 - If it fails. ########################################################################### function dynamodb_delete_item() { local table_name keys response local option OPTARG # Required to use getopts command in a function. # ###################################### # Function usage explanation ####################################### function usage() { echo "function dynamodb_delete_item" echo "Delete an item from a DynamoDB table." echo " -n table_name -- The name of the table." echo " -k keys -- Path to json file containing the keys that identify the item to delete." echo "" } while getopts "n:k:h" option; do case "${option}" in n) table_name="${OPTARG}" ;; k) keys="${OPTARG}" ;; h) usage return 0 ;; \?) echo "Invalid parameter" usage return 1 ;; esac done export OPTIND=1 if [[ -z "$table_name" ]]; then errecho "ERROR: You must provide a table name with the -n parameter." usage return 1 fi if [[ -z "$keys" ]]; then errecho "ERROR: You must provide a keys json file path the -k parameter." usage return 1 fi iecho "Parameters:\n" iecho " table_name: $table_name" iecho " keys: $keys" iecho "" response=$(aws dynamodb delete-item \ --table-name "$table_name" \ --key file://"$keys") local error_code=${?} if [[ $error_code -ne 0 ]]; then aws_cli_error_log $error_code errecho "ERROR: AWS reports delete-item operation failed.$response" return 1 fi return 0 } ############################################################################### # function dynamodb_delete_table # # This function deletes a DynamoDB table. # # Parameters: # -n table_name -- The name of the table to delete. # # Returns: # 0 - If successful. # 1 - If it fails. ############################################################################### function dynamodb_delete_table() { local table_name response local option OPTARG # Required to use getopts command in a function. # bashsupport disable=BP5008 function usage() { echo "function dynamodb_delete_table" echo "Deletes an Amazon DynamoDB table." echo " -n table_name -- The name of the table to delete." echo "" } # Retrieve the calling parameters. while getopts "n:h" option; do case "${option}" in n) table_name="${OPTARG}" ;; h) usage return 0 ;; \?) echo "Invalid parameter" usage return 1 ;; esac done export OPTIND=1 if [[ -z "$table_name" ]]; then errecho "ERROR: You must provide a table name with the -n parameter." usage return 1 fi iecho "Parameters:\n" iecho " table_name: $table_name" iecho "" response=$(aws dynamodb delete-table \ --table-name "$table_name") local error_code=${?} if [[ $error_code -ne 0 ]]; then aws_cli_error_log $error_code errecho "ERROR: AWS reports delete-table operation failed.$response" return 1 fi return 0 }
The utility functions used in this scenario.
############################################################################### # function iecho # # This function enables the script to display the specified text only if # the global variable $VERBOSE is set to true. ############################################################################### function iecho() { if [[ $VERBOSE == true ]]; then echo "$@" fi } ############################################################################### # 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 the following topics 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
. { Aws::Client::ClientConfiguration clientConfig; // 1. Create a table with partition: year (N) and sort: title (S). (CreateTable) if (AwsDoc::DynamoDB::createMoviesDynamoDBTable(clientConfig)) { AwsDoc::DynamoDB::dynamodbGettingStartedScenario(clientConfig); // 9. Delete the table. (DeleteTable) AwsDoc::DynamoDB::deleteMoviesDynamoDBTable(clientConfig); } } //! Scenario to modify and query a DynamoDB table. /*! \sa dynamodbGettingStartedScenario() \param clientConfiguration: AWS client configuration. \return bool: Function succeeded. */ bool AwsDoc::DynamoDB::dynamodbGettingStartedScenario( const Aws::Client::ClientConfiguration &clientConfiguration) { std::cout << std::setfill('*') << std::setw(ASTERISK_FILL_WIDTH) << " " << std::endl; std::cout << "Welcome to the Amazon DynamoDB getting started demo." << std::endl; std::cout << std::setfill('*') << std::setw(ASTERISK_FILL_WIDTH) << " " << std::endl; Aws::DynamoDB::DynamoDBClient dynamoClient(clientConfiguration); // 2. Add a new movie. Aws::String title; float rating; int year; Aws::String plot; { title = askQuestion( "Enter the title of a movie you want to add to the table: "); year = askQuestionForInt("What year was it released? "); rating = askQuestionForFloatRange("On a scale of 1 - 10, how do you rate it? ", 1, 10); plot = askQuestion("Summarize the plot for me: "); Aws::DynamoDB::Model::PutItemRequest putItemRequest; putItemRequest.SetTableName(MOVIE_TABLE_NAME); putItemRequest.AddItem(YEAR_KEY, Aws::DynamoDB::Model::AttributeValue().SetN(year)); putItemRequest.AddItem(TITLE_KEY, Aws::DynamoDB::Model::AttributeValue().SetS(title)); // Create attribute for the info map. Aws::DynamoDB::Model::AttributeValue infoMapAttribute; std::shared_ptr<Aws::DynamoDB::Model::AttributeValue> ratingAttribute = Aws::MakeShared<Aws::DynamoDB::Model::AttributeValue>( ALLOCATION_TAG.c_str()); ratingAttribute->SetN(rating); infoMapAttribute.AddMEntry(RATING_KEY, ratingAttribute); std::shared_ptr<Aws::DynamoDB::Model::AttributeValue> plotAttribute = Aws::MakeShared<Aws::DynamoDB::Model::AttributeValue>( ALLOCATION_TAG.c_str()); plotAttribute->SetS(plot); infoMapAttribute.AddMEntry(PLOT_KEY, plotAttribute); putItemRequest.AddItem(INFO_KEY, infoMapAttribute); Aws::DynamoDB::Model::PutItemOutcome outcome = dynamoClient.PutItem( putItemRequest); if (!outcome.IsSuccess()) { std::cerr << "Failed to add an item: " << outcome.GetError().GetMessage() << std::endl; return false; } } std::cout << "\nAdded '" << title << "' to '" << MOVIE_TABLE_NAME << "'." << std::endl; // 3. Update the rating and plot of the movie by using an update expression. { rating = askQuestionForFloatRange( Aws::String("\nLet's update your movie.\nYou rated it ") + std::to_string(rating) + ", what new rating would you give it? ", 1, 10); plot = askQuestion(Aws::String("You summarized the plot as '") + plot + "'.\nWhat would you say now? "); Aws::DynamoDB::Model::UpdateItemRequest request; request.SetTableName(MOVIE_TABLE_NAME); request.AddKey(TITLE_KEY, Aws::DynamoDB::Model::AttributeValue().SetS(title)); request.AddKey(YEAR_KEY, Aws::DynamoDB::Model::AttributeValue().SetN(year)); std::stringstream expressionStream; expressionStream << "set " << INFO_KEY << "." << RATING_KEY << " =:r, " << INFO_KEY << "." << PLOT_KEY << " =:p"; request.SetUpdateExpression(expressionStream.str()); request.SetExpressionAttributeValues({ {":r", Aws::DynamoDB::Model::AttributeValue().SetN( rating)}, {":p", Aws::DynamoDB::Model::AttributeValue().SetS( plot)} }); request.SetReturnValues(Aws::DynamoDB::Model::ReturnValue::UPDATED_NEW); const Aws::DynamoDB::Model::UpdateItemOutcome &result = dynamoClient.UpdateItem( request); if (!result.IsSuccess()) { std::cerr << "Error updating movie " + result.GetError().GetMessage() << std::endl; return false; } } std::cout << "\nUpdated '" << title << "' with new attributes:" << std::endl; // 4. Put 250 movies in the table from moviedata.json. { std::cout << "Adding movies from a json file to the database." << std::endl; const size_t MAX_SIZE_FOR_BATCH_WRITE = 25; const size_t MOVIES_TO_WRITE = 10 * MAX_SIZE_FOR_BATCH_WRITE; Aws::String jsonString = getMovieJSON(); if (!jsonString.empty()) { Aws::Utils::Json::JsonValue json(jsonString); Aws::Utils::Array<Aws::Utils::Json::JsonView> movieJsons = json.View().AsArray(); Aws::Vector<Aws::DynamoDB::Model::WriteRequest> writeRequests; // To add movies with a cross-section of years, use an appropriate increment // value for iterating through the database. size_t increment = movieJsons.GetLength() / MOVIES_TO_WRITE; for (size_t i = 0; i < movieJsons.GetLength(); i += increment) { writeRequests.push_back(Aws::DynamoDB::Model::WriteRequest()); Aws::Map<Aws::String, Aws::DynamoDB::Model::AttributeValue> putItems = movieJsonViewToAttributeMap( movieJsons[i]); Aws::DynamoDB::Model::PutRequest putRequest; putRequest.SetItem(putItems); writeRequests.back().SetPutRequest(putRequest); if (writeRequests.size() == MAX_SIZE_FOR_BATCH_WRITE) { Aws::DynamoDB::Model::BatchWriteItemRequest request; request.AddRequestItems(MOVIE_TABLE_NAME, writeRequests); const Aws::DynamoDB::Model::BatchWriteItemOutcome &outcome = dynamoClient.BatchWriteItem( request); if (!outcome.IsSuccess()) { std::cerr << "Unable to batch write movie data: " << outcome.GetError().GetMessage() << std::endl; writeRequests.clear(); break; } else { std::cout << "Added batch of " << writeRequests.size() << " movies to the database." << std::endl; } writeRequests.clear(); } } } } std::cout << std::setfill('*') << std::setw(ASTERISK_FILL_WIDTH) << " " << std::endl; // 5. Get a movie by Key (partition + sort). { Aws::String titleToGet("King Kong"); Aws::String answer = askQuestion(Aws::String( "Let's move on...Would you like to get info about '" + titleToGet + "'? (y/n) ")); if (answer == "y") { Aws::DynamoDB::Model::GetItemRequest request; request.SetTableName(MOVIE_TABLE_NAME); request.AddKey(TITLE_KEY, Aws::DynamoDB::Model::AttributeValue().SetS(titleToGet)); request.AddKey(YEAR_KEY, Aws::DynamoDB::Model::AttributeValue().SetN(1933)); const Aws::DynamoDB::Model::GetItemOutcome &result = dynamoClient.GetItem( request); if (!result.IsSuccess()) { std::cerr << "Error " << result.GetError().GetMessage(); } else { const Aws::Map<Aws::String, Aws::DynamoDB::Model::AttributeValue> &item = result.GetResult().GetItem(); if (!item.empty()) { std::cout << "\nHere's what I found:" << std::endl; printMovieInfo(item); } else { std::cout << "\nThe movie was not found in the database." << std::endl; } } } } // 6. Use Query with a key condition expression to return all movies // released in a given year. Aws::String doAgain = "n"; do { Aws::DynamoDB::Model::QueryRequest req; req.SetTableName(MOVIE_TABLE_NAME); // "year" is a DynamoDB reserved keyword and must be replaced with an // expression attribute name. req.SetKeyConditionExpression("#dynobase_year = :valueToMatch"); req.SetExpressionAttributeNames({{"#dynobase_year", YEAR_KEY}}); int yearToMatch = askQuestionForIntRange( "\nLet's get a list of movies released in" " a given year. Enter a year between 1972 and 2018 ", 1972, 2018); Aws::Map<Aws::String, Aws::DynamoDB::Model::AttributeValue> attributeValues; attributeValues.emplace(":valueToMatch", Aws::DynamoDB::Model::AttributeValue().SetN( yearToMatch)); req.SetExpressionAttributeValues(attributeValues); const Aws::DynamoDB::Model::QueryOutcome &result = dynamoClient.Query(req); if (result.IsSuccess()) { const Aws::Vector<Aws::Map<Aws::String, Aws::DynamoDB::Model::AttributeValue>> &items = result.GetResult().GetItems(); if (!items.empty()) { std::cout << "\nThere were " << items.size() << " movies in the database from " << yearToMatch << "." << std::endl; for (const auto &item: items) { printMovieInfo(item); } doAgain = "n"; } else { std::cout << "\nNo movies from " << yearToMatch << " were found in the database" << std::endl; doAgain = askQuestion(Aws::String("Try another year? (y/n) ")); } } else { std::cerr << "Failed to Query items: " << result.GetError().GetMessage() << std::endl; } } while (doAgain == "y"); // 7. Use Scan to return movies released within a range of years. // Show how to paginate data using ExclusiveStartKey. (Scan + FilterExpression) { int startYear = askQuestionForIntRange("\nNow let's scan a range of years " "for movies in the database. Enter a start year: ", 1972, 2018); int endYear = askQuestionForIntRange("\nEnter an end year: ", startYear, 2018); Aws::Map<Aws::String, Aws::DynamoDB::Model::AttributeValue> exclusiveStartKey; do { Aws::DynamoDB::Model::ScanRequest scanRequest; scanRequest.SetTableName(MOVIE_TABLE_NAME); scanRequest.SetFilterExpression( "#dynobase_year >= :startYear AND #dynobase_year <= :endYear"); scanRequest.SetExpressionAttributeNames({{"#dynobase_year", YEAR_KEY}}); Aws::Map<Aws::String, Aws::DynamoDB::Model::AttributeValue> attributeValues; attributeValues.emplace(":startYear", Aws::DynamoDB::Model::AttributeValue().SetN( startYear)); attributeValues.emplace(":endYear", Aws::DynamoDB::Model::AttributeValue().SetN( endYear)); scanRequest.SetExpressionAttributeValues(attributeValues); if (!exclusiveStartKey.empty()) { scanRequest.SetExclusiveStartKey(exclusiveStartKey); } const Aws::DynamoDB::Model::ScanOutcome &result = dynamoClient.Scan( scanRequest); if (result.IsSuccess()) { const Aws::Vector<Aws::Map<Aws::String, Aws::DynamoDB::Model::AttributeValue>> &items = result.GetResult().GetItems(); if (!items.empty()) { std::stringstream stringStream; stringStream << "\nFound " << items.size() << " movies in one scan." << " How many would you like to see? "; size_t count = askQuestionForInt(stringStream.str()); for (size_t i = 0; i < count && i < items.size(); ++i) { printMovieInfo(items[i]); } } else { std::cout << "\nNo movies in the database between " << startYear << " and " << endYear << "." << std::endl; } exclusiveStartKey = result.GetResult().GetLastEvaluatedKey(); if (!exclusiveStartKey.empty()) { std::cout << "Not all movies were retrieved. Scanning for more." << std::endl; } else { std::cout << "All movies were retrieved with this scan." << std::endl; } } else { std::cerr << "Failed to Scan movies: " << result.GetError().GetMessage() << std::endl; } } while (!exclusiveStartKey.empty()); } // 8. Delete a movie. (DeleteItem) { std::stringstream stringStream; stringStream << "\nWould you like to delete the movie " << title << " from the database? (y/n) "; Aws::String answer = askQuestion(stringStream.str()); if (answer == "y") { Aws::DynamoDB::Model::DeleteItemRequest request; request.AddKey(YEAR_KEY, Aws::DynamoDB::Model::AttributeValue().SetN(year)); request.AddKey(TITLE_KEY, Aws::DynamoDB::Model::AttributeValue().SetS(title)); request.SetTableName(MOVIE_TABLE_NAME); const Aws::DynamoDB::Model::DeleteItemOutcome &result = dynamoClient.DeleteItem( request); if (result.IsSuccess()) { std::cout << "\nRemoved \"" << title << "\" from the database." << std::endl; } else { std::cerr << "Failed to delete the movie: " << result.GetError().GetMessage() << std::endl; } } } return true; } //! Routine to convert a JsonView object to an attribute map. /*! \sa movieJsonViewToAttributeMap() \param jsonView: Json view object. \return map: Map that can be used in a DynamoDB request. */ Aws::Map<Aws::String, Aws::DynamoDB::Model::AttributeValue> AwsDoc::DynamoDB::movieJsonViewToAttributeMap( const Aws::Utils::Json::JsonView &jsonView) { Aws::Map<Aws::String, Aws::DynamoDB::Model::AttributeValue> result; if (jsonView.KeyExists(YEAR_KEY)) { result[YEAR_KEY].SetN(jsonView.GetInteger(YEAR_KEY)); } if (jsonView.KeyExists(TITLE_KEY)) { result[TITLE_KEY].SetS(jsonView.GetString(TITLE_KEY)); } if (jsonView.KeyExists(INFO_KEY)) { Aws::Map<Aws::String, const std::shared_ptr<Aws::DynamoDB::Model::AttributeValue>> infoMap; Aws::Utils::Json::JsonView infoView = jsonView.GetObject(INFO_KEY); if (infoView.KeyExists(RATING_KEY)) { std::shared_ptr<Aws::DynamoDB::Model::AttributeValue> attributeValue = std::make_shared<Aws::DynamoDB::Model::AttributeValue>(); attributeValue->SetN(infoView.GetDouble(RATING_KEY)); infoMap.emplace(std::make_pair(RATING_KEY, attributeValue)); } if (infoView.KeyExists(PLOT_KEY)) { std::shared_ptr<Aws::DynamoDB::Model::AttributeValue> attributeValue = std::make_shared<Aws::DynamoDB::Model::AttributeValue>(); attributeValue->SetS(infoView.GetString(PLOT_KEY)); infoMap.emplace(std::make_pair(PLOT_KEY, attributeValue)); } result[INFO_KEY].SetM(infoMap); } return result; } //! Create a DynamoDB table to be used in sample code scenarios. /*! \sa createMoviesDynamoDBTable() \param clientConfiguration: AWS client configuration. \return bool: Function succeeded. */ bool AwsDoc::DynamoDB::createMoviesDynamoDBTable( const Aws::Client::ClientConfiguration &clientConfiguration) { Aws::DynamoDB::DynamoDBClient dynamoClient(clientConfiguration); bool movieTableAlreadyExisted = false; { Aws::DynamoDB::Model::CreateTableRequest request; Aws::DynamoDB::Model::AttributeDefinition yearAttributeDefinition; yearAttributeDefinition.SetAttributeName(YEAR_KEY); yearAttributeDefinition.SetAttributeType( Aws::DynamoDB::Model::ScalarAttributeType::N); request.AddAttributeDefinitions(yearAttributeDefinition); Aws::DynamoDB::Model::AttributeDefinition titleAttributeDefinition; yearAttributeDefinition.SetAttributeName(TITLE_KEY); yearAttributeDefinition.SetAttributeType( Aws::DynamoDB::Model::ScalarAttributeType::S); request.AddAttributeDefinitions(yearAttributeDefinition); Aws::DynamoDB::Model::KeySchemaElement yearKeySchema; yearKeySchema.WithAttributeName(YEAR_KEY).WithKeyType( Aws::DynamoDB::Model::KeyType::HASH); request.AddKeySchema(yearKeySchema); Aws::DynamoDB::Model::KeySchemaElement titleKeySchema; yearKeySchema.WithAttributeName(TITLE_KEY).WithKeyType( Aws::DynamoDB::Model::KeyType::RANGE); request.AddKeySchema(yearKeySchema); Aws::DynamoDB::Model::ProvisionedThroughput throughput; throughput.WithReadCapacityUnits( PROVISIONED_THROUGHPUT_UNITS).WithWriteCapacityUnits( PROVISIONED_THROUGHPUT_UNITS); request.SetProvisionedThroughput(throughput); request.SetTableName(MOVIE_TABLE_NAME); std::cout << "Creating table '" << MOVIE_TABLE_NAME << "'..." << std::endl; const Aws::DynamoDB::Model::CreateTableOutcome &result = dynamoClient.CreateTable( request); if (!result.IsSuccess()) { if (result.GetError().GetErrorType() == Aws::DynamoDB::DynamoDBErrors::RESOURCE_IN_USE) { std::cout << "Table already exists." << std::endl; movieTableAlreadyExisted = true; } else { std::cerr << "Failed to create table: " << result.GetError().GetMessage(); return false; } } } // Wait for table to become active. if (!movieTableAlreadyExisted) { std::cout << "Waiting for table '" << MOVIE_TABLE_NAME << "' to become active...." << std::endl; if (!AwsDoc::DynamoDB::waitTableActive(MOVIE_TABLE_NAME, clientConfiguration)) { return false; } std::cout << "Table '" << MOVIE_TABLE_NAME << "' created and active." << std::endl; } return true; } //! Delete the DynamoDB table used for sample code scenarios. /*! \sa deleteMoviesDynamoDBTable() \param clientConfiguration: AWS client configuration. \return bool: Function succeeded. */ bool AwsDoc::DynamoDB::deleteMoviesDynamoDBTable( const Aws::Client::ClientConfiguration &clientConfiguration) { Aws::DynamoDB::DynamoDBClient dynamoClient(clientConfiguration); Aws::DynamoDB::Model::DeleteTableRequest request; request.SetTableName(MOVIE_TABLE_NAME); const Aws::DynamoDB::Model::DeleteTableOutcome &result = dynamoClient.DeleteTable( request); if (result.IsSuccess()) { std::cout << "Your table \"" << result.GetResult().GetTableDescription().GetTableName() << " was deleted.\n"; } else { std::cerr << "Failed to delete table: " << result.GetError().GetMessage() << std::endl; } return result.IsSuccess(); } //! Query a newly created DynamoDB table until it is active. /*! \sa waitTableActive() \param waitTableActive: The DynamoDB table's name. \param dynamoClient: A DynamoDB client. \return bool: Function succeeded. */ bool AwsDoc::DynamoDB::waitTableActive(const Aws::String &tableName, const Aws::DynamoDB::DynamoDBClient &dynamoClient) { // Repeatedly call DescribeTable until table is ACTIVE. const int MAX_QUERIES = 20; Aws::DynamoDB::Model::DescribeTableRequest request; request.SetTableName(tableName); int count = 0; while (count < MAX_QUERIES) { const Aws::DynamoDB::Model::DescribeTableOutcome &result = dynamoClient.DescribeTable( request); if (result.IsSuccess()) { Aws::DynamoDB::Model::TableStatus status = result.GetResult().GetTable().GetTableStatus(); if (Aws::DynamoDB::Model::TableStatus::ACTIVE != status) { std::this_thread::sleep_for(std::chrono::seconds(1)); } else { return true; } } else { std::cerr << "Error DynamoDB::waitTableActive " << result.GetError().GetMessage() << std::endl; return false; } count++; } return false; }
-
For API details, see the following topics in Amazon SDK for C++ API Reference.
-
- Go
-
- SDK for Go 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
. Run an interactive scenario to create the table and perform actions on it.
import ( "context" "fmt" "log" "strings" "github.com/aws/aws-sdk-go-v2/aws" "github.com/aws/aws-sdk-go-v2/service/dynamodb" "github.com/awsdocs/aws-doc-sdk-examples/gov2/demotools" "github.com/awsdocs/aws-doc-sdk-examples/gov2/dynamodb/actions" ) // RunMovieScenario is an interactive example that shows you how to use the AWS SDK for Go // to create and use an Amazon DynamoDB table that stores data about movies. // // 1. Create a table that can hold movie data. // 2. Put, get, and update a single movie in the table. // 3. Write movie data to the table from a sample JSON file. // 4. Query for movies that were released in a given year. // 5. Scan for movies that were released in a range of years. // 6. Delete a movie from the table. // 7. Delete the table. // // This example creates a DynamoDB service client from the specified sdkConfig so that // you can replace it with a mocked or stubbed config for unit testing. // // It uses a questioner from the `demotools` package to get input during the example. // This package can be found in the ..\..\demotools folder of this repo. // // The specified movie sampler is used to get sample data from a URL that is loaded // into the named table. func RunMovieScenario( ctx context.Context, sdkConfig aws.Config, questioner demotools.IQuestioner, tableName string, movieSampler actions.IMovieSampler) { defer func() { if r := recover(); r != nil { fmt.Printf("Something went wrong with the demo.") } }() log.Println(strings.Repeat("-", 88)) log.Println("Welcome to the Amazon DynamoDB getting started demo.") log.Println(strings.Repeat("-", 88)) tableBasics := actions.TableBasics{TableName: tableName, DynamoDbClient: dynamodb.NewFromConfig(sdkConfig)} exists, err := tableBasics.TableExists(ctx) if err != nil { panic(err) } if !exists { log.Printf("Creating table %v...\n", tableName) _, err = tableBasics.CreateMovieTable(ctx) if err != nil { panic(err) } else { log.Printf("Created table %v.\n", tableName) } } else { log.Printf("Table %v already exists.\n", tableName) } var customMovie actions.Movie customMovie.Title = questioner.Ask("Enter a movie title to add to the table:", demotools.NotEmpty{}) customMovie.Year = questioner.AskInt("What year was it released?", demotools.NotEmpty{}, demotools.InIntRange{Lower: 1900, Upper: 2030}) customMovie.Info = map[string]interface{}{} customMovie.Info["rating"] = questioner.AskFloat64( "Enter a rating between 1 and 10:", demotools.NotEmpty{}, demotools.InFloatRange{Lower: 1, Upper: 10}) customMovie.Info["plot"] = questioner.Ask("What's the plot? ", demotools.NotEmpty{}) err = tableBasics.AddMovie(ctx, customMovie) if err == nil { log.Printf("Added %v to the movie table.\n", customMovie.Title) } log.Println(strings.Repeat("-", 88)) log.Printf("Let's update your movie. You previously rated it %v.\n", customMovie.Info["rating"]) customMovie.Info["rating"] = questioner.AskFloat64( "What new rating would you give it?", demotools.NotEmpty{}, demotools.InFloatRange{Lower: 1, Upper: 10}) log.Printf("You summarized the plot as '%v'.\n", customMovie.Info["plot"]) customMovie.Info["plot"] = questioner.Ask("What would you say now?", demotools.NotEmpty{}) attributes, err := tableBasics.UpdateMovie(ctx, customMovie) if err == nil { log.Printf("Updated %v with new values.\n", customMovie.Title) for _, attVal := range attributes { for valKey, val := range attVal { log.Printf("\t%v: %v\n", valKey, val) } } } log.Println(strings.Repeat("-", 88)) log.Printf("Getting movie data from %v and adding 250 movies to the table...\n", movieSampler.GetURL()) movies := movieSampler.GetSampleMovies() written, err := tableBasics.AddMovieBatch(ctx, movies, 250) if err != nil { panic(err) } else { log.Printf("Added %v movies to the table.\n", written) } show := 10 if show > written { show = written } log.Printf("The first %v movies in the table are:", show) for index, movie := range movies[:show] { log.Printf("\t%v. %v\n", index+1, movie.Title) } movieIndex := questioner.AskInt( "Enter the number of a movie to get info about it: ", demotools.InIntRange{Lower: 1, Upper: show}, ) movie, err := tableBasics.GetMovie(ctx, movies[movieIndex-1].Title, movies[movieIndex-1].Year) if err == nil { log.Println(movie) } log.Println(strings.Repeat("-", 88)) log.Println("Let's get a list of movies released in a given year.") releaseYear := questioner.AskInt("Enter a year between 1972 and 2018: ", demotools.InIntRange{Lower: 1972, Upper: 2018}, ) releases, err := tableBasics.Query(ctx, releaseYear) if err == nil { if len(releases) == 0 { log.Printf("I couldn't find any movies released in %v!\n", releaseYear) } else { for _, movie = range releases { log.Println(movie) } } } log.Println(strings.Repeat("-", 88)) log.Println("Now let's scan for movies released in a range of years.") startYear := questioner.AskInt("Enter a year: ", demotools.InIntRange{Lower: 1972, Upper: 2018}) endYear := questioner.AskInt("Enter another year: ", demotools.InIntRange{Lower: 1972, Upper: 2018}) releases, err = tableBasics.Scan(ctx, startYear, endYear) if err == nil { if len(releases) == 0 { log.Printf("I couldn't find any movies released between %v and %v!\n", startYear, endYear) } else { log.Printf("Found %v movies. In this list, the plot is <nil> because "+ "we used a projection expression when scanning for items to return only "+ "the title, year, and rating.\n", len(releases)) for _, movie = range releases { log.Println(movie) } } } log.Println(strings.Repeat("-", 88)) var tables []string if questioner.AskBool("Do you want to list all of your tables? (y/n) ", "y") { tables, err = tableBasics.ListTables(ctx) if err == nil { log.Printf("Found %v tables:", len(tables)) for _, table := range tables { log.Printf("\t%v", table) } } } log.Println(strings.Repeat("-", 88)) log.Printf("Let's remove your movie '%v'.\n", customMovie.Title) if questioner.AskBool("Do you want to delete it from the table? (y/n) ", "y") { err = tableBasics.DeleteMovie(ctx, customMovie) } if err == nil { log.Printf("Deleted %v.\n", customMovie.Title) } if questioner.AskBool("Delete the table, too? (y/n)", "y") { err = tableBasics.DeleteTable(ctx) } else { log.Println("Don't forget to delete the table when you're done or you might " + "incur charges on your account.") } if err == nil { log.Printf("Deleted table %v.\n", tableBasics.TableName) } log.Println(strings.Repeat("-", 88)) log.Println("Thanks for watching!") log.Println(strings.Repeat("-", 88)) }
Define a Movie struct that is used in this example.
import ( "archive/zip" "bytes" "encoding/json" "fmt" "io" "log" "net/http" "github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue" "github.com/aws/aws-sdk-go-v2/service/dynamodb/types" ) // Movie encapsulates data about a movie. Title and Year are the composite primary key // of the movie in Amazon DynamoDB. Title is the sort key, Year is the partition key, // and Info is additional data. type Movie struct { Title string `dynamodbav:"title"` Year int `dynamodbav:"year"` Info map[string]interface{} `dynamodbav:"info"` } // GetKey returns the composite primary key of the movie in a format that can be // sent to DynamoDB. func (movie Movie) GetKey() map[string]types.AttributeValue { title, err := attributevalue.Marshal(movie.Title) if err != nil { panic(err) } year, err := attributevalue.Marshal(movie.Year) if err != nil { panic(err) } return map[string]types.AttributeValue{"title": title, "year": year} } // String returns the title, year, rating, and plot of a movie, formatted for the example. func (movie Movie) String() string { return fmt.Sprintf("%v\n\tReleased: %v\n\tRating: %v\n\tPlot: %v\n", movie.Title, movie.Year, movie.Info["rating"], movie.Info["plot"]) }
Create a struct and methods that call DynamoDB actions.
import ( "context" "errors" "log" "time" "github.com/aws/aws-sdk-go-v2/aws" "github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue" "github.com/aws/aws-sdk-go-v2/feature/dynamodb/expression" "github.com/aws/aws-sdk-go-v2/service/dynamodb" "github.com/aws/aws-sdk-go-v2/service/dynamodb/types" ) // TableBasics encapsulates the Amazon DynamoDB service actions used in the examples. // It contains a DynamoDB service client that is used to act on the specified table. type TableBasics struct { DynamoDbClient *dynamodb.Client TableName string } // TableExists determines whether a DynamoDB table exists. func (basics TableBasics) TableExists(ctx context.Context) (bool, error) { exists := true _, err := basics.DynamoDbClient.DescribeTable( ctx, &dynamodb.DescribeTableInput{TableName: aws.String(basics.TableName)}, ) if err != nil { var notFoundEx *types.ResourceNotFoundException if errors.As(err, ¬FoundEx) { log.Printf("Table %v does not exist.\n", basics.TableName) err = nil } else { log.Printf("Couldn't determine existence of table %v. Here's why: %v\n", basics.TableName, err) } exists = false } return exists, err } // CreateMovieTable creates a DynamoDB table with a composite primary key defined as // a string sort key named `title`, and a numeric partition key named `year`. // This function uses NewTableExistsWaiter to wait for the table to be created by // DynamoDB before it returns. func (basics TableBasics) CreateMovieTable(ctx context.Context) (*types.TableDescription, error) { var tableDesc *types.TableDescription table, err := basics.DynamoDbClient.CreateTable(ctx, &dynamodb.CreateTableInput{ AttributeDefinitions: []types.AttributeDefinition{{ AttributeName: aws.String("year"), AttributeType: types.ScalarAttributeTypeN, }, { AttributeName: aws.String("title"), AttributeType: types.ScalarAttributeTypeS, }}, KeySchema: []types.KeySchemaElement{{ AttributeName: aws.String("year"), KeyType: types.KeyTypeHash, }, { AttributeName: aws.String("title"), KeyType: types.KeyTypeRange, }}, TableName: aws.String(basics.TableName), ProvisionedThroughput: &types.ProvisionedThroughput{ ReadCapacityUnits: aws.Int64(10), WriteCapacityUnits: aws.Int64(10), }, }) if err != nil { log.Printf("Couldn't create table %v. Here's why: %v\n", basics.TableName, err) } else { waiter := dynamodb.NewTableExistsWaiter(basics.DynamoDbClient) err = waiter.Wait(ctx, &dynamodb.DescribeTableInput{ TableName: aws.String(basics.TableName)}, 5*time.Minute) if err != nil { log.Printf("Wait for table exists failed. Here's why: %v\n", err) } tableDesc = table.TableDescription } return tableDesc, err } // ListTables lists the DynamoDB table names for the current account. func (basics TableBasics) ListTables(ctx context.Context) ([]string, error) { var tableNames []string var output *dynamodb.ListTablesOutput var err error tablePaginator := dynamodb.NewListTablesPaginator(basics.DynamoDbClient, &dynamodb.ListTablesInput{}) for tablePaginator.HasMorePages() { output, err = tablePaginator.NextPage(ctx) if err != nil { log.Printf("Couldn't list tables. Here's why: %v\n", err) break } else { tableNames = append(tableNames, output.TableNames...) } } return tableNames, err } // AddMovie adds a movie the DynamoDB table. func (basics TableBasics) AddMovie(ctx context.Context, movie Movie) error { item, err := attributevalue.MarshalMap(movie) if err != nil { panic(err) } _, err = basics.DynamoDbClient.PutItem(ctx, &dynamodb.PutItemInput{ TableName: aws.String(basics.TableName), Item: item, }) if err != nil { log.Printf("Couldn't add item to table. Here's why: %v\n", err) } return err } // UpdateMovie updates the rating and plot of a movie that already exists in the // DynamoDB table. This function uses the `expression` package to build the update // expression. func (basics TableBasics) UpdateMovie(ctx context.Context, movie Movie) (map[string]map[string]interface{}, error) { var err error var response *dynamodb.UpdateItemOutput var attributeMap map[string]map[string]interface{} update := expression.Set(expression.Name("info.rating"), expression.Value(movie.Info["rating"])) update.Set(expression.Name("info.plot"), expression.Value(movie.Info["plot"])) expr, err := expression.NewBuilder().WithUpdate(update).Build() if err != nil { log.Printf("Couldn't build expression for update. Here's why: %v\n", err) } else { response, err = basics.DynamoDbClient.UpdateItem(ctx, &dynamodb.UpdateItemInput{ TableName: aws.String(basics.TableName), Key: movie.GetKey(), ExpressionAttributeNames: expr.Names(), ExpressionAttributeValues: expr.Values(), UpdateExpression: expr.Update(), ReturnValues: types.ReturnValueUpdatedNew, }) if err != nil { log.Printf("Couldn't update movie %v. Here's why: %v\n", movie.Title, err) } else { err = attributevalue.UnmarshalMap(response.Attributes, &attributeMap) if err != nil { log.Printf("Couldn't unmarshall update response. Here's why: %v\n", err) } } } return attributeMap, err } // AddMovieBatch adds a slice of movies to the DynamoDB table. The function sends // batches of 25 movies to DynamoDB until all movies are added or it reaches the // specified maximum. func (basics TableBasics) AddMovieBatch(ctx context.Context, movies []Movie, maxMovies int) (int, error) { var err error var item map[string]types.AttributeValue written := 0 batchSize := 25 // DynamoDB allows a maximum batch size of 25 items. start := 0 end := start + batchSize for start < maxMovies && start < len(movies) { var writeReqs []types.WriteRequest if end > len(movies) { end = len(movies) } for _, movie := range movies[start:end] { item, err = attributevalue.MarshalMap(movie) if err != nil { log.Printf("Couldn't marshal movie %v for batch writing. Here's why: %v\n", movie.Title, err) } else { writeReqs = append( writeReqs, types.WriteRequest{PutRequest: &types.PutRequest{Item: item}}, ) } } _, err = basics.DynamoDbClient.BatchWriteItem(ctx, &dynamodb.BatchWriteItemInput{ RequestItems: map[string][]types.WriteRequest{basics.TableName: writeReqs}}) if err != nil { log.Printf("Couldn't add a batch of movies to %v. Here's why: %v\n", basics.TableName, err) } else { written += len(writeReqs) } start = end end += batchSize } return written, err } // GetMovie gets movie data from the DynamoDB table by using the primary composite key // made of title and year. func (basics TableBasics) GetMovie(ctx context.Context, title string, year int) (Movie, error) { movie := Movie{Title: title, Year: year} response, err := basics.DynamoDbClient.GetItem(ctx, &dynamodb.GetItemInput{ Key: movie.GetKey(), TableName: aws.String(basics.TableName), }) if err != nil { log.Printf("Couldn't get info about %v. Here's why: %v\n", title, err) } else { err = attributevalue.UnmarshalMap(response.Item, &movie) if err != nil { log.Printf("Couldn't unmarshal response. Here's why: %v\n", err) } } return movie, err } // Query gets all movies in the DynamoDB table that were released in the specified year. // The function uses the `expression` package to build the key condition expression // that is used in the query. func (basics TableBasics) Query(ctx context.Context, releaseYear int) ([]Movie, error) { var err error var response *dynamodb.QueryOutput var movies []Movie keyEx := expression.Key("year").Equal(expression.Value(releaseYear)) expr, err := expression.NewBuilder().WithKeyCondition(keyEx).Build() if err != nil { log.Printf("Couldn't build expression for query. Here's why: %v\n", err) } else { queryPaginator := dynamodb.NewQueryPaginator(basics.DynamoDbClient, &dynamodb.QueryInput{ TableName: aws.String(basics.TableName), ExpressionAttributeNames: expr.Names(), ExpressionAttributeValues: expr.Values(), KeyConditionExpression: expr.KeyCondition(), }) for queryPaginator.HasMorePages() { response, err = queryPaginator.NextPage(ctx) if err != nil { log.Printf("Couldn't query for movies released in %v. Here's why: %v\n", releaseYear, err) break } else { var moviePage []Movie err = attributevalue.UnmarshalListOfMaps(response.Items, &moviePage) if err != nil { log.Printf("Couldn't unmarshal query response. Here's why: %v\n", err) break } else { movies = append(movies, moviePage...) } } } } return movies, err } // Scan gets all movies in the DynamoDB table that were released in a range of years // and projects them to return a reduced set of fields. // The function uses the `expression` package to build the filter and projection // expressions. func (basics TableBasics) Scan(ctx context.Context, startYear int, endYear int) ([]Movie, error) { var movies []Movie var err error var response *dynamodb.ScanOutput filtEx := expression.Name("year").Between(expression.Value(startYear), expression.Value(endYear)) projEx := expression.NamesList( expression.Name("year"), expression.Name("title"), expression.Name("info.rating")) expr, err := expression.NewBuilder().WithFilter(filtEx).WithProjection(projEx).Build() if err != nil { log.Printf("Couldn't build expressions for scan. Here's why: %v\n", err) } else { scanPaginator := dynamodb.NewScanPaginator(basics.DynamoDbClient, &dynamodb.ScanInput{ TableName: aws.String(basics.TableName), ExpressionAttributeNames: expr.Names(), ExpressionAttributeValues: expr.Values(), FilterExpression: expr.Filter(), ProjectionExpression: expr.Projection(), }) for scanPaginator.HasMorePages() { response, err = scanPaginator.NextPage(ctx) if err != nil { log.Printf("Couldn't scan for movies released between %v and %v. Here's why: %v\n", startYear, endYear, err) break } else { var moviePage []Movie err = attributevalue.UnmarshalListOfMaps(response.Items, &moviePage) if err != nil { log.Printf("Couldn't unmarshal query response. Here's why: %v\n", err) break } else { movies = append(movies, moviePage...) } } } } return movies, err } // DeleteMovie removes a movie from the DynamoDB table. func (basics TableBasics) DeleteMovie(ctx context.Context, movie Movie) error { _, err := basics.DynamoDbClient.DeleteItem(ctx, &dynamodb.DeleteItemInput{ TableName: aws.String(basics.TableName), Key: movie.GetKey(), }) if err != nil { log.Printf("Couldn't delete %v from the table. Here's why: %v\n", movie.Title, err) } return err } // DeleteTable deletes the DynamoDB table and all of its data. func (basics TableBasics) DeleteTable(ctx context.Context) error { _, err := basics.DynamoDbClient.DeleteTable(ctx, &dynamodb.DeleteTableInput{ TableName: aws.String(basics.TableName)}) if err != nil { log.Printf("Couldn't delete table %v. Here's why: %v\n", basics.TableName, err) } return err }
-
For API details, see the following topics in Amazon SDK for Go API 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
. Create a DynamoDB table.
// Create a table with a Sort key. public static void createTable(DynamoDbClient ddb, String tableName) { DynamoDbWaiter dbWaiter = ddb.waiter(); ArrayList<AttributeDefinition> attributeDefinitions = new ArrayList<>(); // Define attributes. attributeDefinitions.add(AttributeDefinition.builder() .attributeName("year") .attributeType("N") .build()); attributeDefinitions.add(AttributeDefinition.builder() .attributeName("title") .attributeType("S") .build()); ArrayList<KeySchemaElement> tableKey = new ArrayList<>(); KeySchemaElement key = KeySchemaElement.builder() .attributeName("year") .keyType(KeyType.HASH) .build(); KeySchemaElement key2 = KeySchemaElement.builder() .attributeName("title") .keyType(KeyType.RANGE) .build(); // Add KeySchemaElement objects to the list. tableKey.add(key); tableKey.add(key2); CreateTableRequest request = CreateTableRequest.builder() .keySchema(tableKey) .provisionedThroughput(ProvisionedThroughput.builder() .readCapacityUnits(10L) .writeCapacityUnits(10L) .build()) .attributeDefinitions(attributeDefinitions) .tableName(tableName) .build(); try { CreateTableResponse response = ddb.createTable(request); DescribeTableRequest tableRequest = DescribeTableRequest.builder() .tableName(tableName) .build(); // Wait until the Amazon DynamoDB table is created. WaiterResponse<DescribeTableResponse> waiterResponse = dbWaiter.waitUntilTableExists(tableRequest); waiterResponse.matched().response().ifPresent(System.out::println); String newTable = response.tableDescription().tableName(); System.out.println("The " + newTable + " was successfully created."); } catch (DynamoDbException e) { System.err.println(e.getMessage()); System.exit(1); } }
Create a helper function to download and extract the sample JSON file.
// Load data into the table. public static void loadData(DynamoDbClient ddb, String tableName, String fileName) throws IOException { DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder() .dynamoDbClient(ddb) .build(); DynamoDbTable<Movies> mappedTable = enhancedClient.table("Movies", TableSchema.fromBean(Movies.class)); JsonParser parser = new JsonFactory().createParser(new File(fileName)); com.fasterxml.jackson.databind.JsonNode rootNode = new ObjectMapper().readTree(parser); Iterator<JsonNode> iter = rootNode.iterator(); ObjectNode currentNode; int t = 0; while (iter.hasNext()) { // Only add 200 Movies to the table. if (t == 200) break; currentNode = (ObjectNode) iter.next(); int year = currentNode.path("year").asInt(); String title = currentNode.path("title").asText(); String info = currentNode.path("info").toString(); Movies movies = new Movies(); movies.setYear(year); movies.setTitle(title); movies.setInfo(info); // Put the data into the Amazon DynamoDB Movie table. mappedTable.putItem(movies); t++; } }
Get an item from a table.
public static void getItem(DynamoDbClient ddb) { HashMap<String, AttributeValue> keyToGet = new HashMap<>(); keyToGet.put("year", AttributeValue.builder() .n("1933") .build()); keyToGet.put("title", AttributeValue.builder() .s("King Kong") .build()); GetItemRequest request = GetItemRequest.builder() .key(keyToGet) .tableName("Movies") .build(); try { Map<String, AttributeValue> returnedItem = ddb.getItem(request).item(); if (returnedItem != null) { Set<String> keys = returnedItem.keySet(); System.out.println("Amazon DynamoDB table attributes: \n"); for (String key1 : keys) { System.out.format("%s: %s\n", key1, returnedItem.get(key1).toString()); } } else { System.out.format("No item found with the key %s!\n", "year"); } } catch (DynamoDbException e) { System.err.println(e.getMessage()); System.exit(1); } }
Full example.
/** * 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 * * This Java example performs these tasks: * * 1. Creates the Amazon DynamoDB Movie table with partition and sort key. * 2. Puts data into the Amazon DynamoDB table from a JSON document using the * Enhanced client. * 3. Gets data from the Movie table. * 4. Adds a new item. * 5. Updates an item. * 6. Uses a Scan to query items using the Enhanced client. * 7. Queries all items where the year is 2013 using the Enhanced Client. * 8. Deletes the table. */ public class Scenario { public static final String DASHES = new String(new char[80]).replace("\0", "-"); public static void main(String[] args) throws IOException { final String usage = """ Usage: <fileName> Where: fileName - The path to the moviedata.json file that you can download from the Amazon DynamoDB Developer Guide. """; if (args.length != 1) { System.out.println(usage); System.exit(1); } String tableName = "Movies"; String fileName = args[0]; Region region = Region.US_EAST_1; DynamoDbClient ddb = DynamoDbClient.builder() .region(region) .build(); System.out.println(DASHES); System.out.println("Welcome to the Amazon DynamoDB example scenario."); System.out.println(DASHES); System.out.println(DASHES); System.out.println( "1. Creating an Amazon DynamoDB table named Movies with a key named year and a sort key named title."); createTable(ddb, tableName); System.out.println(DASHES); System.out.println(DASHES); System.out.println("2. Loading data into the Amazon DynamoDB table."); loadData(ddb, tableName, fileName); System.out.println(DASHES); System.out.println(DASHES); System.out.println("3. Getting data from the Movie table."); getItem(ddb); System.out.println(DASHES); System.out.println(DASHES); System.out.println("4. Putting a record into the Amazon DynamoDB table."); putRecord(ddb); System.out.println(DASHES); System.out.println(DASHES); System.out.println("5. Updating a record."); updateTableItem(ddb, tableName); System.out.println(DASHES); System.out.println(DASHES); System.out.println("6. Scanning the Amazon DynamoDB table."); scanMovies(ddb, tableName); System.out.println(DASHES); System.out.println(DASHES); System.out.println("7. Querying the Movies released in 2013."); queryTable(ddb); System.out.println(DASHES); System.out.println(DASHES); System.out.println("8. Deleting the Amazon DynamoDB table."); deleteDynamoDBTable(ddb, tableName); System.out.println(DASHES); ddb.close(); } // Create a table with a Sort key. public static void createTable(DynamoDbClient ddb, String tableName) { DynamoDbWaiter dbWaiter = ddb.waiter(); ArrayList<AttributeDefinition> attributeDefinitions = new ArrayList<>(); // Define attributes. attributeDefinitions.add(AttributeDefinition.builder() .attributeName("year") .attributeType("N") .build()); attributeDefinitions.add(AttributeDefinition.builder() .attributeName("title") .attributeType("S") .build()); ArrayList<KeySchemaElement> tableKey = new ArrayList<>(); KeySchemaElement key = KeySchemaElement.builder() .attributeName("year") .keyType(KeyType.HASH) .build(); KeySchemaElement key2 = KeySchemaElement.builder() .attributeName("title") .keyType(KeyType.RANGE) .build(); // Add KeySchemaElement objects to the list. tableKey.add(key); tableKey.add(key2); CreateTableRequest request = CreateTableRequest.builder() .keySchema(tableKey) .provisionedThroughput(ProvisionedThroughput.builder() .readCapacityUnits(10L) .writeCapacityUnits(10L) .build()) .attributeDefinitions(attributeDefinitions) .tableName(tableName) .build(); try { CreateTableResponse response = ddb.createTable(request); DescribeTableRequest tableRequest = DescribeTableRequest.builder() .tableName(tableName) .build(); // Wait until the Amazon DynamoDB table is created. WaiterResponse<DescribeTableResponse> waiterResponse = dbWaiter.waitUntilTableExists(tableRequest); waiterResponse.matched().response().ifPresent(System.out::println); String newTable = response.tableDescription().tableName(); System.out.println("The " + newTable + " was successfully created."); } catch (DynamoDbException e) { System.err.println(e.getMessage()); System.exit(1); } } // Query the table. public static void queryTable(DynamoDbClient ddb) { try { DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder() .dynamoDbClient(ddb) .build(); DynamoDbTable<Movies> custTable = enhancedClient.table("Movies", TableSchema.fromBean(Movies.class)); QueryConditional queryConditional = QueryConditional .keyEqualTo(Key.builder() .partitionValue(2013) .build()); // Get items in the table and write out the ID value. Iterator<Movies> results = custTable.query(queryConditional).items().iterator(); String result = ""; while (results.hasNext()) { Movies rec = results.next(); System.out.println("The title of the movie is " + rec.getTitle()); System.out.println("The movie information is " + rec.getInfo()); } } catch (DynamoDbException e) { System.err.println(e.getMessage()); System.exit(1); } } // Scan the table. public static void scanMovies(DynamoDbClient ddb, String tableName) { System.out.println("******* Scanning all movies.\n"); try { DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder() .dynamoDbClient(ddb) .build(); DynamoDbTable<Movies> custTable = enhancedClient.table("Movies", TableSchema.fromBean(Movies.class)); Iterator<Movies> results = custTable.scan().items().iterator(); while (results.hasNext()) { Movies rec = results.next(); System.out.println("The movie title is " + rec.getTitle()); System.out.println("The movie year is " + rec.getYear()); } } catch (DynamoDbException e) { System.err.println(e.getMessage()); System.exit(1); } } // Load data into the table. public static void loadData(DynamoDbClient ddb, String tableName, String fileName) throws IOException { DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder() .dynamoDbClient(ddb) .build(); DynamoDbTable<Movies> mappedTable = enhancedClient.table("Movies", TableSchema.fromBean(Movies.class)); JsonParser parser = new JsonFactory().createParser(new File(fileName)); com.fasterxml.jackson.databind.JsonNode rootNode = new ObjectMapper().readTree(parser); Iterator<JsonNode> iter = rootNode.iterator(); ObjectNode currentNode; int t = 0; while (iter.hasNext()) { // Only add 200 Movies to the table. if (t == 200) break; currentNode = (ObjectNode) iter.next(); int year = currentNode.path("year").asInt(); String title = currentNode.path("title").asText(); String info = currentNode.path("info").toString(); Movies movies = new Movies(); movies.setYear(year); movies.setTitle(title); movies.setInfo(info); // Put the data into the Amazon DynamoDB Movie table. mappedTable.putItem(movies); t++; } } // Update the record to include show only directors. public static void updateTableItem(DynamoDbClient ddb, String tableName) { HashMap<String, AttributeValue> itemKey = new HashMap<>(); itemKey.put("year", AttributeValue.builder().n("1933").build()); itemKey.put("title", AttributeValue.builder().s("King Kong").build()); HashMap<String, AttributeValueUpdate> updatedValues = new HashMap<>(); updatedValues.put("info", AttributeValueUpdate.builder() .value(AttributeValue.builder().s("{\"directors\":[\"Merian C. Cooper\",\"Ernest B. Schoedsack\"]") .build()) .action(AttributeAction.PUT) .build()); UpdateItemRequest request = UpdateItemRequest.builder() .tableName(tableName) .key(itemKey) .attributeUpdates(updatedValues) .build(); try { ddb.updateItem(request); } catch (ResourceNotFoundException e) { System.err.println(e.getMessage()); System.exit(1); } catch (DynamoDbException e) { System.err.println(e.getMessage()); System.exit(1); } System.out.println("Item was updated!"); } public static void deleteDynamoDBTable(DynamoDbClient ddb, String tableName) { DeleteTableRequest request = DeleteTableRequest.builder() .tableName(tableName) .build(); try { ddb.deleteTable(request); } catch (DynamoDbException e) { System.err.println(e.getMessage()); System.exit(1); } System.out.println(tableName + " was successfully deleted!"); } public static void putRecord(DynamoDbClient ddb) { try { DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder() .dynamoDbClient(ddb) .build(); DynamoDbTable<Movies> table = enhancedClient.table("Movies", TableSchema.fromBean(Movies.class)); // Populate the Table. Movies record = new Movies(); record.setYear(2020); record.setTitle("My Movie2"); record.setInfo("no info"); table.putItem(record); } catch (DynamoDbException e) { System.err.println(e.getMessage()); System.exit(1); } System.out.println("Added a new movie to the table."); } public static void getItem(DynamoDbClient ddb) { HashMap<String, AttributeValue> keyToGet = new HashMap<>(); keyToGet.put("year", AttributeValue.builder() .n("1933") .build()); keyToGet.put("title", AttributeValue.builder() .s("King Kong") .build()); GetItemRequest request = GetItemRequest.builder() .key(keyToGet) .tableName("Movies") .build(); try { Map<String, AttributeValue> returnedItem = ddb.getItem(request).item(); if (returnedItem != null) { Set<String> keys = returnedItem.keySet(); System.out.println("Amazon DynamoDB table attributes: \n"); for (String key1 : keys) { System.out.format("%s: %s\n", key1, returnedItem.get(key1).toString()); } } else { System.out.format("No item found with the key %s!\n", "year"); } } catch (DynamoDbException e) { System.err.println(e.getMessage()); System.exit(1); } } }
-
For API details, see the following topics 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
. import { readFileSync } from "node:fs"; import { BillingMode, CreateTableCommand, DeleteTableCommand, DynamoDBClient, waitUntilTableExists, } from "@aws-sdk/client-dynamodb"; /** * This module is a convenience library. It abstracts Amazon DynamoDB's data type * descriptors (such as S, N, B, and BOOL) by marshalling JavaScript objects into * AttributeValue shapes. */ import { BatchWriteCommand, DeleteCommand, DynamoDBDocumentClient, GetCommand, PutCommand, UpdateCommand, paginateQuery, paginateScan, } from "@aws-sdk/lib-dynamodb"; // These modules are local to our GitHub repository. We recommend cloning // the project from GitHub if you want to run this example. // For more information, see https://github.com/awsdocs/aws-doc-sdk-examples. import { getUniqueName } from "@aws-doc-sdk-examples/lib/utils/util-string.js"; import { dirnameFromMetaUrl } from "@aws-doc-sdk-examples/lib/utils/util-fs.js"; import { chunkArray } from "@aws-doc-sdk-examples/lib/utils/util-array.js"; const dirname = dirnameFromMetaUrl(import.meta.url); const tableName = getUniqueName("Movies"); const client = new DynamoDBClient({}); const docClient = DynamoDBDocumentClient.from(client); const log = (msg) => console.log(`[SCENARIO] ${msg}`); export const main = async () => { /** * Create a table. */ const createTableCommand = new CreateTableCommand({ TableName: tableName, // This example performs a large write to the database. // Set the billing mode to PAY_PER_REQUEST to // avoid throttling the large write. BillingMode: BillingMode.PAY_PER_REQUEST, // Define the attributes that are necessary for the key schema. AttributeDefinitions: [ { AttributeName: "year", // 'N' is a data type descriptor that represents a number type. // For a list of all data type descriptors, see the following link. // https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Programming.LowLevelAPI.html#Programming.LowLevelAPI.DataTypeDescriptors AttributeType: "N", }, { AttributeName: "title", AttributeType: "S" }, ], // The KeySchema defines the primary key. The primary key can be // a partition key, or a combination of a partition key and a sort key. // Key schema design is important. For more info, see // https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/best-practices.html KeySchema: [ // The way your data is accessed determines how you structure your keys. // The movies table will be queried for movies by year. It makes sense // to make year our partition (HASH) key. { AttributeName: "year", KeyType: "HASH" }, { AttributeName: "title", KeyType: "RANGE" }, ], }); log("Creating a table."); const createTableResponse = await client.send(createTableCommand); log(`Table created: ${JSON.stringify(createTableResponse.TableDescription)}`); // This polls with DescribeTableCommand until the requested table is 'ACTIVE'. // You can't write to a table before it's active. log("Waiting for the table to be active."); await waitUntilTableExists({ client }, { TableName: tableName }); log("Table active."); /** * Add a movie to the table. */ log("Adding a single movie to the table."); // PutCommand is the first example usage of 'lib-dynamodb'. const putCommand = new PutCommand({ TableName: tableName, Item: { // In 'client-dynamodb', the AttributeValue would be required (`year: { N: 1981 }`) // 'lib-dynamodb' simplifies the usage ( `year: 1981` ) year: 1981, // The preceding KeySchema defines 'title' as our sort (RANGE) key, so 'title' // is required. title: "The Evil Dead", // Every other attribute is optional. info: { genres: ["Horror"], }, }, }); await docClient.send(putCommand); log("The movie was added."); /** * Get a movie from the table. */ log("Getting a single movie from the table."); const getCommand = new GetCommand({ TableName: tableName, // Requires the complete primary key. For the movies table, the primary key // is only the id (partition key). Key: { year: 1981, title: "The Evil Dead", }, // Set this to make sure that recent writes are reflected. // For more information, see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadConsistency.html. ConsistentRead: true, }); const getResponse = await docClient.send(getCommand); log(`Got the movie: ${JSON.stringify(getResponse.Item)}`); /** * Update a movie in the table. */ log("Updating a single movie in the table."); const updateCommand = new UpdateCommand({ TableName: tableName, Key: { year: 1981, title: "The Evil Dead" }, // This update expression appends "Comedy" to the list of genres. // For more information on update expressions, see // https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html UpdateExpression: "set #i.#g = list_append(#i.#g, :vals)", ExpressionAttributeNames: { "#i": "info", "#g": "genres" }, ExpressionAttributeValues: { ":vals": ["Comedy"], }, ReturnValues: "ALL_NEW", }); const updateResponse = await docClient.send(updateCommand); log(`Movie updated: ${JSON.stringify(updateResponse.Attributes)}`); /** * Delete a movie from the table. */ log("Deleting a single movie from the table."); const deleteCommand = new DeleteCommand({ TableName: tableName, Key: { year: 1981, title: "The Evil Dead" }, }); await client.send(deleteCommand); log("Movie deleted."); /** * Upload a batch of movies. */ log("Adding movies from local JSON file."); const file = readFileSync( `${dirname}../../../../resources/sample_files/movies.json`, ); const movies = JSON.parse(file.toString()); // chunkArray is a local convenience function. It takes an array and returns // a generator function. The generator function yields every N items. const movieChunks = chunkArray(movies, 25); // For every chunk of 25 movies, make one BatchWrite request. for (const chunk of movieChunks) { const putRequests = chunk.map((movie) => ({ PutRequest: { Item: movie, }, })); const command = new BatchWriteCommand({ RequestItems: { [tableName]: putRequests, }, }); await docClient.send(command); } log("Movies added."); /** * Query for movies by year. */ log("Querying for all movies from 1981."); const paginatedQuery = paginateQuery( { client: docClient }, { TableName: tableName, //For more information about query expressions, see // https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html#Query.KeyConditionExpressions KeyConditionExpression: "#y = :y", // 'year' is a reserved word in DynamoDB. Indicate that it's an attribute // name by using an expression attribute name. ExpressionAttributeNames: { "#y": "year" }, ExpressionAttributeValues: { ":y": 1981 }, ConsistentRead: true, }, ); /** * @type { Record<string, any>[] }; */ const movies1981 = []; for await (const page of paginatedQuery) { movies1981.push(...page.Items); } log(`Movies: ${movies1981.map((m) => m.title).join(", ")}`); /** * Scan the table for movies between 1980 and 1990. */ log("Scan for movies released between 1980 and 1990"); // A 'Scan' operation always reads every item in the table. If your design requires // the use of 'Scan', consider indexing your table or changing your design. // https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-query-scan.html const paginatedScan = paginateScan( { client: docClient }, { TableName: tableName, // Scan uses a filter expression instead of a key condition expression. Scan will // read the entire table and then apply the filter. FilterExpression: "#y between :y1 and :y2", ExpressionAttributeNames: { "#y": "year" }, ExpressionAttributeValues: { ":y1": 1980, ":y2": 1990 }, ConsistentRead: true, }, ); /** * @type { Record<string, any>[] }; */ const movies1980to1990 = []; for await (const page of paginatedScan) { movies1980to1990.push(...page.Items); } log( `Movies: ${movies1980to1990 .map((m) => `${m.title} (${m.year})`) .join(", ")}`, ); /** * Delete the table. */ const deleteTableCommand = new DeleteTableCommand({ TableName: tableName }); log(`Deleting table ${tableName}.`); await client.send(deleteTableCommand); log("Table deleted."); };
-
For API details, see the following topics in Amazon SDK for JavaScript API Reference.
-
- Kotlin
-
- SDK for Kotlin
-
Note
There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository
. Create a DynamoDB table.
suspend fun createScenarioTable( tableNameVal: String, key: String, ) { val attDef = AttributeDefinition { attributeName = key attributeType = ScalarAttributeType.N } val attDef1 = AttributeDefinition { attributeName = "title" attributeType = ScalarAttributeType.S } val keySchemaVal = KeySchemaElement { attributeName = key keyType = KeyType.Hash } val keySchemaVal1 = KeySchemaElement { attributeName = "title" keyType = KeyType.Range } val provisionedVal = ProvisionedThroughput { readCapacityUnits = 10 writeCapacityUnits = 10 } val request = CreateTableRequest { attributeDefinitions = listOf(attDef, attDef1) keySchema = listOf(keySchemaVal, keySchemaVal1) provisionedThroughput = provisionedVal tableName = tableNameVal } DynamoDbClient { region = "us-east-1" }.use { ddb -> val response = ddb.createTable(request) ddb.waitUntilTableExists { // suspend call tableName = tableNameVal } println("The table was successfully created ${response.tableDescription?.tableArn}") } }
Create a helper function to download and extract the sample JSON file.
// Load data into the table. suspend fun loadData( tableName: String, fileName: String, ) { val parser = JsonFactory().createParser(File(fileName)) val rootNode = ObjectMapper().readTree<JsonNode>(parser) val iter: Iterator<JsonNode> = rootNode.iterator() var currentNode: ObjectNode var t = 0 while (iter.hasNext()) { if (t == 50) { break } currentNode = iter.next() as ObjectNode val year = currentNode.path("year").asInt() val title = currentNode.path("title").asText() val info = currentNode.path("info").toString() putMovie(tableName, year, title, info) t++ } } suspend fun putMovie( tableNameVal: String, year: Int, title: String, info: String, ) { val itemValues = mutableMapOf<String, AttributeValue>() val strVal = year.toString() // Add all content to the table. itemValues["year"] = AttributeValue.N(strVal) itemValues["title"] = AttributeValue.S(title) itemValues["info"] = AttributeValue.S(info) val request = PutItemRequest { tableName = tableNameVal item = itemValues } DynamoDbClient { region = "us-east-1" }.use { ddb -> ddb.putItem(request) println("Added $title to the Movie table.") } }
Get an item from a table.
suspend fun getMovie( tableNameVal: String, keyName: String, keyVal: String, ) { val keyToGet = mutableMapOf<String, AttributeValue>() keyToGet[keyName] = AttributeValue.N(keyVal) keyToGet["title"] = AttributeValue.S("King Kong") val request = GetItemRequest { key = keyToGet tableName = tableNameVal } DynamoDbClient { region = "us-east-1" }.use { ddb -> val returnedItem = ddb.getItem(request) val numbersMap = returnedItem.item numbersMap?.forEach { key1 -> println(key1.key) println(key1.value) } } }
Full example.
suspend fun main(args: Array<String>) { val usage = """ Usage: <fileName> Where: fileName - The path to the moviedata.json you can download from the Amazon DynamoDB Developer Guide. """ if (args.size != 1) { println(usage) exitProcess(1) } // Get the moviedata.json from the Amazon DynamoDB Developer Guide. val tableName = "Movies" val fileName = args[0] val partitionAlias = "#a" println("Creating an Amazon DynamoDB table named Movies with a key named id and a sort key named title.") createScenarioTable(tableName, "year") loadData(tableName, fileName) getMovie(tableName, "year", "1933") scanMovies(tableName) val count = queryMovieTable(tableName, "year", partitionAlias) println("There are $count Movies released in 2013.") deletIssuesTable(tableName) } suspend fun createScenarioTable( tableNameVal: String, key: String, ) { val attDef = AttributeDefinition { attributeName = key attributeType = ScalarAttributeType.N } val attDef1 = AttributeDefinition { attributeName = "title" attributeType = ScalarAttributeType.S } val keySchemaVal = KeySchemaElement { attributeName = key keyType = KeyType.Hash } val keySchemaVal1 = KeySchemaElement { attributeName = "title" keyType = KeyType.Range } val provisionedVal = ProvisionedThroughput { readCapacityUnits = 10 writeCapacityUnits = 10 } val request = CreateTableRequest { attributeDefinitions = listOf(attDef, attDef1) keySchema = listOf(keySchemaVal, keySchemaVal1) provisionedThroughput = provisionedVal tableName = tableNameVal } DynamoDbClient { region = "us-east-1" }.use { ddb -> val response = ddb.createTable(request) ddb.waitUntilTableExists { // suspend call tableName = tableNameVal } println("The table was successfully created ${response.tableDescription?.tableArn}") } } // Load data into the table. suspend fun loadData( tableName: String, fileName: String, ) { val parser = JsonFactory().createParser(File(fileName)) val rootNode = ObjectMapper().readTree<JsonNode>(parser) val iter: Iterator<JsonNode> = rootNode.iterator() var currentNode: ObjectNode var t = 0 while (iter.hasNext()) { if (t == 50) { break } currentNode = iter.next() as ObjectNode val year = currentNode.path("year").asInt() val title = currentNode.path("title").asText() val info = currentNode.path("info").toString() putMovie(tableName, year, title, info) t++ } } suspend fun putMovie( tableNameVal: String, year: Int, title: String, info: String, ) { val itemValues = mutableMapOf<String, AttributeValue>() val strVal = year.toString() // Add all content to the table. itemValues["year"] = AttributeValue.N(strVal) itemValues["title"] = AttributeValue.S(title) itemValues["info"] = AttributeValue.S(info) val request = PutItemRequest { tableName = tableNameVal item = itemValues } DynamoDbClient { region = "us-east-1" }.use { ddb -> ddb.putItem(request) println("Added $title to the Movie table.") } } suspend fun getMovie( tableNameVal: String, keyName: String, keyVal: String, ) { val keyToGet = mutableMapOf<String, AttributeValue>() keyToGet[keyName] = AttributeValue.N(keyVal) keyToGet["title"] = AttributeValue.S("King Kong") val request = GetItemRequest { key = keyToGet tableName = tableNameVal } DynamoDbClient { region = "us-east-1" }.use { ddb -> val returnedItem = ddb.getItem(request) val numbersMap = returnedItem.item numbersMap?.forEach { key1 -> println(key1.key) println(key1.value) } } } suspend fun deletIssuesTable(tableNameVal: String) { val request = DeleteTableRequest { tableName = tableNameVal } DynamoDbClient { region = "us-east-1" }.use { ddb -> ddb.deleteTable(request) println("$tableNameVal was deleted") } } suspend fun queryMovieTable( tableNameVal: String, partitionKeyName: String, partitionAlias: String, ): Int { val attrNameAlias = mutableMapOf<String, String>() attrNameAlias[partitionAlias] = "year" // Set up mapping of the partition name with the value. val attrValues = mutableMapOf<String, AttributeValue>() attrValues[":$partitionKeyName"] = AttributeValue.N("2013") val request = QueryRequest { tableName = tableNameVal keyConditionExpression = "$partitionAlias = :$partitionKeyName" expressionAttributeNames = attrNameAlias this.expressionAttributeValues = attrValues } DynamoDbClient { region = "us-east-1" }.use { ddb -> val response = ddb.query(request) return response.count } } suspend fun scanMovies(tableNameVal: String) { val request = ScanRequest { tableName = tableNameVal } DynamoDbClient { region = "us-east-1" }.use { ddb -> val response = ddb.scan(request) response.items?.forEach { item -> item.keys.forEach { key -> println("The key name is $key\n") println("The value is ${item[key]}") } } } }
-
For API details, see the following topics in Amazon SDK for Kotlin API reference.
-
- PHP
-
- SDK for PHP
-
Note
There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository
. namespace DynamoDb\Basics; use Aws\DynamoDb\Marshaler; use DynamoDb; use DynamoDb\DynamoDBAttribute; use DynamoDb\DynamoDBService; use function AwsUtilities\loadMovieData; use function AwsUtilities\testable_readline; class GettingStartedWithDynamoDB { public function run() { echo("\n"); echo("--------------------------------------\n"); print("Welcome to the Amazon DynamoDB getting started demo using PHP!\n"); echo("--------------------------------------\n"); $uuid = uniqid(); $service = new DynamoDBService(); $tableName = "ddb_demo_table_$uuid"; $service->createTable( $tableName, [ new DynamoDBAttribute('year', 'N', 'HASH'), new DynamoDBAttribute('title', 'S', 'RANGE') ] ); echo "Waiting for table..."; $service->dynamoDbClient->waitUntil("TableExists", ['TableName' => $tableName]); echo "table $tableName found!\n"; echo "What's the name of the last movie you watched?\n"; while (empty($movieName)) { $movieName = testable_readline("Movie name: "); } echo "And what year was it released?\n"; $movieYear = "year"; while (!is_numeric($movieYear) || intval($movieYear) != $movieYear) { $movieYear = testable_readline("Year released: "); } $service->putItem([ 'Item' => [ 'year' => [ 'N' => "$movieYear", ], 'title' => [ 'S' => $movieName, ], ], 'TableName' => $tableName, ]); echo "How would you rate the movie from 1-10?\n"; $rating = 0; while (!is_numeric($rating) || intval($rating) != $rating || $rating < 1 || $rating > 10) { $rating = testable_readline("Rating (1-10): "); } echo "What was the movie about?\n"; while (empty($plot)) { $plot = testable_readline("Plot summary: "); } $key = [ 'Item' => [ 'title' => [ 'S' => $movieName, ], 'year' => [ 'N' => $movieYear, ], ] ]; $attributes = ["rating" => [ 'AttributeName' => 'rating', 'AttributeType' => 'N', 'Value' => $rating, ], 'plot' => [ 'AttributeName' => 'plot', 'AttributeType' => 'S', 'Value' => $plot, ] ]; $service->updateItemAttributesByKey($tableName, $key, $attributes); echo "Movie added and updated."; $batch = json_decode(loadMovieData()); $service->writeBatch($tableName, $batch); $movie = $service->getItemByKey($tableName, $key); echo "\nThe movie {$movie['Item']['title']['S']} was released in {$movie['Item']['year']['N']}.\n"; echo "What rating would you like to give {$movie['Item']['title']['S']}?\n"; $rating = 0; while (!is_numeric($rating) || intval($rating) != $rating || $rating < 1 || $rating > 10) { $rating = testable_readline("Rating (1-10): "); } $service->updateItemAttributeByKey($tableName, $key, 'rating', 'N', $rating); $movie = $service->getItemByKey($tableName, $key); echo "Ok, you have rated {$movie['Item']['title']['S']} as a {$movie['Item']['rating']['N']}\n"; $service->deleteItemByKey($tableName, $key); echo "But, bad news, this was a trap. That movie has now been deleted because of your rating...harsh.\n"; echo "That's okay though. The book was better. Now, for something lighter, in what year were you born?\n"; $birthYear = "not a number"; while (!is_numeric($birthYear) || $birthYear >= date("Y")) { $birthYear = testable_readline("Birth year: "); } $birthKey = [ 'Key' => [ 'year' => [ 'N' => "$birthYear", ], ], ]; $result = $service->query($tableName, $birthKey); $marshal = new Marshaler(); echo "Here are the movies in our collection released the year you were born:\n"; $oops = "Oops! There were no movies released in that year (that we know of).\n"; $display = ""; foreach ($result['Items'] as $movie) { $movie = $marshal->unmarshalItem($movie); $display .= $movie['title'] . "\n"; } echo ($display) ?: $oops; $yearsKey = [ 'Key' => [ 'year' => [ 'N' => [ 'minRange' => 1990, 'maxRange' => 1999, ], ], ], ]; $filter = "year between 1990 and 1999"; echo "\nHere's a list of all the movies released in the 90s:\n"; $result = $service->scan($tableName, $yearsKey, $filter); foreach ($result['Items'] as $movie) { $movie = $marshal->unmarshalItem($movie); echo $movie['title'] . "\n"; } echo "\nCleaning up this demo by deleting table $tableName...\n"; $service->deleteTable($tableName); } }
-
For API details, see the following topics in Amazon SDK for PHP API 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
. Create a class that encapsulates a DynamoDB table.
from decimal import Decimal from io import BytesIO import json import logging import os from pprint import pprint import requests from zipfile import ZipFile import boto3 from boto3.dynamodb.conditions import Key from botocore.exceptions import ClientError from question import Question logger = logging.getLogger(__name__) class Movies: """Encapsulates an Amazon DynamoDB table of movie data. Example data structure for a movie record in this table: { "year": 1999, "title": "For Love of the Game", "info": { "directors": ["Sam Raimi"], "release_date": "1999-09-15T00:00:00Z", "rating": 6.3, "plot": "A washed up pitcher flashes through his career.", "rank": 4987, "running_time_secs": 8220, "actors": [ "Kevin Costner", "Kelly Preston", "John C. Reilly" ] } } """ def __init__(self, dyn_resource): """ :param dyn_resource: A Boto3 DynamoDB resource. """ self.dyn_resource = dyn_resource # The table variable is set during the scenario in the call to # 'exists' if the table exists. Otherwise, it is set by 'create_table'. self.table = None def exists(self, table_name): """ Determines whether a table exists. As a side effect, stores the table in a member variable. :param table_name: The name of the table to check. :return: True when the table exists; otherwise, False. """ try: table = self.dyn_resource.Table(table_name) table.load() exists = True except ClientError as err: if err.response["Error"]["Code"] == "ResourceNotFoundException": exists = False else: logger.error( "Couldn't check for existence of %s. Here's why: %s: %s", table_name, err.response["Error"]["Code"], err.response["Error"]["Message"], ) raise else: self.table = table return exists def create_table(self, table_name): """ Creates an Amazon DynamoDB table that can be used to store movie data. The table uses the release year of the movie as the partition key and the title as the sort key. :param table_name: The name of the table to create. :return: The newly created table. """ try: self.table = self.dyn_resource.create_table( TableName=table_name, KeySchema=[ {"AttributeName": "year", "KeyType": "HASH"}, # Partition key {"AttributeName": "title", "KeyType": "RANGE"}, # Sort key ], AttributeDefinitions=[ {"AttributeName": "year", "AttributeType": "N"}, {"AttributeName": "title", "AttributeType": "S"}, ], ProvisionedThroughput={ "ReadCapacityUnits": 10, "WriteCapacityUnits": 10, }, ) self.table.wait_until_exists() except ClientError as err: logger.error( "Couldn't create table %s. Here's why: %s: %s", table_name, err.response["Error"]["Code"], err.response["Error"]["Message"], ) raise else: return self.table def list_tables(self): """ Lists the Amazon DynamoDB tables for the current account. :return: The list of tables. """ try: tables = [] for table in self.dyn_resource.tables.all(): print(table.name) tables.append(table) except ClientError as err: logger.error( "Couldn't list tables. Here's why: %s: %s", err.response["Error"]["Code"], err.response["Error"]["Message"], ) raise else: return tables def write_batch(self, movies): """ Fills an Amazon DynamoDB table with the specified data, using the Boto3 Table.batch_writer() function to put the items in the table. Inside the context manager, Table.batch_writer builds a list of requests. On exiting the context manager, Table.batch_writer starts sending batches of write requests to Amazon DynamoDB and automatically handles chunking, buffering, and retrying. :param movies: The data to put in the table. Each item must contain at least the keys required by the schema that was specified when the table was created. """ try: with self.table.batch_writer() as writer: for movie in movies: writer.put_item(Item=movie) except ClientError as err: logger.error( "Couldn't load data into table %s. Here's why: %s: %s", self.table.name, err.response["Error"]["Code"], err.response["Error"]["Message"], ) raise def add_movie(self, title, year, plot, rating): """ Adds a movie to the table. :param title: The title of the movie. :param year: The release year of the movie. :param plot: The plot summary of the movie. :param rating: The quality rating of the movie. """ try: self.table.put_item( Item={ "year": year, "title": title, "info": {"plot": plot, "rating": Decimal(str(rating))}, } ) except ClientError as err: logger.error( "Couldn't add movie %s to table %s. Here's why: %s: %s", title, self.table.name, err.response["Error"]["Code"], err.response["Error"]["Message"], ) raise def get_movie(self, title, year): """ Gets movie data from the table for a specific movie. :param title: The title of the movie. :param year: The release year of the movie. :return: The data about the requested movie. """ try: response = self.table.get_item(Key={"year": year, "title": title}) except ClientError as err: logger.error( "Couldn't get movie %s from table %s. Here's why: %s: %s", title, self.table.name, err.response["Error"]["Code"], err.response["Error"]["Message"], ) raise else: return response["Item"] def update_movie(self, title, year, rating, plot): """ Updates rating and plot data for a movie in the table. :param title: The title of the movie to update. :param year: The release year of the movie to update. :param rating: The updated rating to the give the movie. :param plot: The updated plot summary to give the movie. :return: The fields that were updated, with their new values. """ try: response = self.table.update_item( Key={"year": year, "title": title}, UpdateExpression="set info.rating=:r, info.plot=:p", ExpressionAttributeValues={":r": Decimal(str(rating)), ":p": plot}, ReturnValues="UPDATED_NEW", ) except ClientError as err: logger.error( "Couldn't update movie %s in table %s. Here's why: %s: %s", title, self.table.name, err.response["Error"]["Code"], err.response["Error"]["Message"], ) raise else: return response["Attributes"] def query_movies(self, year): """ Queries for movies that were released in the specified year. :param year: The year to query. :return: The list of movies that were released in the specified year. """ try: response = self.table.query(KeyConditionExpression=Key("year").eq(year)) except ClientError as err: logger.error( "Couldn't query for movies released in %s. Here's why: %s: %s", year, err.response["Error"]["Code"], err.response["Error"]["Message"], ) raise else: return response["Items"] def scan_movies(self, year_range): """ Scans for movies that were released in a range of years. Uses a projection expression to return a subset of data for each movie. :param year_range: The range of years to retrieve. :return: The list of movies released in the specified years. """ movies = [] scan_kwargs = { "FilterExpression": Key("year").between( year_range["first"], year_range["second"] ), "ProjectionExpression": "#yr, title, info.rating", "ExpressionAttributeNames": {"#yr": "year"}, } try: done = False start_key = None while not done: if start_key: scan_kwargs["ExclusiveStartKey"] = start_key response = self.table.scan(**scan_kwargs) movies.extend(response.get("Items", [])) start_key = response.get("LastEvaluatedKey", None) done = start_key is None except ClientError as err: logger.error( "Couldn't scan for movies. Here's why: %s: %s", err.response["Error"]["Code"], err.response["Error"]["Message"], ) raise return movies def delete_movie(self, title, year): """ Deletes a movie from the table. :param title: The title of the movie to delete. :param year: The release year of the movie to delete. """ try: self.table.delete_item(Key={"year": year, "title": title}) except ClientError as err: logger.error( "Couldn't delete movie %s. Here's why: %s: %s", title, err.response["Error"]["Code"], err.response["Error"]["Message"], ) raise def delete_table(self): """ Deletes the table. """ try: self.table.delete() self.table = None except ClientError as err: logger.error( "Couldn't delete table. Here's why: %s: %s", err.response["Error"]["Code"], err.response["Error"]["Message"], ) raise
Create a helper function to download and extract the sample JSON file.
def get_sample_movie_data(movie_file_name): """ Gets sample movie data, either from a local file or by first downloading it from the Amazon DynamoDB developer guide. :param movie_file_name: The local file name where the movie data is stored in JSON format. :return: The movie data as a dict. """ if not os.path.isfile(movie_file_name): print(f"Downloading {movie_file_name}...") movie_content = requests.get( "https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/samples/moviedata.zip" ) movie_zip = ZipFile(BytesIO(movie_content.content)) movie_zip.extractall() try: with open(movie_file_name) as movie_file: movie_data = json.load(movie_file, parse_float=Decimal) except FileNotFoundError: print( f"File {movie_file_name} not found. You must first download the file to " "run this demo. See the README for instructions." ) raise else: # The sample file lists over 4000 movies, return only the first 250. return movie_data[:250]
Run an interactive scenario to create the table and perform actions on it.
def run_scenario(table_name, movie_file_name, dyn_resource): logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s") print("-" * 88) print("Welcome to the Amazon DynamoDB getting started demo.") print("-" * 88) movies = Movies(dyn_resource) movies_exists = movies.exists(table_name) if not movies_exists: print(f"\nCreating table {table_name}...") movies.create_table(table_name) print(f"\nCreated table {movies.table.name}.") my_movie = Question.ask_questions( [ Question( "title", "Enter the title of a movie you want to add to the table: " ), Question("year", "What year was it released? ", Question.is_int), Question( "rating", "On a scale of 1 - 10, how do you rate it? ", Question.is_float, Question.in_range(1, 10), ), Question("plot", "Summarize the plot for me: "), ] ) movies.add_movie(**my_movie) print(f"\nAdded '{my_movie['title']}' to '{movies.table.name}'.") print("-" * 88) movie_update = Question.ask_questions( [ Question( "rating", f"\nLet's update your movie.\nYou rated it {my_movie['rating']}, what new " f"rating would you give it? ", Question.is_float, Question.in_range(1, 10), ), Question( "plot", f"You summarized the plot as '{my_movie['plot']}'.\nWhat would you say now? ", ), ] ) my_movie.update(movie_update) updated = movies.update_movie(**my_movie) print(f"\nUpdated '{my_movie['title']}' with new attributes:") pprint(updated) print("-" * 88) if not movies_exists: movie_data = get_sample_movie_data(movie_file_name) print(f"\nReading data from '{movie_file_name}' into your table.") movies.write_batch(movie_data) print(f"\nWrote {len(movie_data)} movies into {movies.table.name}.") print("-" * 88) title = "The Lord of the Rings: The Fellowship of the Ring" if Question.ask_question( f"Let's move on...do you want to get info about '{title}'? (y/n) ", Question.is_yesno, ): movie = movies.get_movie(title, 2001) print("\nHere's what I found:") pprint(movie) print("-" * 88) ask_for_year = True while ask_for_year: release_year = Question.ask_question( f"\nLet's get a list of movies released in a given year. Enter a year between " f"1972 and 2018: ", Question.is_int, Question.in_range(1972, 2018), ) releases = movies.query_movies(release_year) if releases: print(f"There were {len(releases)} movies released in {release_year}:") for release in releases: print(f"\t{release['title']}") ask_for_year = False else: print(f"I don't know about any movies released in {release_year}!") ask_for_year = Question.ask_question( "Try another year? (y/n) ", Question.is_yesno ) print("-" * 88) years = Question.ask_questions( [ Question( "first", f"\nNow let's scan for movies released in a range of years. Enter a year: ", Question.is_int, Question.in_range(1972, 2018), ), Question( "second", "Now enter another year: ", Question.is_int, Question.in_range(1972, 2018), ), ] ) releases = movies.scan_movies(years) if releases: count = Question.ask_question( f"\nFound {len(releases)} movies. How many do you want to see? ", Question.is_int, Question.in_range(1, len(releases)), ) print(f"\nHere are your {count} movies:\n") pprint(releases[:count]) else: print( f"I don't know about any movies released between {years['first']} " f"and {years['second']}." ) print("-" * 88) if Question.ask_question( f"\nLet's remove your movie from the table. Do you want to remove " f"'{my_movie['title']}'? (y/n)", Question.is_yesno, ): movies.delete_movie(my_movie["title"], my_movie["year"]) print(f"\nRemoved '{my_movie['title']}' from the table.") print("-" * 88) if Question.ask_question(f"\nDelete the table? (y/n) ", Question.is_yesno): movies.delete_table() print(f"Deleted {table_name}.") else: print( "Don't forget to delete the table when you're done or you might incur " "charges on your account." ) print("\nThanks for watching!") print("-" * 88) if __name__ == "__main__": try: run_scenario( "doc-example-table-movies", "moviedata.json", boto3.resource("dynamodb") ) except Exception as e: print(f"Something went wrong with the demo! Here's what: {e}")
This scenario uses the following helper class to ask questions at a command prompt.
class Question: """ A helper class to ask questions at a command prompt and validate and convert the answers. """ def __init__(self, key, question, *validators): """ :param key: The key that is used for storing the answer in a dict, when multiple questions are asked in a set. :param question: The question to ask. :param validators: The answer is passed through the list of validators until one fails or they all pass. Validators may also convert the answer to another form, such as from a str to an int. """ self.key = key self.question = question self.validators = Question.non_empty, *validators @staticmethod def ask_questions(questions): """ Asks a set of questions and stores the answers in a dict. :param questions: The list of questions to ask. :return: A dict of answers. """ answers = {} for question in questions: answers[question.key] = Question.ask_question( question.question, *question.validators ) return answers @staticmethod def ask_question(question, *validators): """ Asks a single question and validates it against a list of validators. When an answer fails validation, the complaint is printed and the question is asked again. :param question: The question to ask. :param validators: The list of validators that the answer must pass. :return: The answer, converted to its final form by the validators. """ answer = None while answer is None: answer = input(question) for validator in validators: answer, complaint = validator(answer) if answer is None: print(complaint) break return answer @staticmethod def non_empty(answer): """ Validates that the answer is not empty. :return: The non-empty answer, or None. """ return answer if answer != "" else None, "I need an answer. Please?" @staticmethod def is_yesno(answer): """ Validates a yes/no answer. :return: True when the answer is 'y'; otherwise, False. """ return answer.lower() == "y", "" @staticmethod def is_int(answer): """ Validates that the answer can be converted to an int. :return: The int answer; otherwise, None. """ try: int_answer = int(answer) except ValueError: int_answer = None return int_answer, f"{answer} must be a valid integer." @staticmethod def is_letter(answer): """ Validates that the answer is a letter. :return The letter answer, converted to uppercase; otherwise, None. """ return ( answer.upper() if answer.isalpha() else None, f"{answer} must be a single letter.", ) @staticmethod def is_float(answer): """ Validate that the answer can be converted to a float. :return The float answer; otherwise, None. """ try: float_answer = float(answer) except ValueError: float_answer = None return float_answer, f"{answer} must be a valid float." @staticmethod def in_range(lower, upper): """ Validate that the answer is within a range. The answer must be of a type that can be compared to the lower and upper bounds. :return: The answer, if it is within the range; otherwise, None. """ def _validate(answer): return ( answer if lower <= answer <= upper else None, f"{answer} must be between {lower} and {upper}.", ) return _validate
-
For API details, see the following topics in Amazon SDK for Python (Boto3) API Reference.
-
- Ruby
-
- SDK for Ruby
-
Note
There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository
. Create a class that encapsulates a DynamoDB table.
# Creates an Amazon DynamoDB table that can be used to store movie data. # The table uses the release year of the movie as the partition key and the # title as the sort key. # # @param table_name [String] The name of the table to create. # @return [Aws::DynamoDB::Table] The newly created table. def create_table(table_name) @table = @dynamo_resource.create_table( table_name: table_name, key_schema: [ { attribute_name: 'year', key_type: 'HASH' }, # Partition key { attribute_name: 'title', key_type: 'RANGE' } # Sort key ], attribute_definitions: [ { attribute_name: 'year', attribute_type: 'N' }, { attribute_name: 'title', attribute_type: 'S' } ], provisioned_throughput: { read_capacity_units: 10, write_capacity_units: 10 } ) @dynamo_resource.client.wait_until(:table_exists, table_name: table_name) @table rescue Aws::DynamoDB::Errors::ServiceError => e @logger.error("Failed create table #{table_name}:\n#{e.code}: #{e.message}") raise end
Create a helper function to download and extract the sample JSON file.
# Gets sample movie data, either from a local file or by first downloading it from # the Amazon DynamoDB Developer Guide. # # @param movie_file_name [String] The local file name where the movie data is stored in JSON format. # @return [Hash] The movie data as a Hash. def fetch_movie_data(movie_file_name) if !File.file?(movie_file_name) @logger.debug("Downloading #{movie_file_name}...") movie_content = URI.open( 'https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/samples/moviedata.zip' ) movie_json = '' Zip::File.open_buffer(movie_content) do |zip| zip.each do |entry| movie_json = entry.get_input_stream.read end end else movie_json = File.read(movie_file_name) end movie_data = JSON.parse(movie_json) # The sample file lists over 4000 movies. This returns only the first 250. movie_data.slice(0, 250) rescue StandardError => e puts("Failure downloading movie data:\n#{e}") raise end
Run an interactive scenario to create the table and perform actions on it.
table_name = "doc-example-table-movies-#{rand(10**4)}" scaffold = Scaffold.new(table_name) dynamodb_wrapper = DynamoDBBasics.new(table_name) new_step(1, 'Create a new DynamoDB table if none already exists.') unless scaffold.exists?(table_name) puts("\nNo such table: #{table_name}. Creating it...") scaffold.create_table(table_name) print "Done!\n".green end new_step(2, 'Add a new record to the DynamoDB table.') my_movie = {} my_movie[:title] = CLI::UI::Prompt.ask('Enter the title of a movie to add to the table. E.g. The Matrix') my_movie[:year] = CLI::UI::Prompt.ask('What year was it released? E.g. 1989').to_i my_movie[:rating] = CLI::UI::Prompt.ask('On a scale of 1 - 10, how do you rate it? E.g. 7').to_i my_movie[:plot] = CLI::UI::Prompt.ask('Enter a brief summary of the plot. E.g. A man awakens to a new reality.') dynamodb_wrapper.add_item(my_movie) puts("\nNew record added:") puts JSON.pretty_generate(my_movie).green print "Done!\n".green new_step(3, 'Update a record in the DynamoDB table.') my_movie[:rating] = CLI::UI::Prompt.ask("Let's update the movie you added with a new rating, e.g. 3:").to_i response = dynamodb_wrapper.update_item(my_movie) puts("Updated '#{my_movie[:title]}' with new attributes:") puts JSON.pretty_generate(response).green print "Done!\n".green new_step(4, 'Get a record from the DynamoDB table.') puts("Searching for #{my_movie[:title]} (#{my_movie[:year]})...") response = dynamodb_wrapper.get_item(my_movie[:title], my_movie[:year]) puts JSON.pretty_generate(response).green print "Done!\n".green new_step(5, 'Write a batch of items into the DynamoDB table.') download_file = 'moviedata.json' puts("Downloading movie database to #{download_file}...") movie_data = scaffold.fetch_movie_data(download_file) puts("Writing movie data from #{download_file} into your table...") scaffold.write_batch(movie_data) puts("Records added: #{movie_data.length}.") print "Done!\n".green new_step(5, 'Query for a batch of items by key.') loop do release_year = CLI::UI::Prompt.ask('Enter a year between 1972 and 2018, e.g. 1999:').to_i results = dynamodb_wrapper.query_items(release_year) if results.any? puts("There were #{results.length} movies released in #{release_year}:") results.each do |movie| print "\t #{movie['title']}".green end break else continue = CLI::UI::Prompt.ask("Found no movies released in #{release_year}! Try another year? (y/n)") break unless continue.eql?('y') end end print "\nDone!\n".green new_step(6, 'Scan for a batch of items using a filter expression.') years = {} years[:start] = CLI::UI::Prompt.ask('Enter a starting year between 1972 and 2018:') years[:end] = CLI::UI::Prompt.ask('Enter an ending year between 1972 and 2018:') releases = dynamodb_wrapper.scan_items(years) if !releases.empty? puts("Found #{releases.length} movies.") count = Question.ask( 'How many do you want to see? ', method(:is_int), in_range(1, releases.length) ) puts("Here are your #{count} movies:") releases.take(count).each do |release| puts("\t#{release['title']}") end else puts("I don't know about any movies released between #{years[:start]} "\ "and #{years[:end]}.") end print "\nDone!\n".green new_step(7, 'Delete an item from the DynamoDB table.') answer = CLI::UI::Prompt.ask("Do you want to remove '#{my_movie[:title]}'? (y/n) ") if answer.eql?('y') dynamodb_wrapper.delete_item(my_movie[:title], my_movie[:year]) puts("Removed '#{my_movie[:title]}' from the table.") print "\nDone!\n".green end new_step(8, 'Delete the DynamoDB table.') answer = CLI::UI::Prompt.ask('Delete the table? (y/n)') if answer.eql?('y') scaffold.delete_table puts("Deleted #{table_name}.") else puts("Don't forget to delete the table when you're done!") end print "\nThanks for watching!\n".green rescue Aws::Errors::ServiceError puts('Something went wrong with the demo.') rescue Errno::ENOENT true end
-
For API details, see the following topics in Amazon SDK for Ruby API Reference.
-
- SAP ABAP
-
- SDK for SAP ABAP
-
Note
There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository
. " Create an Amazon Dynamo DB table. TRY. DATA(lo_session) = /aws1/cl_rt_session_aws=>create( cv_pfl ). DATA(lo_dyn) = /aws1/cl_dyn_factory=>create( lo_session ). DATA(lt_keyschema) = VALUE /aws1/cl_dynkeyschemaelement=>tt_keyschema( ( NEW /aws1/cl_dynkeyschemaelement( iv_attributename = 'year' iv_keytype = 'HASH' ) ) ( NEW /aws1/cl_dynkeyschemaelement( iv_attributename = 'title' iv_keytype = 'RANGE' ) ) ). DATA(lt_attributedefinitions) = VALUE /aws1/cl_dynattributedefn=>tt_attributedefinitions( ( NEW /aws1/cl_dynattributedefn( iv_attributename = 'year' iv_attributetype = 'N' ) ) ( NEW /aws1/cl_dynattributedefn( iv_attributename = 'title' iv_attributetype = 'S' ) ) ). " Adjust read/write capacities as desired. DATA(lo_dynprovthroughput) = NEW /aws1/cl_dynprovthroughput( iv_readcapacityunits = 5 iv_writecapacityunits = 5 ). DATA(oo_result) = lo_dyn->createtable( it_keyschema = lt_keyschema iv_tablename = iv_table_name it_attributedefinitions = lt_attributedefinitions io_provisionedthroughput = lo_dynprovthroughput ). " Table creation can take some time. Wait till table exists before returning. lo_dyn->get_waiter( )->tableexists( iv_max_wait_time = 200 iv_tablename = iv_table_name ). MESSAGE 'DynamoDB Table' && iv_table_name && 'created.' TYPE 'I'. " It throws exception if the table already exists. CATCH /aws1/cx_dynresourceinuseex INTO DATA(lo_resourceinuseex). DATA(lv_error) = |"{ lo_resourceinuseex->av_err_code }" - { lo_resourceinuseex->av_err_msg }|. MESSAGE lv_error TYPE 'E'. ENDTRY. " Describe table TRY. DATA(lo_table) = lo_dyn->describetable( iv_tablename = iv_table_name ). DATA(lv_tablename) = lo_table->get_table( )->ask_tablename( ). MESSAGE 'The table name is ' && lv_tablename TYPE 'I'. CATCH /aws1/cx_dynresourcenotfoundex. MESSAGE 'The table does not exist' TYPE 'E'. ENDTRY. " Put items into the table. TRY. DATA(lo_resp_putitem) = lo_dyn->putitem( iv_tablename = iv_table_name it_item = VALUE /aws1/cl_dynattributevalue=>tt_putiteminputattributemap( ( VALUE /aws1/cl_dynattributevalue=>ts_putiteminputattrmap_maprow( key = 'title' value = NEW /aws1/cl_dynattributevalue( iv_s = 'Jaws' ) ) ) ( VALUE /aws1/cl_dynattributevalue=>ts_putiteminputattrmap_maprow( key = 'year' value = NEW /aws1/cl_dynattributevalue( iv_n = |{ '1975' }| ) ) ) ( VALUE /aws1/cl_dynattributevalue=>ts_putiteminputattrmap_maprow( key = 'rating' value = NEW /aws1/cl_dynattributevalue( iv_n = |{ '7.5' }| ) ) ) ) ). lo_resp_putitem = lo_dyn->putitem( iv_tablename = iv_table_name it_item = VALUE /aws1/cl_dynattributevalue=>tt_putiteminputattributemap( ( VALUE /aws1/cl_dynattributevalue=>ts_putiteminputattrmap_maprow( key = 'title' value = NEW /aws1/cl_dynattributevalue( iv_s = 'Star Wars' ) ) ) ( VALUE /aws1/cl_dynattributevalue=>ts_putiteminputattrmap_maprow( key = 'year' value = NEW /aws1/cl_dynattributevalue( iv_n = |{ '1978' }| ) ) ) ( VALUE /aws1/cl_dynattributevalue=>ts_putiteminputattrmap_maprow( key = 'rating' value = NEW /aws1/cl_dynattributevalue( iv_n = |{ '8.1' }| ) ) ) ) ). lo_resp_putitem = lo_dyn->putitem( iv_tablename = iv_table_name it_item = VALUE /aws1/cl_dynattributevalue=>tt_putiteminputattributemap( ( VALUE /aws1/cl_dynattributevalue=>ts_putiteminputattrmap_maprow( key = 'title' value = NEW /aws1/cl_dynattributevalue( iv_s = 'Speed' ) ) ) ( VALUE /aws1/cl_dynattributevalue=>ts_putiteminputattrmap_maprow( key = 'year' value = NEW /aws1/cl_dynattributevalue( iv_n = |{ '1994' }| ) ) ) ( VALUE /aws1/cl_dynattributevalue=>ts_putiteminputattrmap_maprow( key = 'rating' value = NEW /aws1/cl_dynattributevalue( iv_n = |{ '7.9' }| ) ) ) ) ). " TYPE REF TO ZCL_AWS1_dyn_PUT_ITEM_OUTPUT MESSAGE '3 rows inserted into DynamoDB Table' && iv_table_name TYPE 'I'. CATCH /aws1/cx_dyncondalcheckfaile00. MESSAGE 'A condition specified in the operation could not be evaluated.' TYPE 'E'. CATCH /aws1/cx_dynresourcenotfoundex. MESSAGE 'The table or index does not exist' TYPE 'E'. CATCH /aws1/cx_dyntransactconflictex. MESSAGE 'Another transaction is using the item' TYPE 'E'. ENDTRY. " Get item from table. TRY. DATA(lo_resp_getitem) = lo_dyn->getitem( iv_tablename = iv_table_name it_key = VALUE /aws1/cl_dynattributevalue=>tt_key( ( VALUE /aws1/cl_dynattributevalue=>ts_key_maprow( key = 'title' value = NEW /aws1/cl_dynattributevalue( iv_s = 'Jaws' ) ) ) ( VALUE /aws1/cl_dynattributevalue=>ts_key_maprow( key = 'year' value = NEW /aws1/cl_dynattributevalue( iv_n = '1975' ) ) ) ) ). DATA(lt_attr) = lo_resp_getitem->get_item( ). DATA(lo_title) = lt_attr[ key = 'title' ]-value. DATA(lo_year) = lt_attr[ key = 'year' ]-value. DATA(lo_rating) = lt_attr[ key = 'year' ]-value. MESSAGE 'Movie name is: ' && lo_title->get_s( ) TYPE 'I'. MESSAGE 'Movie year is: ' && lo_year->get_n( ) TYPE 'I'. MESSAGE 'Movie rating is: ' && lo_rating->get_n( ) TYPE 'I'. CATCH /aws1/cx_dynresourcenotfoundex. MESSAGE 'The table or index does not exist' TYPE 'E'. ENDTRY. " Query item from table. TRY. DATA(lt_attributelist) = VALUE /aws1/cl_dynattributevalue=>tt_attributevaluelist( ( NEW /aws1/cl_dynattributevalue( iv_n = '1975' ) ) ). DATA(lt_keyconditions) = VALUE /aws1/cl_dyncondition=>tt_keyconditions( ( VALUE /aws1/cl_dyncondition=>ts_keyconditions_maprow( key = 'year' value = NEW /aws1/cl_dyncondition( it_attributevaluelist = lt_attributelist iv_comparisonoperator = |EQ| ) ) ) ). DATA(lo_query_result) = lo_dyn->query( iv_tablename = iv_table_name it_keyconditions = lt_keyconditions ). DATA(lt_items) = lo_query_result->get_items( ). READ TABLE lo_query_result->get_items( ) INTO DATA(lt_item) INDEX 1. lo_title = lt_item[ key = 'title' ]-value. lo_year = lt_item[ key = 'year' ]-value. lo_rating = lt_item[ key = 'rating' ]-value. MESSAGE 'Movie name is: ' && lo_title->get_s( ) TYPE 'I'. MESSAGE 'Movie year is: ' && lo_year->get_n( ) TYPE 'I'. MESSAGE 'Movie rating is: ' && lo_rating->get_n( ) TYPE 'I'. CATCH /aws1/cx_dynresourcenotfoundex. MESSAGE 'The table or index does not exist' TYPE 'E'. ENDTRY. " Scan items from table. TRY. DATA(lo_scan_result) = lo_dyn->scan( iv_tablename = iv_table_name ). lt_items = lo_scan_result->get_items( ). " Read the first item and display the attributes. READ TABLE lo_query_result->get_items( ) INTO lt_item INDEX 1. lo_title = lt_item[ key = 'title' ]-value. lo_year = lt_item[ key = 'year' ]-value. lo_rating = lt_item[ key = 'rating' ]-value. MESSAGE 'Movie name is: ' && lo_title->get_s( ) TYPE 'I'. MESSAGE 'Movie year is: ' && lo_year->get_n( ) TYPE 'I'. MESSAGE 'Movie rating is: ' && lo_rating->get_n( ) TYPE 'I'. CATCH /aws1/cx_dynresourcenotfoundex. MESSAGE 'The table or index does not exist' TYPE 'E'. ENDTRY. " Update items from table. TRY. DATA(lt_attributeupdates) = VALUE /aws1/cl_dynattrvalueupdate=>tt_attributeupdates( ( VALUE /aws1/cl_dynattrvalueupdate=>ts_attributeupdates_maprow( key = 'rating' value = NEW /aws1/cl_dynattrvalueupdate( io_value = NEW /aws1/cl_dynattributevalue( iv_n = '7.6' ) iv_action = |PUT| ) ) ) ). DATA(lt_key) = VALUE /aws1/cl_dynattributevalue=>tt_key( ( VALUE /aws1/cl_dynattributevalue=>ts_key_maprow( key = 'year' value = NEW /aws1/cl_dynattributevalue( iv_n = '1975' ) ) ) ( VALUE /aws1/cl_dynattributevalue=>ts_key_maprow( key = 'title' value = NEW /aws1/cl_dynattributevalue( iv_s = '1980' ) ) ) ). DATA(lo_resp) = lo_dyn->updateitem( iv_tablename = iv_table_name it_key = lt_key it_attributeupdates = lt_attributeupdates ). MESSAGE '1 item updated in DynamoDB Table' && iv_table_name TYPE 'I'. CATCH /aws1/cx_dyncondalcheckfaile00. MESSAGE 'A condition specified in the operation could not be evaluated.' TYPE 'E'. CATCH /aws1/cx_dynresourcenotfoundex. MESSAGE 'The table or index does not exist' TYPE 'E'. CATCH /aws1/cx_dyntransactconflictex. MESSAGE 'Another transaction is using the item' TYPE 'E'. ENDTRY. " Delete table. TRY. lo_dyn->deletetable( iv_tablename = iv_table_name ). lo_dyn->get_waiter( )->tablenotexists( iv_max_wait_time = 200 iv_tablename = iv_table_name ). MESSAGE 'DynamoDB Table deleted.' TYPE 'I'. CATCH /aws1/cx_dynresourcenotfoundex. MESSAGE 'The table or index does not exist' TYPE 'E'. CATCH /aws1/cx_dynresourceinuseex. MESSAGE 'The table cannot be deleted as it is in use' TYPE 'E'. ENDTRY.
-
For API details, see the following topics in Amazon SDK for SAP ABAP 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
. A Swift class that handles DynamoDB calls to the SDK for Swift.
import AWSDynamoDB import Foundation /// An enumeration of error codes representing issues that can arise when using /// the `MovieTable` class. enum MoviesError: Error { /// The specified table wasn't found or couldn't be created. case TableNotFound /// The specified item wasn't found or couldn't be created. case ItemNotFound /// The Amazon DynamoDB client is not properly initialized. case UninitializedClient /// The table status reported by Amazon DynamoDB is not recognized. case StatusUnknown /// One or more specified attribute values are invalid or missing. case InvalidAttributes } /// A class representing an Amazon DynamoDB table containing movie /// information. public class MovieTable { var ddbClient: DynamoDBClient? let tableName: String /// Create an object representing a movie table in an Amazon DynamoDB /// database. /// /// - Parameters: /// - region: The optional Amazon Region to create the database in. /// - tableName: The name to assign to the table. If not specified, a /// random table name is generated automatically. /// /// > Note: The table is not necessarily available when this function /// returns. Use `tableExists()` to check for its availability, or /// `awaitTableActive()` to wait until the table's status is reported as /// ready to use by Amazon DynamoDB. /// init(region: String? = nil, tableName: String) async throws { do { let config = try await DynamoDBClient.DynamoDBClientConfiguration() if let region = region { config.region = region } self.ddbClient = DynamoDBClient(config: config) self.tableName = tableName try await self.createTable() } catch { print("ERROR: ", dump(error, name: "Initializing Amazon DynamoDBClient client")) throw error } } /// /// Create a movie table in the Amazon DynamoDB data store. /// private func createTable() async throws { do { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } let input = CreateTableInput( attributeDefinitions: [ DynamoDBClientTypes.AttributeDefinition(attributeName: "year", attributeType: .n), DynamoDBClientTypes.AttributeDefinition(attributeName: "title", attributeType: .s) ], keySchema: [ DynamoDBClientTypes.KeySchemaElement(attributeName: "year", keyType: .hash), DynamoDBClientTypes.KeySchemaElement(attributeName: "title", keyType: .range) ], provisionedThroughput: DynamoDBClientTypes.ProvisionedThroughput( readCapacityUnits: 10, writeCapacityUnits: 10 ), tableName: self.tableName ) let output = try await client.createTable(input: input) if output.tableDescription == nil { throw MoviesError.TableNotFound } } catch { print("ERROR: createTable:", dump(error)) throw error } } /// Check to see if the table exists online yet. /// /// - Returns: `true` if the table exists, or `false` if not. /// func tableExists() async throws -> Bool { do { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } let input = DescribeTableInput( tableName: tableName ) let output = try await client.describeTable(input: input) guard let description = output.table else { throw MoviesError.TableNotFound } return description.tableName == self.tableName } catch { print("ERROR: tableExists:", dump(error)) throw error } } /// /// Waits for the table to exist and for its status to be active. /// func awaitTableActive() async throws { while try (await self.tableExists() == false) { do { let duration = UInt64(0.25 * 1_000_000_000) // Convert .25 seconds to nanoseconds. try await Task.sleep(nanoseconds: duration) } catch { print("Sleep error:", dump(error)) } } while try (await self.getTableStatus() != .active) { do { let duration = UInt64(0.25 * 1_000_000_000) // Convert .25 seconds to nanoseconds. try await Task.sleep(nanoseconds: duration) } catch { print("Sleep error:", dump(error)) } } } /// /// Deletes the table from Amazon DynamoDB. /// func deleteTable() async throws { do { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } let input = DeleteTableInput( tableName: self.tableName ) _ = try await client.deleteTable(input: input) } catch { print("ERROR: deleteTable:", dump(error)) throw error } } /// Get the table's status. /// /// - Returns: The table status, as defined by the /// `DynamoDBClientTypes.TableStatus` enum. /// func getTableStatus() async throws -> DynamoDBClientTypes.TableStatus { do { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } let input = DescribeTableInput( tableName: self.tableName ) let output = try await client.describeTable(input: input) guard let description = output.table else { throw MoviesError.TableNotFound } guard let status = description.tableStatus else { throw MoviesError.StatusUnknown } return status } catch { print("ERROR: getTableStatus:", dump(error)) throw error } } /// Populate the movie database from the specified JSON file. /// /// - Parameter jsonPath: Path to a JSON file containing movie data. /// func populate(jsonPath: String) async throws { do { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } // Create a Swift `URL` and use it to load the file into a `Data` // object. Then decode the JSON into an array of `Movie` objects. let fileUrl = URL(fileURLWithPath: jsonPath) let jsonData = try Data(contentsOf: fileUrl) var movieList = try JSONDecoder().decode([Movie].self, from: jsonData) // Truncate the list to the first 200 entries or so for this example. if movieList.count > 200 { movieList = Array(movieList[...199]) } // Before sending records to the database, break the movie list into // 25-entry chunks, which is the maximum size of a batch item request. let count = movieList.count let chunks = stride(from: 0, to: count, by: 25).map { Array(movieList[$0 ..< Swift.min($0 + 25, count)]) } // For each chunk, create a list of write request records and populate // them with `PutRequest` requests, each specifying one movie from the // chunk. Once the chunk's items are all in the `PutRequest` list, // send them to Amazon DynamoDB using the // `DynamoDBClient.batchWriteItem()` function. for chunk in chunks { var requestList: [DynamoDBClientTypes.WriteRequest] = [] for movie in chunk { let item = try await movie.getAsItem() let request = DynamoDBClientTypes.WriteRequest( putRequest: .init( item: item ) ) requestList.append(request) } let input = BatchWriteItemInput(requestItems: [tableName: requestList]) _ = try await client.batchWriteItem(input: input) } } catch { print("ERROR: populate:", dump(error)) throw error } } /// Add a movie specified as a `Movie` structure to the Amazon DynamoDB /// table. /// /// - Parameter movie: The `Movie` to add to the table. /// func add(movie: Movie) async throws { do { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } // Get a DynamoDB item containing the movie data. let item = try await movie.getAsItem() // Send the `PutItem` request to Amazon DynamoDB. let input = PutItemInput( item: item, tableName: self.tableName ) _ = try await client.putItem(input: input) } catch { print("ERROR: add movie:", dump(error)) throw error } } /// Given a movie's details, add a movie to the Amazon DynamoDB table. /// /// - Parameters: /// - title: The movie's title as a `String`. /// - year: The release year of the movie (`Int`). /// - rating: The movie's rating if available (`Double`; default is /// `nil`). /// - plot: A summary of the movie's plot (`String`; default is `nil`, /// indicating no plot summary is available). /// func add(title: String, year: Int, rating: Double? = nil, plot: String? = nil) async throws { do { let movie = Movie(title: title, year: year, rating: rating, plot: plot) try await self.add(movie: movie) } catch { print("ERROR: add with fields:", dump(error)) throw error } } /// Return a `Movie` record describing the specified movie from the Amazon /// DynamoDB table. /// /// - Parameters: /// - title: The movie's title (`String`). /// - year: The movie's release year (`Int`). /// /// - Throws: `MoviesError.ItemNotFound` if the movie isn't in the table. /// /// - Returns: A `Movie` record with the movie's details. func get(title: String, year: Int) async throws -> Movie { do { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } let input = GetItemInput( key: [ "year": .n(String(year)), "title": .s(title) ], tableName: self.tableName ) let output = try await client.getItem(input: input) guard let item = output.item else { throw MoviesError.ItemNotFound } let movie = try Movie(withItem: item) return movie } catch { print("ERROR: get:", dump(error)) throw error } } /// Get all the movies released in the specified year. /// /// - Parameter year: The release year of the movies to return. /// /// - Returns: An array of `Movie` objects describing each matching movie. /// func getMovies(fromYear year: Int) async throws -> [Movie] { do { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } let input = QueryInput( expressionAttributeNames: [ "#y": "year" ], expressionAttributeValues: [ ":y": .n(String(year)) ], keyConditionExpression: "#y = :y", tableName: self.tableName ) // Use "Paginated" to get all the movies. // This lets the SDK handle the 'lastEvaluatedKey' property in "QueryOutput". let pages = client.queryPaginated(input: input) var movieList: [Movie] = [] for try await page in pages { guard let items = page.items else { print("Error: no items returned.") continue } // Convert the found movies into `Movie` objects and return an array // of them. for item in items { let movie = try Movie(withItem: item) movieList.append(movie) } } return movieList } catch { print("ERROR: getMovies:", dump(error)) throw error } } /// Return an array of `Movie` objects released in the specified range of /// years. /// /// - Parameters: /// - firstYear: The first year of movies to return. /// - lastYear: The last year of movies to return. /// - startKey: A starting point to resume processing; always use `nil`. /// /// - Returns: An array of `Movie` objects describing the matching movies. /// /// > Note: The `startKey` parameter is used by this function when /// recursively calling itself, and should always be `nil` when calling /// directly. /// func getMovies(firstYear: Int, lastYear: Int, startKey: [Swift.String: DynamoDBClientTypes.AttributeValue]? = nil) async throws -> [Movie] { do { var movieList: [Movie] = [] guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } let input = ScanInput( consistentRead: true, exclusiveStartKey: startKey, expressionAttributeNames: [ "#y": "year" // `year` is a reserved word, so use `#y` instead. ], expressionAttributeValues: [ ":y1": .n(String(firstYear)), ":y2": .n(String(lastYear)) ], filterExpression: "#y BETWEEN :y1 AND :y2", tableName: self.tableName ) let pages = client.scanPaginated(input: input) for try await page in pages { guard let items = page.items else { print("Error: no items returned.") continue } // Build an array of `Movie` objects for the returned items. for item in items { let movie = try Movie(withItem: item) movieList.append(movie) } } return movieList } catch { print("ERROR: getMovies with scan:", dump(error)) throw error } } /// Update the specified movie with new `rating` and `plot` information. /// /// - Parameters: /// - title: The title of the movie to update. /// - year: The release year of the movie to update. /// - rating: The new rating for the movie. /// - plot: The new plot summary string for the movie. /// /// - Returns: An array of mappings of attribute names to their new /// listing each item actually changed. Items that didn't need to change /// aren't included in this list. `nil` if no changes were made. /// func update(title: String, year: Int, rating: Double? = nil, plot: String? = nil) async throws -> [Swift.String: DynamoDBClientTypes.AttributeValue]? { do { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } // Build the update expression and the list of expression attribute // values. Include only the information that's changed. var expressionParts: [String] = [] var attrValues: [Swift.String: DynamoDBClientTypes.AttributeValue] = [:] if rating != nil { expressionParts.append("info.rating=:r") attrValues[":r"] = .n(String(rating!)) } if plot != nil { expressionParts.append("info.plot=:p") attrValues[":p"] = .s(plot!) } let expression = "set \(expressionParts.joined(separator: ", "))" let input = UpdateItemInput( // Create substitution tokens for the attribute values, to ensure // no conflicts in expression syntax. expressionAttributeValues: attrValues, // The key identifying the movie to update consists of the release // year and title. key: [ "year": .n(String(year)), "title": .s(title) ], returnValues: .updatedNew, tableName: self.tableName, updateExpression: expression ) let output = try await client.updateItem(input: input) guard let attributes: [Swift.String: DynamoDBClientTypes.AttributeValue] = output.attributes else { throw MoviesError.InvalidAttributes } return attributes } catch { print("ERROR: update:", dump(error)) throw error } } /// Delete a movie, given its title and release year. /// /// - Parameters: /// - title: The movie's title. /// - year: The movie's release year. /// func delete(title: String, year: Int) async throws { do { guard let client = self.ddbClient else { throw MoviesError.UninitializedClient } let input = DeleteItemInput( key: [ "year": .n(String(year)), "title": .s(title) ], tableName: self.tableName ) _ = try await client.deleteItem(input: input) } catch { print("ERROR: delete:", dump(error)) throw error } } }
The structures used by the MovieTable class to represent movies.
import Foundation import AWSDynamoDB /// The optional details about a movie. public struct Details: Codable { /// The movie's rating, if available. var rating: Double? /// The movie's plot, if available. var plot: String? } /// A structure describing a movie. The `year` and `title` properties are /// required and are used as the key for Amazon DynamoDB operations. The /// `info` sub-structure's two properties, `rating` and `plot`, are optional. public struct Movie: Codable { /// The year in which the movie was released. var year: Int /// The movie's title. var title: String /// A `Details` object providing the optional movie rating and plot /// information. var info: Details /// Create a `Movie` object representing a movie, given the movie's /// details. /// /// - Parameters: /// - title: The movie's title (`String`). /// - year: The year in which the movie was released (`Int`). /// - rating: The movie's rating (optional `Double`). /// - plot: The movie's plot (optional `String`) init(title: String, year: Int, rating: Double? = nil, plot: String? = nil) { self.title = title self.year = year self.info = Details(rating: rating, plot: plot) } /// Create a `Movie` object representing a movie, given the movie's /// details. /// /// - Parameters: /// - title: The movie's title (`String`). /// - year: The year in which the movie was released (`Int`). /// - info: The optional rating and plot information for the movie in a /// `Details` object. init(title: String, year: Int, info: Details?){ self.title = title self.year = year if info != nil { self.info = info! } else { self.info = Details(rating: nil, plot: nil) } } /// /// Return a new `MovieTable` object, given an array mapping string to Amazon /// DynamoDB attribute values. /// /// - Parameter item: The item information provided to the form used by /// DynamoDB. This is an array of strings mapped to /// `DynamoDBClientTypes.AttributeValue` values. init(withItem item: [Swift.String:DynamoDBClientTypes.AttributeValue]) throws { // Read the attributes. guard let titleAttr = item["title"], let yearAttr = item["year"] else { throw MoviesError.ItemNotFound } let infoAttr = item["info"] ?? nil // Extract the values of the title and year attributes. if case .s(let titleVal) = titleAttr { self.title = titleVal } else { throw MoviesError.InvalidAttributes } if case .n(let yearVal) = yearAttr { self.year = Int(yearVal)! } else { throw MoviesError.InvalidAttributes } // Extract the rating and/or plot from the `info` attribute, if // they're present. var rating: Double? = nil var plot: String? = nil if infoAttr != nil, case .m(let infoVal) = infoAttr { let ratingAttr = infoVal["rating"] ?? nil let plotAttr = infoVal["plot"] ?? nil if ratingAttr != nil, case .n(let ratingVal) = ratingAttr { rating = Double(ratingVal) ?? nil } if plotAttr != nil, case .s(let plotVal) = plotAttr { plot = plotVal } } self.info = Details(rating: rating, plot: plot) } /// /// Return an array mapping attribute names to Amazon DynamoDB attribute /// values, representing the contents of the `Movie` record as a DynamoDB /// item. /// /// - Returns: The movie item as an array of type /// `[Swift.String:DynamoDBClientTypes.AttributeValue]`. /// func getAsItem() async throws -> [Swift.String:DynamoDBClientTypes.AttributeValue] { // Build the item record, starting with the year and title, which are // always present. var item: [Swift.String:DynamoDBClientTypes.AttributeValue] = [ "year": .n(String(self.year)), "title": .s(self.title) ] // Add the `info` field with the rating and/or plot if they're // available. var details: [Swift.String:DynamoDBClientTypes.AttributeValue] = [:] if (self.info.rating != nil || self.info.plot != nil) { if self.info.rating != nil { details["rating"] = .n(String(self.info.rating!)) } if self.info.plot != nil { details["plot"] = .s(self.info.plot!) } } item["info"] = .m(details) return item } }
A program that uses the MovieTable class to access a DynamoDB database.
import ArgumentParser import ClientRuntime import Foundation import AWSDynamoDB @testable import MovieList extension String { // Get the directory if the string is a file path. func directory() -> String { guard let lastIndex = lastIndex(of: "/") else { print("Error: String directory separator not found.") return "" } return String(self[...lastIndex]) } } struct ExampleCommand: ParsableCommand { @Argument(help: "The path of the sample movie data JSON file.") var jsonPath: String = #file.directory() + "../../../../../resources/sample_files/movies.json" @Option(help: "The AWS Region to run AWS API calls in.") var awsRegion: String? @Option( help: ArgumentHelp("The level of logging for the Swift SDK to perform."), completion: .list([ "critical", "debug", "error", "info", "notice", "trace", "warning" ]) ) var logLevel: String = "error" /// Configuration details for the command. static var configuration = CommandConfiguration( commandName: "basics", abstract: "A basic scenario demonstrating the usage of Amazon DynamoDB.", discussion: """ An example showing how to use Amazon DynamoDB to perform a series of common database activities on a simple movie database. """ ) /// Called by ``main()`` to asynchronously run the AWS example. func runAsync() async throws { print("Welcome to the AWS SDK for Swift basic scenario for Amazon DynamoDB!") //===================================================================== // 1. Create the table. The Amazon DynamoDB table is represented by // the `MovieTable` class. //===================================================================== let tableName = "ddb-movies-sample-\(Int.random(in: 1 ... Int.max))" print("Creating table \"\(tableName)\"...") let movieDatabase = try await MovieTable(region: awsRegion, tableName: tableName) print("\nWaiting for table to be ready to use...") try await movieDatabase.awaitTableActive() //===================================================================== // 2. Add a movie to the table. //===================================================================== print("\nAdding a movie...") try await movieDatabase.add(title: "Avatar: The Way of Water", year: 2022) try await movieDatabase.add(title: "Not a Real Movie", year: 2023) //===================================================================== // 3. Update the plot and rating of the movie using an update // expression. //===================================================================== print("\nAdding details to the added movie...") _ = try await movieDatabase.update(title: "Avatar: The Way of Water", year: 2022, rating: 9.2, plot: "It's a sequel.") //===================================================================== // 4. Populate the table from the JSON file. //===================================================================== print("\nPopulating the movie database from JSON...") try await movieDatabase.populate(jsonPath: jsonPath) //===================================================================== // 5. Get a specific movie by key. In this example, the key is a // combination of `title` and `year`. //===================================================================== print("\nLooking for a movie in the table...") let gotMovie = try await movieDatabase.get(title: "This Is the End", year: 2013) print("Found the movie \"\(gotMovie.title)\", released in \(gotMovie.year).") print("Rating: \(gotMovie.info.rating ?? 0.0).") print("Plot summary: \(gotMovie.info.plot ?? "None.")") //===================================================================== // 6. Delete a movie. //===================================================================== print("\nDeleting the added movie...") try await movieDatabase.delete(title: "Avatar: The Way of Water", year: 2022) //===================================================================== // 7. Use a query with a key condition expression to return all movies // released in a given year. //===================================================================== print("\nGetting movies released in 1994...") let movieList = try await movieDatabase.getMovies(fromYear: 1994) for movie in movieList { print(" \(movie.title)") } //===================================================================== // 8. Use `scan()` to return movies released in a range of years. //===================================================================== print("\nGetting movies released between 1993 and 1997...") let scannedMovies = try await movieDatabase.getMovies(firstYear: 1993, lastYear: 1997) for movie in scannedMovies { print(" \(movie.title) (\(movie.year))") } //===================================================================== // 9. Delete the table. //===================================================================== print("\nDeleting the table...") try await movieDatabase.deleteTable() } } @main struct Main { static func main() async { let args = Array(CommandLine.arguments.dropFirst()) do { let command = try ExampleCommand.parse(args) try await command.runAsync() } catch { ExampleCommand.exit(withError: error) } } }
-
For API details, see the following topics 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.