AWS SDK for Ruby 操作 DynamoDB 完整实战指南：从建表、增删改查到 PartiQL

• 示例工程
• 教程
• 后端

本指南以 aws-doc-sdk-examples 仓库中 ruby/example_code/dynamodb/README.md 为核心，系统讲解如何使用 AWS SDK for Ruby（v3）操作 Amazon DynamoDB。你将掌握「Hello DynamoDB」入门示例、基于电影数据表的全套基础操作（建表、批量写入、Put/Get/Update/Delete/Query/Scan），以及用 PartiQL 进行单条与批量 SQL 式增删改查的完整实现与运行方法，并了解对应的 RSpec 集成测试。

概述：本目录示例能做什么

DynamoDB 是全托管的 NoSQL 数据库服务，以快速且可预测的性能与无缝横向扩展为特点。本目录中的 Ruby 示例覆盖三类典型用法：

• 入门（Get started）：Hello DynamoDB，调用ListTables列出当前账号下的所有表；
• 基础操作（Basics）：围绕「电影数据表」完成建表、写入、查询、扫描、删除等核心单操作；
• 场景（Scenarios）：使用 PartiQL（DynamoDB 的 SQL 兼容查询语言）分别演示单条语句与批量语句两种数据访问方式。

所有示例基于 AWS SDK for Ruby Version 3，使用aws-sdk-dynamodb官方 Gem，可在 ruby/example_code/dynamodb 目录下直接查看与运行。

环境准备（Prerequisites）

正式运行示例前，需要完成以下准备：

1. AWS 账号与本地凭证：参照仓库根目录 README 的全局前提条件创建账号并配置本地 AWS 凭证；
2. Ruby 版本：仓库测试环境使用 Ruby 3.1.2，可用ruby -v检查本机版本；
3. 安装依赖：在ruby目录下执行：

gem install bundler bundle install

bundle install会按 ruby/Gemfile 解析并安装aws-sdk-dynamodb、rspec、cli-ui、zip等依赖。如需使用其他 Ruby 版本，可修改或移除 Gemfile 中的ruby "3.1.2"约束。

⚠ 费用与安全提醒

• 运行这些代码可能产生 AWS 账号费用；运行测试同样可能产生费用；
• 建议遵循最小权限原则（least privilege），仅授予完成任务所需的最低 IAM 权限；
• 这些示例并未在所有 AWS Region 逐一测试，请确认目标区域支持 DynamoDB。

示例文件与 API 总览

目录结构如下，每个文件对应 README 中列出的 API 操作：

ruby/example_code/dynamodb/ ├── hello/ # Hello DynamoDB 入门（ListTables） │ └── hello_dynamodb.rb ├── basics/ # 基础操作封装与完整场景 │ ├── dynamodb_basics.rb # PutItem/GetItem/UpdateItem/Query/Scan/DeleteItem │ ├── scenario_getting_started_dynamodb.rb │ └── spec/scenario_getting_started_dynamodb_spec.rb ├── partiql/ # PartiQL 单条与批量场景 │ ├── partiql_single.rb # ExecuteStatement（SELECT/UPDATE/DELETE/INSERT） │ ├── partiql_batch.rb # BatchExecuteStatement（SELECT/DELETE 批量） │ ├── scenario_partiql_single.rb │ ├── scenario_partiql_batch.rb │ └── spec/ # 两个场景的 RSpec 测试 ├── scaffold.rb # CreateTable/DescribeTable/BatchWriteItem/DeleteTable └── README.md

各 API 在 README 中的定位：

Hello DynamoDB：用 ListTables 快速验证 SDK 配置

这是最简单的入门示例，仅做一件事：列出当前 AWS 账号下的所有 DynamoDB 表。核心实现在 hello_dynamodb.rb：

require 'aws-sdk-dynamodb' require 'logger' class DynamoDBManager def initialize(client) @client = client @logger = Logger.new($stdout) end 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

关键点：

• Aws::DynamoDB::Client.new会从环境变量、~/.aws/credentials或 IAM 角色中读取凭证；
• list_tables(limit: 10)限制单次返回条数，并通过each_page自动翻页，最终输出全部表名或「没有任何表」的提示。

运行命令：

ruby hello/hello_dynamodb.rb

基础场景：电影数据表的全生命周期

README 中「Learn the basics」对应的入口是 scaffold.rb，它演示了从建表到删表的完整流程，并可对照 scenario_getting_started_dynamodb.rb 中的交互式驱动脚本查看每一步的串联方式。该场景的能力清单：

• 创建一张可存放电影数据的表；
• 向表中写入、读取、更新单部电影；
• 从示例 JSON 文件批量写入电影数据；
• 按年份查询（Query）某年上映的电影；
• 按年份区间扫描（Scan）电影；
• 删除单部电影，最后删除整张表。

建表与表结构设计（CreateTable）

scaffold.rb 中的create_table展示了典型的分区键 + 排序键设计：

@table = @dynamo_resource.create_table( table_name: table_name, key_schema: [ { attribute_name: 'year', key_type: 'HASH' }, # 分区键 { attribute_name: 'title', key_type: 'RANGE' } # 排序键 ], 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)

要点说明：

• 键设计：以电影上映年份year（数字 N）作为分区键、标题title（字符串 S）作为排序键，同一年的多部电影可通过title排序；
• 计费模式：billing_mode: 'PAY_PER_REQUEST'按实际读写量计费，无需预置容量，适合示例场景；
• 同步等待：wait_until(:table_exists, ...)会轮询直到表状态变为ACTIVE，避免后续写入报ResourceNotFoundException；
• 配套的exists?方法（对应DescribeTable）通过describe_table判断表是否存在，并捕获Aws::DynamoDB::Errors::ResourceNotFoundException返回false。

批量写入电影数据（BatchWriteItem）

write_batch 以每次 25 条的方式分批调用batch_write_item：

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 end

• 每次BatchWriteItem最多写入 25 个put_request，超过部分必须分批发送；
• 电影数据通过 fetch_movie_data 获取：优先读取本地moviedata.json，不存在时从 DynamoDB 开发者指南下载moviedata.zip并解压，最终只保留前 250 条以减少示例运行时间。

单条记录的增删改查（PutItem / GetItem / UpdateItem / DeleteItem）

basics/dynamodb_basics.rb 封装了单条记录操作。其构造函数同样使用Aws::DynamoDB::Client.new(region: 'us-east-1')显式指定区域，并通过Aws::DynamoDB::Resource拿到表的引用。

写入单条（PutItem），见 add_item：

@table.put_item( item: { 'year' => movie[:year], 'title' => movie[:title], 'info' => { 'plot' => movie[:plot], 'rating' => movie[:rating] } } )

读取单条（GetItem），见 get_item：使用主键{ 'year' => year, 'title' => title }精确定位记录。

更新单条（UpdateItem），见 update_item：使用 Update 表达式只更新info.rating字段，并借助expression_attribute_values做参数化：

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' )

return_values: 'UPDATED_NEW'让返回结果只包含更新后的属性。

删除单条（DeleteItem），见 delete_item：同样以主键定位删除。

条件查询与区间扫描（Query / Scan）

Query（query_items）按分区键查询某年全部电影，是访问 DynamoDB 数据的高效方式：

response = @table.query( key_condition_expression: '#yr = :year', expression_attribute_names: { '#yr' => 'year' }, expression_attribute_values: { ':year' => year } )

• #yr是属性名占位符（year是保留字，必须用表达式属性名转义）；
• :year是属性值占位符，防止参数注入。

Scan（scan_items）使用BETWEEN过滤表达式扫描年份区间，并通过投影表达式只返回必要字段，同时手动处理分页：

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

last_evaluated_key非空表示还有下一页，将其作为下一轮exclusive_start_key继续扫描，直到取完全部结果。

交互式场景脚本

scenario_getting_started_dynamodb.rb 将上述操作编排为 8 个交互步骤（建表、添加记录、更新评分、读取记录、批量写入、按年查询、区间扫描、删除记录并删表），使用cli/ui提示输入电影信息，并在每次请求前弹出计费与安全确认。表名通过doc-example-table-movies-#{rand(10**4)}随机生成以避免冲突。运行：

ruby scaffold.rb

PartiQL 场景：用 SQL 兼容语句访问 DynamoDB

PartiQL 是 DynamoDB 内置的 SQL 兼容查询语言，可以用SELECT/INSERT/UPDATE/DELETE替代底层 API。本目录提供单条与批量两个场景。

单条 PartiQL 操作（ExecuteStatement）

partiql_single.rb 中的四个方法全部通过client.execute_statement发送语句，?作为参数占位符：

SELECT（select_item_by_title）：

request = { statement: "SELECT * FROM \"#{@table.name}\" WHERE title=?", parameters: [title] } @dynamodb.client.execute_statement(request)

UPDATE（update_rating_by_title），注意评分以{ "N": rating }显式声明数字类型：

statement: "UPDATE \"#{@table.name}\" SET info.rating=? WHERE title=? and year=?", parameters: [{ "N": rating }, title, year]

DELETE（delete_item_by_title）：

statement: "DELETE FROM \"#{@table.name}\" WHERE title=? and year=?", parameters: [title, year]

INSERT（insert_item），文档（Item）用花括号字面量表示，info作为嵌套文档传入：

statement: "INSERT INTO \"#{@table.name}\" VALUE {'title': ?, 'year': ?, 'info': ?}", parameters: [title, year, { 'plot': plot, 'rating': rating }]

值得注意：当需要更细粒度的查询（例如按键范围、排序、分页）时，源码注释明确建议改用Client.query实例方法而非 PartiQL 的SELECT。

对应场景脚本 scenario_partiql_single.rb 的演示流程为：建表 → 批量载入电影数据 → 查询Star Wars→ 把The Big Lebowski（1998）的评分改为 10.0 → 删除The Silence of the Lambs（1991）→ 插入新电影The Prancing of the Lambs→ 删除整张表。运行：

ruby partiql/scenario_partiql_single.rb

批量 PartiQL 操作（BatchExecuteStatement）

partiql_batch.rb 演示如何用batch_execute_statement一次提交多条语句：

批量读取（batch_execute_select）：对多部电影各生成一条SELECT，一起发送：

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 })

批量删除（batch_execute_write）：用同样的方式批量生成DELETE FROM语句并一次性执行。

场景脚本 scenario_partiql_batch.rb 的流程为：建表 → 载入数据 → 批量查询Mean Girls(2004)、Goodfellas(1977)、The Prancing of the Lambs(2005) → 批量删除这三条记录 → 删除表。运行：

ruby partiql/scenario_partiql_batch.rb

运行测试（Tests）

⚠ 运行测试可能产生 AWS 账号费用。测试说明详见 ruby 目录 README 的 Tests 小节。

测试使用 RSpec 编写，位于spec/下，均标注integ: true标记为集成测试（需要真实 AWS 环境）：

• basics/spec/scenario_getting_started_dynamodb_spec.rb：覆盖建表、批量写入（断言movie_data.length > 200）、GetItem（读取12 Years a Slave并断言评分为 7）、PutItem、UpdateItem（评分更新为 8 后可读回）、Query（1999 年结果多于 1 条）、Scan（1989–1990 区间有结果）以及最终删表；
• partiql/spec/scenario_partiql_single_spec.rb：验证 PartiQL 单条场景——查询Star Wars能返回至少 1 条且标题匹配、更新The Big Lebowski评分后能读回 10.0、删除The Silence of the Lambs后查不到该条、插入The Prancing of the Lambs后能查到且info字段存在；
• partiql/spec/scenario_partiql_batch_spec.rb：验证批量查询与批量删除行为。

在ruby目录下用 RSpec 运行（示例）：

bundle exec rspec example_code/dynamodb/basics/spec bundle exec rspec example_code/dynamodb/partiql/spec

代码组织与学习建议

• 本目录代码按「封装类 + 场景脚本」的层次组织：Scaffold、DynamoDBBasics、DynamoDBPartiQLSingle、DynamoDBPartiQLBatch是可复用的操作封装，scenario_*.rb是带交互输出的演示入口，便于对比同一操作在底层 API 与 PartiQL 两种写法下的差异；
• 所有封装均捕获Aws::DynamoDB::Errors::ServiceError并输出e.code与e.message，便于排查权限、资源不存在等常见问题；
• 动手实践时建议：先运行hello_dynamodb.rb验证凭证与 SDK 配置，再运行scaffold.rb观察全生命周期，最后分别运行两个 PartiQL 场景对比单条与批量写法的取舍。

附加资源

• 本目录 README：ruby/example_code/dynamodb/README.md
• Ruby SDK 示例总入口与依赖安装说明：ruby/README.md
• Ruby SDK 其他服务示例：ruby/example_code
• 仓库贡献指南：CONTRIBUTING.md

本文内容基于 aws-doc-sdk-examples 仓库中 ruby/example_code/dynamodb 目录下的文档与源码整理，代码版权归 Amazon.com, Inc. 或其关联方所有，遵循 Apache-2.0 许可。

• 示例工程
• 教程
• 后端