There are more AWS SDK examples available in the [AWS Doc SDK Examples](https://github.com/awsdocs/aws-doc-sdk-examples) GitHub repo.
# DynamoDB examples using SDK for Ruby
The following code examples show you how to perform actions and implement common scenarios by using the AWS SDK for Ruby with DynamoDB.
*Basics* are code examples that show you how to perform the essential operations within a service.
*Actions* are code excerpts from larger programs and must be run in context. While actions show you how to call individual service functions, you can see actions in context in their related scenarios.
*Scenarios* are code examples that show you how to accomplish specific tasks by calling multiple functions within a service or combined with other AWS services.
Each example includes a link to the complete source code, where you can find instructions on how to set up and run the code in context.
**Topics**
+ [Get started](#get_started)
+ [Basics](#basics)
+ [Actions](#actions)
+ [Scenarios](#scenarios)
+ [Serverless examples](#serverless_examples)
## Get started
### Hello DynamoDB
The following code example shows how to get started using DynamoDB.
**SDK for Ruby**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby/example_code/dynamodb#code-examples).
```
require 'aws-sdk-dynamodb'
require 'logger'
# DynamoDBManager is a class responsible for managing DynamoDB operations
# such as listing all tables in the current AWS account.
class DynamoDBManager
def initialize(client)
@client = client
@logger = Logger.new($stdout)
end
# Lists and prints all DynamoDB tables in the current AWS account.
def list_tables
@logger.info('Here are the DynamoDB tables in your account:')
paginator = @client.list_tables(limit: 10)
table_names = []
paginator.each_page do |page|
page.table_names.each do |table_name|
@logger.info("- #{table_name}")
table_names << table_name
end
end
if table_names.empty?
@logger.info("You don't have any DynamoDB tables in your account.")
else
@logger.info("\nFound #{table_names.length} tables.")
end
end
end
if $PROGRAM_NAME == __FILE__
dynamodb_client = Aws::DynamoDB::Client.new
manager = DynamoDBManager.new(dynamodb_client)
manager.list_tables
end
```
+ For API details, see [ListTables](https://docs.aws.amazon.com/goto/SdkForRubyV3/dynamodb-2012-08-10/ListTables) in *AWS SDK for Ruby API Reference*.
## Basics
### Learn the basics
The following code example shows 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.
**SDK for Ruby**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby/example_code/dynamodb#code-examples).
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' }
],
billing_mode: 'PAY_PER_REQUEST'
)
@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 *AWS SDK for Ruby API Reference*.
+ [BatchWriteItem](https://docs.aws.amazon.com/goto/SdkForRubyV3/dynamodb-2012-08-10/BatchWriteItem)
+ [CreateTable](https://docs.aws.amazon.com/goto/SdkForRubyV3/dynamodb-2012-08-10/CreateTable)
+ [DeleteItem](https://docs.aws.amazon.com/goto/SdkForRubyV3/dynamodb-2012-08-10/DeleteItem)
+ [DeleteTable](https://docs.aws.amazon.com/goto/SdkForRubyV3/dynamodb-2012-08-10/DeleteTable)
+ [DescribeTable](https://docs.aws.amazon.com/goto/SdkForRubyV3/dynamodb-2012-08-10/DescribeTable)
+ [GetItem](https://docs.aws.amazon.com/goto/SdkForRubyV3/dynamodb-2012-08-10/GetItem)
+ [PutItem](https://docs.aws.amazon.com/goto/SdkForRubyV3/dynamodb-2012-08-10/PutItem)
+ [Query](https://docs.aws.amazon.com/goto/SdkForRubyV3/dynamodb-2012-08-10/Query)
+ [Scan](https://docs.aws.amazon.com/goto/SdkForRubyV3/dynamodb-2012-08-10/Scan)
+ [UpdateItem](https://docs.aws.amazon.com/goto/SdkForRubyV3/dynamodb-2012-08-10/UpdateItem)
## Actions
### `BatchExecuteStatement`
The following code example shows how to use `BatchExecuteStatement`.
**SDK for Ruby**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby/example_code/dynamodb#code-examples).
Read a batch of items using PartiQL.
```
class DynamoDBPartiQLBatch
attr_reader :dynamo_resource, :table
def initialize(table_name)
client = Aws::DynamoDB::Client.new(region: 'us-east-1')
@dynamodb = Aws::DynamoDB::Resource.new(client: client)
@table = @dynamodb.table(table_name)
end
# Selects a batch of items from a table using PartiQL
#
# @param batch_titles [Array] Collection of movie titles
# @return [Aws::DynamoDB::Types::BatchExecuteStatementOutput]
def batch_execute_select(batch_titles)
request_items = batch_titles.map do |title, year|
{
statement: "SELECT * FROM \"#{@table.name}\" WHERE title=? and year=?",
parameters: [title, year]
}
end
@dynamodb.client.batch_execute_statement({ statements: request_items })
end
```
Delete a batch of items using PartiQL.
```
class DynamoDBPartiQLBatch
attr_reader :dynamo_resource, :table
def initialize(table_name)
client = Aws::DynamoDB::Client.new(region: 'us-east-1')
@dynamodb = Aws::DynamoDB::Resource.new(client: client)
@table = @dynamodb.table(table_name)
end
# Deletes a batch of items from a table using PartiQL
#
# @param batch_titles [Array] Collection of movie titles
# @return [Aws::DynamoDB::Types::BatchExecuteStatementOutput]
def batch_execute_write(batch_titles)
request_items = batch_titles.map do |title, year|
{
statement: "DELETE FROM \"#{@table.name}\" WHERE title=? and year=?",
parameters: [title, year]
}
end
@dynamodb.client.batch_execute_statement({ statements: request_items })
end
```
+ For API details, see [BatchExecuteStatement](https://docs.aws.amazon.com/goto/SdkForRubyV3/dynamodb-2012-08-10/BatchExecuteStatement) in *AWS SDK for Ruby API Reference*.
### `BatchWriteItem`
The following code example shows how to use `BatchWriteItem`.
**SDK for Ruby**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby/example_code/dynamodb#code-examples).
```
class DynamoDBBasics
attr_reader :dynamo_resource, :table
def initialize(table_name)
client = Aws::DynamoDB::Client.new(region: 'us-east-1')
@dynamo_resource = Aws::DynamoDB::Resource.new(client: client)
@table = @dynamo_resource.table(table_name)
end
# Fills an Amazon DynamoDB table with the specified data. Items are sent in
# batches of 25 until all items are written.
#
# @param movies [Enumerable] 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.
def write_batch(movies)
index = 0
slice_size = 25
while index < movies.length
movie_items = []
movies[index, slice_size].each do |movie|
movie_items.append({ put_request: { item: movie } })
end
@dynamo_resource.client.batch_write_item({ request_items: { @table.name => movie_items } })
index += slice_size
end
rescue Aws::DynamoDB::Errors::ServiceError => e
puts(
"Couldn't load data into table #{@table.name}. Here's why:"
)
puts("\t#{e.code}: #{e.message}")
raise
end
```
+ For API details, see [BatchWriteItem](https://docs.aws.amazon.com/goto/SdkForRubyV3/dynamodb-2012-08-10/BatchWriteItem) in *AWS SDK for Ruby API Reference*.
### `CreateTable`
The following code example shows how to use `CreateTable`.
**SDK for Ruby**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby/example_code/dynamodb#code-examples).
```
# Encapsulates an Amazon DynamoDB table of movie data.
class Scaffold
attr_reader :dynamo_resource, :table_name, :table
def initialize(table_name)
client = Aws::DynamoDB::Client.new(region: 'us-east-1')
@dynamo_resource = Aws::DynamoDB::Resource.new(client: client)
@table_name = table_name
@table = nil
@logger = Logger.new($stdout)
@logger.level = Logger::DEBUG
end
# 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' }
],
billing_mode: 'PAY_PER_REQUEST'
)
@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
```
+ For API details, see [CreateTable](https://docs.aws.amazon.com/goto/SdkForRubyV3/dynamodb-2012-08-10/CreateTable) in *AWS SDK for Ruby API Reference*.
### `DeleteItem`
The following code example shows how to use `DeleteItem`.
**SDK for Ruby**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby/example_code/dynamodb#code-examples).
```
class DynamoDBBasics
attr_reader :dynamo_resource, :table
def initialize(table_name)
client = Aws::DynamoDB::Client.new(region: 'us-east-1')
@dynamo_resource = Aws::DynamoDB::Resource.new(client: client)
@table = @dynamo_resource.table(table_name)
end
# Deletes a movie from the table.
#
# @param title [String] The title of the movie to delete.
# @param year [Integer] The release year of the movie to delete.
def delete_item(title, year)
@table.delete_item(key: { 'year' => year, 'title' => title })
rescue Aws::DynamoDB::Errors::ServiceError => e
puts("Couldn't delete movie #{title}. Here's why:")
puts("\t#{e.code}: #{e.message}")
raise
end
```
+ For API details, see [DeleteItem](https://docs.aws.amazon.com/goto/SdkForRubyV3/dynamodb-2012-08-10/DeleteItem) in *AWS SDK for Ruby API Reference*.
### `DeleteTable`
The following code example shows how to use `DeleteTable`.
**SDK for Ruby**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby/example_code/dynamodb#code-examples).
```
# Encapsulates an Amazon DynamoDB table of movie data.
class Scaffold
attr_reader :dynamo_resource, :table_name, :table
def initialize(table_name)
client = Aws::DynamoDB::Client.new(region: 'us-east-1')
@dynamo_resource = Aws::DynamoDB::Resource.new(client: client)
@table_name = table_name
@table = nil
@logger = Logger.new($stdout)
@logger.level = Logger::DEBUG
end
# Deletes the table.
def delete_table
@table.delete
@table = nil
rescue Aws::DynamoDB::Errors::ServiceError => e
puts("Couldn't delete table. Here's why:")
puts("\t#{e.code}: #{e.message}")
raise
end
```
+ For API details, see [DeleteTable](https://docs.aws.amazon.com/goto/SdkForRubyV3/dynamodb-2012-08-10/DeleteTable) in *AWS SDK for Ruby API Reference*.
### `DescribeTable`
The following code example shows how to use `DescribeTable`.
**SDK for Ruby**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby/example_code/dynamodb#code-examples).
```
# Encapsulates an Amazon DynamoDB table of movie data.
class Scaffold
attr_reader :dynamo_resource, :table_name, :table
def initialize(table_name)
client = Aws::DynamoDB::Client.new(region: 'us-east-1')
@dynamo_resource = Aws::DynamoDB::Resource.new(client: client)
@table_name = table_name
@table = nil
@logger = Logger.new($stdout)
@logger.level = Logger::DEBUG
end
# Determines whether a table exists. As a side effect, stores the table in
# a member variable.
#
# @param table_name [String] The name of the table to check.
# @return [Boolean] True when the table exists; otherwise, False.
def exists?(table_name)
@dynamo_resource.client.describe_table(table_name: table_name)
@logger.debug("Table #{table_name} exists")
rescue Aws::DynamoDB::Errors::ResourceNotFoundException
@logger.debug("Table #{table_name} doesn't exist")
false
rescue Aws::DynamoDB::Errors::ServiceError => e
puts("Couldn't check for existence of #{table_name}:\n")
puts("\t#{e.code}: #{e.message}")
raise
end
```
+ For API details, see [DescribeTable](https://docs.aws.amazon.com/goto/SdkForRubyV3/dynamodb-2012-08-10/DescribeTable) in *AWS SDK for Ruby API Reference*.
### `ExecuteStatement`
The following code example shows how to use `ExecuteStatement`.
**SDK for Ruby**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby/example_code/dynamodb#code-examples).
Select a single item using PartiQL.
```
class DynamoDBPartiQLSingle
attr_reader :dynamo_resource, :table
def initialize(table_name)
client = Aws::DynamoDB::Client.new(region: 'us-east-1')
@dynamodb = Aws::DynamoDB::Resource.new(client: client)
@table = @dynamodb.table(table_name)
end
# Gets a single record from a table using PartiQL.
# Note: To perform more fine-grained selects,
# use the Client.query instance method instead.
#
# @param title [String] The title of the movie to search.
# @return [Aws::DynamoDB::Types::ExecuteStatementOutput]
def select_item_by_title(title)
request = {
statement: "SELECT * FROM \"#{@table.name}\" WHERE title=?",
parameters: [title]
}
@dynamodb.client.execute_statement(request)
end
```
Update a single item using PartiQL.
```
class DynamoDBPartiQLSingle
attr_reader :dynamo_resource, :table
def initialize(table_name)
client = Aws::DynamoDB::Client.new(region: 'us-east-1')
@dynamodb = Aws::DynamoDB::Resource.new(client: client)
@table = @dynamodb.table(table_name)
end
# Updates a single record from a table using PartiQL.
#
# @param title [String] The title of the movie to update.
# @param year [Integer] The year the movie was released.
# @param rating [Float] The new rating to assign the title.
# @return [Aws::DynamoDB::Types::ExecuteStatementOutput]
def update_rating_by_title(title, year, rating)
request = {
statement: "UPDATE \"#{@table.name}\" SET info.rating=? WHERE title=? and year=?",
parameters: [{ "N": rating }, title, year]
}
@dynamodb.client.execute_statement(request)
end
```
Add a single item using PartiQL.
```
class DynamoDBPartiQLSingle
attr_reader :dynamo_resource, :table
def initialize(table_name)
client = Aws::DynamoDB::Client.new(region: 'us-east-1')
@dynamodb = Aws::DynamoDB::Resource.new(client: client)
@table = @dynamodb.table(table_name)
end
# Adds a single record to a table using PartiQL.
#
# @param title [String] The title of the movie to update.
# @param year [Integer] The year the movie was released.
# @param plot [String] The plot of the movie.
# @param rating [Float] The new rating to assign the title.
# @return [Aws::DynamoDB::Types::ExecuteStatementOutput]
def insert_item(title, year, plot, rating)
request = {
statement: "INSERT INTO \"#{@table.name}\" VALUE {'title': ?, 'year': ?, 'info': ?}",
parameters: [title, year, { 'plot': plot, 'rating': rating }]
}
@dynamodb.client.execute_statement(request)
end
```
Delete a single item using PartiQL.
```
class DynamoDBPartiQLSingle
attr_reader :dynamo_resource, :table
def initialize(table_name)
client = Aws::DynamoDB::Client.new(region: 'us-east-1')
@dynamodb = Aws::DynamoDB::Resource.new(client: client)
@table = @dynamodb.table(table_name)
end
# Deletes a single record from a table using PartiQL.
#
# @param title [String] The title of the movie to update.
# @param year [Integer] The year the movie was released.
# @return [Aws::DynamoDB::Types::ExecuteStatementOutput]
def delete_item_by_title(title, year)
request = {
statement: "DELETE FROM \"#{@table.name}\" WHERE title=? and year=?",
parameters: [title, year]
}
@dynamodb.client.execute_statement(request)
end
```
+ For API details, see [ExecuteStatement](https://docs.aws.amazon.com/goto/SdkForRubyV3/dynamodb-2012-08-10/ExecuteStatement) in *AWS SDK for Ruby API Reference*.
### `GetItem`
The following code example shows how to use `GetItem`.
**SDK for Ruby**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby/example_code/dynamodb#code-examples).
```
class DynamoDBBasics
attr_reader :dynamo_resource, :table
def initialize(table_name)
client = Aws::DynamoDB::Client.new(region: 'us-east-1')
@dynamo_resource = Aws::DynamoDB::Resource.new(client: client)
@table = @dynamo_resource.table(table_name)
end
# Gets movie data from the table for a specific movie.
#
# @param title [String] The title of the movie.
# @param year [Integer] The release year of the movie.
# @return [Hash] The data about the requested movie.
def get_item(title, year)
@table.get_item(key: { 'year' => year, 'title' => title })
rescue Aws::DynamoDB::Errors::ServiceError => e
puts("Couldn't get movie #{title} (#{year}) from table #{@table.name}:\n")
puts("\t#{e.code}: #{e.message}")
raise
end
```
+ For API details, see [GetItem](https://docs.aws.amazon.com/goto/SdkForRubyV3/dynamodb-2012-08-10/GetItem) in *AWS SDK for Ruby API Reference*.
### `ListTables`
The following code example shows how to use `ListTables`.
**SDK for Ruby**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/dynamodb#code-examples).
Determine whether a table exists.
```
# Encapsulates an Amazon DynamoDB table of movie data.
class Scaffold
attr_reader :dynamo_resource, :table_name, :table
def initialize(table_name)
client = Aws::DynamoDB::Client.new(region: 'us-east-1')
@dynamo_resource = Aws::DynamoDB::Resource.new(client: client)
@table_name = table_name
@table = nil
@logger = Logger.new($stdout)
@logger.level = Logger::DEBUG
end
# Determines whether a table exists. As a side effect, stores the table in
# a member variable.
#
# @param table_name [String] The name of the table to check.
# @return [Boolean] True when the table exists; otherwise, False.
def exists?(table_name)
@dynamo_resource.client.describe_table(table_name: table_name)
@logger.debug("Table #{table_name} exists")
rescue Aws::DynamoDB::Errors::ResourceNotFoundException
@logger.debug("Table #{table_name} doesn't exist")
false
rescue Aws::DynamoDB::Errors::ServiceError => e
puts("Couldn't check for existence of #{table_name}:\n")
puts("\t#{e.code}: #{e.message}")
raise
end
```
+ For API details, see [ListTables](https://docs.aws.amazon.com/goto/SdkForRubyV3/dynamodb-2012-08-10/ListTables) in *AWS SDK for Ruby API Reference*.
### `PutItem`
The following code example shows how to use `PutItem`.
**SDK for Ruby**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby/example_code/dynamodb#code-examples).
```
class DynamoDBBasics
attr_reader :dynamo_resource, :table
def initialize(table_name)
client = Aws::DynamoDB::Client.new(region: 'us-east-1')
@dynamo_resource = Aws::DynamoDB::Resource.new(client: client)
@table = @dynamo_resource.table(table_name)
end
# Adds a movie to the table.
#
# @param movie [Hash] The title, year, plot, and rating of the movie.
def add_item(movie)
@table.put_item(
item: {
'year' => movie[:year],
'title' => movie[:title],
'info' => { 'plot' => movie[:plot], 'rating' => movie[:rating] }
}
)
rescue Aws::DynamoDB::Errors::ServiceError => e
puts("Couldn't add movie #{title} to table #{@table.name}. Here's why:")
puts("\t#{e.code}: #{e.message}")
raise
end
```
+ For API details, see [PutItem](https://docs.aws.amazon.com/goto/SdkForRubyV3/dynamodb-2012-08-10/PutItem) in *AWS SDK for Ruby API Reference*.
### `Query`
The following code example shows how to use `Query`.
**SDK for Ruby**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby/example_code/dynamodb#code-examples).
```
class DynamoDBBasics
attr_reader :dynamo_resource, :table
def initialize(table_name)
client = Aws::DynamoDB::Client.new(region: 'us-east-1')
@dynamo_resource = Aws::DynamoDB::Resource.new(client: client)
@table = @dynamo_resource.table(table_name)
end
# Queries for movies that were released in the specified year.
#
# @param year [Integer] The year to query.
# @return [Array] The list of movies that were released in the specified year.
def query_items(year)
response = @table.query(
key_condition_expression: '#yr = :year',
expression_attribute_names: { '#yr' => 'year' },
expression_attribute_values: { ':year' => year }
)
rescue Aws::DynamoDB::Errors::ServiceError => e
puts("Couldn't query for movies released in #{year}. Here's why:")
puts("\t#{e.code}: #{e.message}")
raise
else
response.items
end
```
+ For API details, see [Query](https://docs.aws.amazon.com/goto/SdkForRubyV3/dynamodb-2012-08-10/Query) in *AWS SDK for Ruby API Reference*.
### `Scan`
The following code example shows how to use `Scan`.
**SDK for Ruby**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby/example_code/dynamodb#code-examples).
```
class DynamoDBBasics
attr_reader :dynamo_resource, :table
def initialize(table_name)
client = Aws::DynamoDB::Client.new(region: 'us-east-1')
@dynamo_resource = Aws::DynamoDB::Resource.new(client: client)
@table = @dynamo_resource.table(table_name)
end
# 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 [Hash] The range of years to retrieve.
# @return [Array] The list of movies released in the specified years.
def scan_items(year_range)
movies = []
scan_hash = {
filter_expression: '#yr between :start_yr and :end_yr',
projection_expression: '#yr, title, info.rating',
expression_attribute_names: { '#yr' => 'year' },
expression_attribute_values: {
':start_yr' => year_range[:start], ':end_yr' => year_range[:end]
}
}
done = false
start_key = nil
until done
scan_hash[:exclusive_start_key] = start_key unless start_key.nil?
response = @table.scan(scan_hash)
movies.concat(response.items) unless response.items.empty?
start_key = response.last_evaluated_key
done = start_key.nil?
end
rescue Aws::DynamoDB::Errors::ServiceError => e
puts("Couldn't scan for movies. Here's why:")
puts("\t#{e.code}: #{e.message}")
raise
else
movies
end
```
+ For API details, see [Scan](https://docs.aws.amazon.com/goto/SdkForRubyV3/dynamodb-2012-08-10/Scan) in *AWS SDK for Ruby API Reference*.
### `UpdateItem`
The following code example shows how to use `UpdateItem`.
**SDK for Ruby**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby/example_code/dynamodb#code-examples).
```
class DynamoDBBasics
attr_reader :dynamo_resource, :table
def initialize(table_name)
client = Aws::DynamoDB::Client.new(region: 'us-east-1')
@dynamo_resource = Aws::DynamoDB::Resource.new(client: client)
@table = @dynamo_resource.table(table_name)
end
# Updates rating and plot data for a movie in the table.
#
# @param movie [Hash] The title, year, plot, rating of the movie.
def update_item(movie)
response = @table.update_item(
key: { 'year' => movie[:year], 'title' => movie[:title] },
update_expression: 'set info.rating=:r',
expression_attribute_values: { ':r' => movie[:rating] },
return_values: 'UPDATED_NEW'
)
rescue Aws::DynamoDB::Errors::ServiceError => e
puts("Couldn't update movie #{movie[:title]} (#{movie[:year]}) in table #{@table.name}\n")
puts("\t#{e.code}: #{e.message}")
raise
else
response.attributes
end
```
+ For API details, see [UpdateItem](https://docs.aws.amazon.com/goto/SdkForRubyV3/dynamodb-2012-08-10/UpdateItem) in *AWS SDK for Ruby API Reference*.
## Scenarios
### Query a table by using batches of PartiQL statements
The following code example shows how to:
+ Get a batch of items by running multiple SELECT statements.
+ Add a batch of items by running multiple INSERT statements.
+ Update a batch of items by running multiple UPDATE statements.
+ Delete a batch of items by running multiple DELETE statements.
**SDK for Ruby**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby/example_code/dynamodb#code-examples).
Run a scenario that creates a table and runs batch PartiQL queries.
```
table_name = "doc-example-table-movies-partiql-#{rand(10**4)}"
scaffold = Scaffold.new(table_name)
sdk = DynamoDBPartiQLBatch.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, 'Populate DynamoDB table with movie data.')
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(3, 'Select a batch of items from the movies table.')
puts "Let's select some popular movies for side-by-side comparison."
response = sdk.batch_execute_select([['Mean Girls', 2004], ['Goodfellas', 1977], ['The Prancing of the Lambs', 2005]])
puts("Items selected: #{response['responses'].length}\n")
print "\nDone!\n".green
new_step(4, 'Delete a batch of items from the movies table.')
sdk.batch_execute_write([['Mean Girls', 2004], ['Goodfellas', 1977], ['The Prancing of the Lambs', 2005]])
print "\nDone!\n".green
new_step(5, 'Delete the table.')
return unless scaffold.exists?(table_name)
scaffold.delete_table
end
```
+ For API details, see [BatchExecuteStatement](https://docs.aws.amazon.com/goto/SdkForRubyV3/dynamodb-2012-08-10/BatchExecuteStatement) in *AWS SDK for Ruby API Reference*.
### Query a table using PartiQL
The following code example shows how to:
+ Get an item by running a SELECT statement.
+ Add an item by running an INSERT statement.
+ Update an item by running an UPDATE statement.
+ Delete an item by running a DELETE statement.
**SDK for Ruby**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby/example_code/dynamodb#code-examples).
Run a scenario that creates a table and runs PartiQL queries.
```
table_name = "doc-example-table-movies-partiql-#{rand(10**8)}"
scaffold = Scaffold.new(table_name)
sdk = DynamoDBPartiQLSingle.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, 'Populate DynamoDB table with movie data.')
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(3, 'Select a single item from the movies table.')
response = sdk.select_item_by_title('Star Wars')
puts("Items selected for title 'Star Wars': #{response.items.length}\n")
print response.items.first.to_s.yellow
print "\n\nDone!\n".green
new_step(4, 'Update a single item from the movies table.')
puts "Let's correct the rating on The Big Lebowski to 10.0."
sdk.update_rating_by_title('The Big Lebowski', 1998, 10.0)
print "\nDone!\n".green
new_step(5, 'Delete a single item from the movies table.')
puts "Let's delete The Silence of the Lambs because it's just too scary."
sdk.delete_item_by_title('The Silence of the Lambs', 1991)
print "\nDone!\n".green
new_step(6, 'Insert a new item into the movies table.')
puts "Let's create a less-scary movie called The Prancing of the Lambs."
sdk.insert_item('The Prancing of the Lambs', 2005, 'A movie about happy livestock.', 5.0)
print "\nDone!\n".green
new_step(7, 'Delete the table.')
return unless scaffold.exists?(table_name)
scaffold.delete_table
end
```
+ For API details, see [ExecuteStatement](https://docs.aws.amazon.com/goto/SdkForRubyV3/dynamodb-2012-08-10/ExecuteStatement) in *AWS SDK for Ruby API Reference*.
## Serverless examples
### Invoke a Lambda function from a DynamoDB trigger
The following code example shows how to implement a Lambda function that receives an event triggered by receiving records from a DynamoDB stream. The function retrieves the DynamoDB payload and logs the record contents.
**SDK for Ruby**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Serverless examples](https://github.com/aws-samples/serverless-snippets/tree/main/integration-ddb-to-lambda) repository.
Consuming a DynamoDB event with Lambda using Ruby.
```
def lambda_handler(event:, context:)
return 'received empty event' if event['Records'].empty?
event['Records'].each do |record|
log_dynamodb_record(record)
end
"Records processed: #{event['Records'].length}"
end
def log_dynamodb_record(record)
puts record['eventID']
puts record['eventName']
puts "DynamoDB Record: #{JSON.generate(record['dynamodb'])}"
end
```
### Reporting batch item failures for Lambda functions with a DynamoDB trigger
The following code example shows how to implement partial batch response for Lambda functions that receive events from a DynamoDB stream. The function reports the batch item failures in the response, signaling to Lambda to retry those messages later.
**SDK for Ruby**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Serverless examples](https://github.com/aws-samples/serverless-snippets/tree/main/integration-ddb-to-lambda-with-batch-item-handling) repository.
Reporting DynamoDB batch item failures with Lambda using Ruby.
```
def lambda_handler(event:, context:)
records = event["Records"]
cur_record_sequence_number = ""
records.each do |record|
begin
# Process your record
cur_record_sequence_number = record["dynamodb"]["SequenceNumber"]
rescue StandardError => e
# Return failed record's sequence number
return {"batchItemFailures" => [{"itemIdentifier" => cur_record_sequence_number}]}
end
end
{"batchItemFailures" => []}
end
```