# DynamoDB に対する AWS SDK サポートの概要
次の図表は、AWS SDK を使用した Amazon DynamoDB アプリケーションの、プログラミングの概要を示しています。
![\[AWS SDK で DynamoDB を使用するためのプログラミングモデル。\]](http://docs.aws.amazon.com/ja_jp/amazondynamodb/latest/developerguide/images/SDKSupport.png)
1. 自分が使用するプログラミング言語用のための AWS SDK を使用して、アプリケーションを作成します。
1. 各 AWS SDK には、DynamoDB を操作するプログラミングインターフェイスが 1 つ以上用意されています。使用できるインターフェイスは、使用するプログラミング言語と AWS SDK によって異なります。オプションには以下が含まれます。
+ [DynamoDB で動作する低レベルインターフェイス](Programming.SDKs.Interfaces.md#Programming.SDKs.Interfaces.LowLevel)
+ [DynamoDB で動作するドキュメントインターフェイス](Programming.SDKs.Interfaces.md#Programming.SDKs.Interfaces.Document)
+ [DynamoDB で動作するオブジェクト永続性インターフェイス](Programming.SDKs.Interfaces.md#Programming.SDKs.Interfaces.Mapper)
+ [高レベルのインターフェイス](HigherLevelInterfaces.md)
1. AWS SDK は、低レベル DynamoDB API で使用する HTTP (S) リクエストを作成します。
1. AWS SDK は DynamoDB エンドポイントにリクエストを送信します。
1. DynamoDB がリクエストを実行します。リクエストが成功すると、DynamoDB は HTTP 200 レスポンスコード (OK) を返します。リクエストが失敗した場合は、DynamoDB は HTTP エラーコードとエラーメッセージを返します。
1. AWS SDK はレスポンスを処理し、アプリケーションに伝達します。
各 AWS SDK は、次のような重要なサービスをアプリケーションに提供します。
+ HTTP (S) リクエストのフォーマットと、リクエストパラメータのシリアル化。
+ リクエストごとの暗号化署名の生成。
+ DynamoDB エンドポイントへのリクエストの転送と、DynamoDB からのレスポンスの受信。
+ これらの応答からの結果の抽出。
+ エラーが発生した場合の基本的な再試行ロジックの実装。
これらのタスクでは、コードを記述する必要はありません。
**注記**
AWS SDK のインストール方法とドキュメントの詳細については、「[アマゾン ウェブ サービス用ツール](https://aws.amazon.com/tools)」を参照してください。
## AWS アカウントベースのエンドポイントの SDK サポート
AWS は、2024 年 9 月 4 日、SDK for Java V1 から、DynamoDB の AWS アカウントベースのエンドポイントの AWS SDK サポートをロールアウトします。これらの新しいエンドポイントは、高いパフォーマンスとスケーラビリティを AWS で確保するのに役立ちます。更新された SDK では、`https://(account-id).ddb.(region).amazonaws.com` 形式の新しいエンドポイントを自動的に使用します。
SDK クライアントの 1 つのインスタンスを使用して複数のアカウントにリクエストを行う場合、アプリケーションは接続を再利用する機会が少なくなります。AWS では、SDK クライアントインスタンスあたりの接続先のアカウント数を減らすようにアプリケーションを変更することをお勧めします。代わりに、「[AWS SDK およびツールリファレンスガイド](https://docs.aws.amazon.com/sdkref/latest/guide/feature-account-endpoints.html)」に記載されているように、`ACCOUNT_ID_ENDPOINT_MODE` 設定を使用してリージョンエンドポイントを引き続き使用するように SDK クライアントを設定することもできます。**
# DynamoDB で動作するプログラムインターフェイス
各 [AWS SDK](https://aws.amazon.com/tools) には、Amazon DynamoDB を操作するプログラミングインターフェイスが 1 つ以上用意されています。これらのインターフェイスは、シンプルな低レベルの DynamoDB ラッパーから、オブジェクト指向の永続レイヤーまで、多岐にわたります。使用可能なインターフェイスは、AWS SDK およびプログラミング言語によって異なります。
![\[DynamoDB を使用するためのさまざまな AWS SDK で利用可能なプログラミングインターフェイス。\]](http://docs.aws.amazon.com/ja_jp/amazondynamodb/latest/developerguide/images/SDKSupport.SDKInterfaces.png)
次のセクションでは、AWS SDK for Java を例として使用して、使用可能なインターフェイスをいくつかハイライトします。(すべてのインターフェイスが、どの AWS SDK でも使用できるわけではありません。)
**Topics**
+ [DynamoDB で動作する低レベルインターフェイス](#Programming.SDKs.Interfaces.LowLevel)
+ [DynamoDB で動作するドキュメントインターフェイス](#Programming.SDKs.Interfaces.Document)
+ [DynamoDB で動作するオブジェクト永続性インターフェイス](#Programming.SDKs.Interfaces.Mapper)
## DynamoDB で動作する低レベルインターフェイス
それぞれの言語特有の AWS SDK は、低レベルの DynamoDB API リクエストによく似たメソッドを持つ、Amazon DynamoDB 用の低レベルインターフェイスを提供します。
場合によっては [データ型記述子](Programming.LowLevelAPI.md#Programming.LowLevelAPI.DataTypeDescriptors) を使用して、文字列型の `S` や、数値型の `N` など、属性のデータ型を識別する必要があります。
**注記**
すべての言語特有の AWS SDK で、低レベルインターフェイスを使用できます。
次の Java プログラムは、AWS SDK for Java の低レベルインターフェイスを使用しています。
### 低レベルインターフェイスの例
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
import software.amazon.awssdk.services.dynamodb.model.GetItemRequest;
import java.util.HashMap;
import java.util.Map;
import java.util.Set;
/**
* 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
*
* To get an item from an Amazon DynamoDB table using the AWS SDK for Java V2,
* its better practice to use the
* Enhanced Client, see the EnhancedGetItem example.
*/
public class GetItem {
public static void main(String[] args) {
final String usage = """
Usage:
Where:
tableName - The Amazon DynamoDB table from which an item is retrieved (for example, Music3).\s
key - The key used in the Amazon DynamoDB table (for example, Artist).\s
keyval - The key value that represents the item to get (for example, Famous Band).
""";
if (args.length != 3) {
System.out.println(usage);
System.exit(1);
}
String tableName = args[0];
String key = args[1];
String keyVal = args[2];
System.out.format("Retrieving item \"%s\" from \"%s\"\n", keyVal, tableName);
Region region = Region.US_EAST_1;
DynamoDbClient ddb = DynamoDbClient.builder()
.region(region)
.build();
getDynamoDBItem(ddb, tableName, key, keyVal);
ddb.close();
}
public static void getDynamoDBItem(DynamoDbClient ddb, String tableName, String key, String keyVal) {
HashMap keyToGet = new HashMap<>();
keyToGet.put(key, AttributeValue.builder()
.s(keyVal)
.build());
GetItemRequest request = GetItemRequest.builder()
.key(keyToGet)
.tableName(tableName)
.build();
try {
// If there is no matching item, GetItem does not return any data.
Map returnedItem = ddb.getItem(request).item();
if (returnedItem.isEmpty())
System.out.format("No item found with the key %s!\n", key);
else {
Set 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());
}
}
} catch (DynamoDbException e) {
System.err.println(e.getMessage());
System.exit(1);
}
}
}
```
## DynamoDB で動作するドキュメントインターフェイス
多くの AWS SDK はドキュメントインターフェイスを備えており、テーブルやインデックスに対してデータプレーンオペレーション (作成、読み取り、更新、削除) を実行できます。ドキュメントインターフェイスでは、[データ型記述子](Programming.LowLevelAPI.md#Programming.LowLevelAPI.DataTypeDescriptors) を指定する必要はありません。データ型は、データ自体のセマンティクスによって暗示されています。これらの AWS SDK には、JSON ドキュメントとネイティブの Amazon DynamoDB データ型とを簡単に変換するメソッドも用意されています。
**注記**
ドキュメントインターフェイスは、AWS SDK for [Java](https://aws.amazon.com/sdk-for-java)、[.NET](https://aws.amazon.com/sdk-for-net)、[Node.js](https://aws.amazon.com/sdk-for-node-js)、および [JavaScript SDK](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/) で使用できます。
次の Java プログラムは、AWS SDK for Java のドキュメントインターフェイスを使用します。プログラムが `Music` テーブルを表す `Table` オブジェクトを作成し、そのオブジェクトに `GetItem` の使用を依頼して、曲を取得します。その後プログラムが、曲がリリースされた年を出力します。
`software.amazon.dynamodb.document.DynamoDB` クラスは DynamoDB ドキュメントインターフェイスを実装します。低レベルクライアント (`AmazonDynamoDB`) のラッパーとして、`DynamoDB` がどのような役割を果たすかに注目してください。
### ドキュメントインターフェイスの例
```
package com.amazonaws.codesamples.gsg;
import software.amazon.dynamodb.AmazonDynamoDB;
import software.amazon.dynamodb.AmazonDynamoDBClientBuilder;
import software.amazon.dynamodb.document.DynamoDB;
import software.amazon.dynamodb.document.GetItemOutcome;
import software.amazon.dynamodb.document.Table;
public class MusicDocumentDemo {
public static void main(String[] args) {
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB docClient = new DynamoDB(client);
Table table = docClient.getTable("Music");
GetItemOutcome outcome = table.getItemOutcome(
"Artist", "No One You Know",
"SongTitle", "Call Me Today");
int year = outcome.getItem().getInt("Year");
System.out.println("The song was released in " + year);
}
}
```
## DynamoDB で動作するオブジェクト永続性インターフェイス
一部の AWS SDK には、データプレーンオペレーションを直接実行しない、オブジェクト永続性インターフェイスが用意されています。代わりに、Amazon DynamoDB のテーブルとインデックスの項目を表すオブジェクトを作成し、それらのオブジェクトのみとやり取りを行います。これにより、データベースを意識するのではなく、オブジェクトを中心にコードを作成していくことができます。
**注記**
オブジェクト永続性インターフェイスは、AWS SDK for Java と for .NET で利用できます。詳細については、DynamoDB の「[DynamoDB の上位レベルのプログラミングインターフェイス](HigherLevelInterfaces.md)」を参照してください。
### オブジェクト永続性インターフェイスの例
```
import com.example.dynamodb.Customer;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedClient;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbTable;
import software.amazon.awssdk.enhanced.dynamodb.Key;
import software.amazon.awssdk.enhanced.dynamodb.TableSchema;
import software.amazon.awssdk.enhanced.dynamodb.model.GetItemEnhancedRequest;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
```
```
import com.example.dynamodb.Customer;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedClient;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbTable;
import software.amazon.awssdk.enhanced.dynamodb.Key;
import software.amazon.awssdk.enhanced.dynamodb.TableSchema;
import software.amazon.awssdk.enhanced.dynamodb.model.GetItemEnhancedRequest;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
/*
* Before running this code example, create an Amazon DynamoDB table named Customer with these columns:
* - id - the id of the record that is the key. Be sure one of the id values is `id101`
* - custName - the customer name
* - email - the email value
* - registrationDate - an instant value when the item was added to the table. These values
* need to be in the form of `YYYY-MM-DDTHH:mm:ssZ`, such as 2022-07-11T00:00:00Z
*
* Also, ensure that you have set up your development environment, including your credentials.
*
* For information, see this documentation topic:
*
* https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html
*/
public class EnhancedGetItem {
public static void main(String[] args) {
Region region = Region.US_EAST_1;
DynamoDbClient ddb = DynamoDbClient.builder()
.region(region)
.build();
DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
.dynamoDbClient(ddb)
.build();
getItem(enhancedClient);
ddb.close();
}
public static String getItem(DynamoDbEnhancedClient enhancedClient) {
Customer result = null;
try {
DynamoDbTable table = enhancedClient.table("Customer", TableSchema.fromBean(Customer.class));
Key key = Key.builder()
.partitionValue("id101").sortValue("tred@noserver.com")
.build();
// Get the item by using the key.
result = table.getItem(
(GetItemEnhancedRequest.Builder requestBuilder) -> requestBuilder.key(key));
System.out.println("******* The description value is " + result.getCustName());
} catch (DynamoDbException e) {
System.err.println(e.getMessage());
System.exit(1);
}
return result.getCustName();
}
}
```
# DynamoDB の上位レベルのプログラミングインターフェイス
AWS SDK は、Amazon DynamoDB を操作するための下位レベルのインターフェイスをアプリケーションに提供します。これらのクライアント側のクラスとメソッドは、下位レベルの DynamoDB API と直接対応しています。しかし、これは多くのデベロッパーにとって、複雑なデータ型をデータベーステーブル内の項目にマップする必要がある場合の接続性の悪さ、つまり*インピーダンスの不整合*の原因となります。下位レベルのデータベースインタフェースを使用するデベロッパーは、オブジェクトデータをデータベーステーブルに対して読み書きするためのメソッドを記述する必要があります。オブジェクトタイプとデータベーステーブルの組み合わせに、個別に対応するための余分なコードが、圧倒的な量になることもあります。
AWS SDK for Java および for .NET では、開発業務を簡素化するために、高度に抽象化されたインターフェイスが用意されています。DynamoDB の上位レベルのインターフェイスを使用すると、プログラム内のオブジェクトと、それらのオブジェクトのデータを格納するためのデータベーステーブル間の関係を定義できます。このマッピングを定義した後、`save`、`load`、`delete` などの単純なオブジェクトメソッドを呼び出すと、ユーザーに代わって、基盤となる下位レベルの DynamoDB オペレーションの呼び出しが自動化されます。これにより、データベースを意識するのではなく、オブジェクトを中心にコードを作成していくことができます。
DynamoDB の上位レベルのプログラミングインターフェイスは、Java および .NET 用の AWS SDK で使用できます。
**Java**:
+ [Java 1.x: DynamoDBMapper](DynamoDBMapper.md)
+ [Java 2.x: DynamoDB 拡張クライアント](DynamoDBEnhanced.md)
**.NET**
+ [DynamoDB での .NET ドキュメントの操作](DotNetSDKMidLevel.md)
+ [.NET オブジェクト永続性モデルと DynamoDB の使用](DotNetSDKHighLevel.md)
# Java 1.x: DynamoDBMapper
**注記**
SDK for Java には、1.x と 2.x の 2 つのバージョンがあります。1.x のサポート終了は、2024 年 1 月 12 日に[発表](https://aws.amazon.com/blogs/developer/announcing-end-of-support-for-aws-sdk-for-java-v1-x-on-december-31-2025/)されました。サポートは 2025 年 12 月 31 日に終了します。新規開発には、2.x を使用することを強くお勧めします。
AWS SDK for Java には `DynamoDBMapper` クラスが用意されているため、クライアント側のクラスを Amazon DynamoDB テーブルにマッピングできます。`DynamoDBMapper` を使用するには、DynamoDB テーブル内の項目と、それが対応するコード内のオブジェクトインスタンスの間での関係性を定義します。`DynamoDBMapper` クラスを使用すると、項目に対する作成、読み込み、更新、削除 (CRUD) の各オペレーションの実行、およびテーブルに対するクエリやスキャンを行うことができます。
**Topics**
+ [DynamoDBMapper クラス](DynamoDBMapper.Methods.md)
+ [DynamoDBMapper for Java でサポートされるデータ型](DynamoDBMapper.DataTypes.md)
+ [DynamoDB 用の Java アノテーション](DynamoDBMapper.Annotations.md)
+ [DynamoDBMapper のオプションの構成設定](DynamoDBMapper.OptionalConfig.md)
+ [DynamoDB およびバージョン番号を使用した楽観的ロック](DynamoDBMapper.OptimisticLocking.md)
+ [DynamoDB での任意のデータのマッピング](DynamoDBMapper.ArbitraryDataMapping.md)
+ [DynamoDBMapper の例](DynamoDBMapper.Examples.md)
**注記**
`DynamoDBMapper`クラスでは、テーブルを作成、更新、または削除することはできません。これらのタスクを実行するには、代わりに SDK for Java の下位レベルインターフェイスを使用します。
SDK for Java には、クラスをテーブルにマッピングするための、一連のアノテーションタイプが用意されています。たとえば、パーティションキーとして `ProductCatalog` を含む `Id` テーブルがあるとします。
```
ProductCatalog(Id, ...)
```
次の Java コードに示すように、クライアントアプリケーション内のクラスを `ProductCatalog` テーブルにマッピングすることができます。このコードでは、`CatalogItem` という名前の Plain Old Java Object (POJO) を定義しています。このオブジェクトは、アノテーションを使用して、オブジェクトフィールドを DynamoDB の属性名にマッピングします。
**Example**
```
package com.amazonaws.codesamples;
import java.util.Set;
import software.amazon.dynamodb.datamodeling.DynamoDBAttribute;
import software.amazon.dynamodb.datamodeling.DynamoDBHashKey;
import software.amazon.dynamodb.datamodeling.DynamoDBIgnore;
import software.amazon.dynamodb.datamodeling.DynamoDBTable;
@DynamoDBTable(tableName="ProductCatalog")
public class CatalogItem {
private Integer id;
private String title;
private String ISBN;
private Set bookAuthors;
private String someProp;
@DynamoDBHashKey(attributeName="Id")
public Integer getId() { return id; }
public void setId(Integer id) {this.id = id; }
@DynamoDBAttribute(attributeName="Title")
public String getTitle() {return title; }
public void setTitle(String title) { this.title = title; }
@DynamoDBAttribute(attributeName="ISBN")
public String getISBN() { return ISBN; }
public void setISBN(String ISBN) { this.ISBN = ISBN; }
@DynamoDBAttribute(attributeName="Authors")
public Set getBookAuthors() { return bookAuthors; }
public void setBookAuthors(Set bookAuthors) { this.bookAuthors = bookAuthors; }
@DynamoDBIgnore
public String getSomeProp() { return someProp; }
public void setSomeProp(String someProp) { this.someProp = someProp; }
}
```
前述のコードでは、`@DynamoDBTable` 注釈によって、`CatalogItem` クラスが `ProductCatalog` テーブルにマッピングされています。個々のクラスインスタンスは、テーブル内の項目として格納できます。クラス定義では、`@DynamoDBHashKey` 注釈によって `Id` プロパティがプライマリキーにマッピングされます。
デフォルトでは、クラスプロパティはテーブル内の同じ名前属性にマッピングされます。プロパティ `Title` および `ISBN` は、テーブル内の同じ名前属性にマッピングされます。
DynamoDB の属性名がクラスで宣言されたプロパティ名と一致する場合、`@DynamoDBAttribute` アノテーションの使用はオプションです。これらの名前が異なる場合には、`attributeName` パラメータを指定しながらこのアノテーションを使用し、プロパティが DynamoDB のどの属性に対応しているかを指定します。
前述の例では、各プロパティに `@DynamoDBAttribute` 注釈を追加することで、プロパティ名が前のステップで作成したテーブルに確実に一致し、このガイド内の他のコード例で使用されている属性名との整合性がとられています。
クラス定義には、テーブル内のどの属性にもマッピングされないプロパティを含めることもできます。これらのプロパティを特定するには、`@DynamoDBIgnore` 注釈を追加します。前述の例では、`SomeProp` プロパティが `@DynamoDBIgnore` 注釈によってマーキングされています。`CatalogItem` インスタンスをテーブルにアップロードしたとき、`DynamoDBMapper` インスタンスに `SomeProp` プロパティは追加されません。また、このマッパーは、テーブルから項目を取り出すときにこの属性を返しません。
マッピングクラスを定義したら、`DynamoDBMapper` メソッドを使用して、そのクラスのインスタンスを `Catalog` テーブルの対応する項目に書き込むことができます。次のサンプルコードでは、この技術を示しています。
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDBMapper mapper = new DynamoDBMapper(client);
CatalogItem item = new CatalogItem();
item.setId(102);
item.setTitle("Book 102 Title");
item.setISBN("222-2222222222");
item.setBookAuthors(new HashSet(Arrays.asList("Author 1", "Author 2")));
item.setSomeProp("Test");
mapper.save(item);
```
次のサンプルコードでは、項目を取得し、その属性の一部にアクセスする方法を示します。
```
CatalogItem partitionKey = new CatalogItem();
partitionKey.setId(102);
DynamoDBQueryExpression queryExpression = new DynamoDBQueryExpression()
.withHashKeyValues(partitionKey);
List itemList = mapper.query(CatalogItem.class, queryExpression);
for (int i = 0; i < itemList.size(); i++) {
System.out.println(itemList.get(i).getTitle());
System.out.println(itemList.get(i).getBookAuthors());
}
```
`DynamoDBMapper` は、Java 内で DynamoDB データを操作するための直観的で自然な方法を提供します。また、オプティミスティックロック、ACID トランザクション、自動生成されるパーティションキーとソートキーの値、オブジェクトのバージョニングなど、複数の組み込み機能があります。
# DynamoDBMapper クラス
`DynamoDBMapper` クラスは、Amazon DynamoDB のエントリポイントとなります。このクラスは、DynamoDB エンドポイントへのアクセスを提供し、さまざまなテーブルのデータを使用できるようにします。また、アイテムに対する作成、読み込み、更新、削除 (CRUD) の各オペレーションの実行、およびテーブルに対するクエリやスキャンを行うことができます。このクラスでは、DynamoDB を操作するために以下のメソッドが提供されます。
対応する Javadoc ドキュメントについては、*AWS SDK for Java API リファレンス*の「[DynamoDBMapper](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/datamodeling/DynamoDBMapper.html)」を参照してください。
**Topics**
+ [save](#DynamoDBMapper.Methods.save)
+ [load](#DynamoDBMapper.Methods.load)
+ [削除](#DynamoDBMapper.Methods.delete)
+ [query](#DynamoDBMapper.Methods.query)
+ [queryPage](#DynamoDBMapper.Methods.queryPage)
+ [スキャン](#DynamoDBMapper.Methods.scan)
+ [scanPage](#DynamoDBMapper.Methods.scanPage)
+ [parallelScan](#DynamoDBMapper.Methods.parallelScan)
+ [batchSave](#DynamoDBMapper.Methods.batchSave)
+ [batchLoad](#DynamoDBMapper.Methods.batchLoad)
+ [batchDelete](#DynamoDBMapper.Methods.batchDelete)
+ [バッチ書き込み](#DynamoDBMapper.Methods.batchWrite)
+ [transactionWrite](#DynamoDBMapper.Methods.transactionWrite)
+ [transactionLoad](#DynamoDBMapper.Methods.transactionLoad)
+ [count](#DynamoDBMapper.Methods.count)
+ [generateCreateTableRequest](#DynamoDBMapper.Methods.generateCreateTableRequest)
+ [createS3Link](#DynamoDBMapper.Methods.createS3Link)
+ [getS3ClientCache](#DynamoDBMapper.Methods.getS3ClientCache)
## save
指定したオブジェクトがテーブルに保存されます。このメソッドで必要なパラメータは、保存するオブジェクトだけです。`DynamoDBMapperConfig` オブジェクトを使用して、オプションの設定パラメータを入力できます。
同じプライマリキーを持つ項目が存在しない場合は、このメソッドによってテーブル内に新しい項目が作成されます。同じプライマリキーを持つ項目が存在する場合は、その既存の項目が更新されます。パーティションキーとソートキーが String 型で、`@DynamoDBAutoGeneratedKey` によって注釈が付けられている場合、初期化しなければ、ランダムな UUID (Universally Unique Identifier) が与えられます。`@DynamoDBVersionAttribute` で注釈が付けられたバージョンフィールドは、バージョンが 1 ずつ増えていきます。さらに、バージョンフィールドが更新されるかキーが生成されると、オペレーションの結果として、渡されたオブジェクトが更新されます。
デフォルトでは、マップされたクラスプロパティに対応する属性のみが更新されます。アイテムのその他の既存の属性には影響はありません。ただし、`SaveBehavior.CLOBBER` を指定すると、項目が完全に上書きされるようにすることができます。
```
DynamoDBMapperConfig config = DynamoDBMapperConfig.builder()
.withSaveBehavior(DynamoDBMapperConfig.SaveBehavior.CLOBBER).build();
mapper.save(item, config);
```
バージョニングを有効にした場合は、クライアント側とサーバー側で項目のバージョンが一致する必要があります。ただし、`SaveBehavior.CLOBBER` オプションを使用する場合は、バージョンを一致させる必要はありません。バージョニングの詳細については、「[DynamoDB およびバージョン番号を使用した楽観的ロック](DynamoDBMapper.OptimisticLocking.md)」を参照してください。
## load
テーブルから項目を取り出します。取得する項目のプライマリキーを入力する必要があります。`DynamoDBMapperConfig` オブジェクトを使用して、オプションの設定パラメータを入力できます。たとえば次の Java ステートメントに示すように、オプションで強力な整合性のある読み込みをリクエストして、このメソッドによって最新の項目の値だけを取り出すようにすることができます。
```
DynamoDBMapperConfig config = DynamoDBMapperConfig.builder()
.withConsistentReads(DynamoDBMapperConfig.ConsistentReads.CONSISTENT).build();
CatalogItem item = mapper.load(CatalogItem.class, item.getId(), config);
```
DynamoDB のデフォルトでは、結果整合性のある値を持つ項目が返されます。DynamoDB の結果整合性モデルの詳細については、「[DynamoDB の読み取り整合性](HowItWorks.ReadConsistency.md)」を参照してください。
## 削除
テーブルから項目を削除します。マッピングされたクラスのオブジェクトインスタンスを渡す必要があります。
バージョニングを有効にした場合は、クライアント側とサーバー側で項目のバージョンが一致する必要があります。ただし、`SaveBehavior.CLOBBER` オプションを使用する場合は、バージョンを一致させる必要はありません。バージョニングの詳細については、「[DynamoDB およびバージョン番号を使用した楽観的ロック](DynamoDBMapper.OptimisticLocking.md)」を参照してください。
## query
テーブルまたはセカンダリインデックスをクエリする
フォーラムスレッドの返信を格納する `Reply` というテーブルがあるとします。各スレッドの件名については、0 以上の返信を受け取ることができます。`Reply` テーブルのプライマリキーは、`Id` および `ReplyDateTime` フィールドで構成されます。ここで、`Id` はプライマリキーのパーティションキー、`ReplyDateTime` はソートキーを表します。
```
Reply ( Id, ReplyDateTime, ... )
```
`Reply` クラスと、それに対応する DynamoDB 内の `Reply` テーブルの間で、マッピングを作成したとします。次の Java コードでは、`DynamoDBMapper` を使用して特定のスレッド件名に対する過去 2 週間のすべての返信を検索しています。
**Example**
```
String forumName = "&DDB;";
String forumSubject = "&DDB; Thread 1";
String partitionKey = forumName + "#" + forumSubject;
long twoWeeksAgoMilli = (new Date()).getTime() - (14L*24L*60L*60L*1000L);
Date twoWeeksAgo = new Date();
twoWeeksAgo.setTime(twoWeeksAgoMilli);
SimpleDateFormat df = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'");
String twoWeeksAgoStr = df.format(twoWeeksAgo);
Map eav = new HashMap();
eav.put(":v1", new AttributeValue().withS(partitionKey));
eav.put(":v2",new AttributeValue().withS(twoWeeksAgoStr.toString()));
DynamoDBQueryExpression queryExpression = new DynamoDBQueryExpression()
.withKeyConditionExpression("Id = :v1 and ReplyDateTime > :v2")
.withExpressionAttributeValues(eav);
List latestReplies = mapper.query(Reply.class, queryExpression);
```
このクエリでは、`Reply` オブジェクトのコレクションが返されます。
デフォルトでは、`query` メソッドによって、「遅延ロード」されたコレクションが返されます。最初に結果が 1 ページのみ返され、必要に応じて、さらに次ページを要求するサービス呼び出しが行われます。一致するすべての項目を取得するには、`latestReplies` コレクションを反復処理します。
コレクションで `size()` メソッドを呼び出すと、正確なカウントを提供するためにすべての結果がロードされます。これにより、プロビジョニングされたスループットが大量に消費され、非常に大きなテーブルでは JVM 内のすべてのメモリが消費されることさえあります。
インデックスにクエリを実行するには、最初にインデックスをマッパークラスとしてモデリングする必要があります。今、`Reply` テーブルに、*PostedBy-Message-Index* という名前のグローバルセカンダリインデックスが存在すると仮定します。このインデックスのパーティションキーは `PostedBy` キーで、ソートキーは `Message` です。インデックス内の項目のクラス定義は次のようになります。
```
@DynamoDBTable(tableName="Reply")
public class PostedByMessage {
private String postedBy;
private String message;
@DynamoDBIndexHashKey(globalSecondaryIndexName = "PostedBy-Message-Index", attributeName = "PostedBy")
public String getPostedBy() { return postedBy; }
public void setPostedBy(String postedBy) { this.postedBy = postedBy; }
@DynamoDBIndexRangeKey(globalSecondaryIndexName = "PostedBy-Message-Index", attributeName = "Message")
public String getMessage() { return message; }
public void setMessage(String message) { this.message = message; }
// Additional properties go here.
}
```
`@DynamoDBTable` 注釈は、このインデックスが `Reply` テーブルに関連付けられていることを示します。`@DynamoDBIndexHashKey` 注釈はインデックスのパーティションキー (*PostedBy*) を示し、`@DynamoDBIndexRangeKey` はインデックスのソートキー (*Message*) を示します。
ここで、`DynamoDBMapper` を使用してインデックスにクエリを実行し、特定のユーザーによって投稿されたメッセージのサブセットを取得できます。テーブル間やインデックス間でマッピングが競合せず、マッピングが既にマッパーで行われている場合は、インデックス名を指定する必要はありません。マッパーは、プライマリキーとソートキーに基づいて推論します。次のコードでは、グローバルセカンダリインデックスをクエリしています。グローバルセカンダリインデックスは、結果整合性のある読み込みをサポートしますが、強力な整合性のある読み込みはサポートしていないため、`withConsistentRead(false)` を指定する必要があります。
```
HashMap eav = new HashMap();
eav.put(":v1", new AttributeValue().withS("User A"));
eav.put(":v2", new AttributeValue().withS("DynamoDB"));
DynamoDBQueryExpression queryExpression = new DynamoDBQueryExpression()
.withIndexName("PostedBy-Message-Index")
.withConsistentRead(false)
.withKeyConditionExpression("PostedBy = :v1 and begins_with(Message, :v2)")
.withExpressionAttributeValues(eav);
List iList = mapper.query(PostedByMessage.class, queryExpression);
```
このクエリでは、`PostedByMessage` オブジェクトのコレクションが返されます。
## queryPage
テーブルまたはセカンダリインデックスのクエリを実行し、一致した結果を 1 ページ返します。`query` メソッドと同様、パーティションキー値とソートキー属性に適用されるクエリフィルタを指定する必要があります。ただし `queryPage` では、データの最初の "ページ"、つまり 1 MB 以内に収まるデータ量のみが返されます。
## スキャン
テーブル全体またはセカンダリインデックスをスキャンします。オプションで `FilterExpression` を指定して結果セットをフィルタリングできます。
フォーラムスレッドの返信を格納する `Reply` というテーブルがあるとします。各スレッドの件名については、0 以上の返信を受け取ることができます。`Reply` テーブルのプライマリキーは、`Id` および `ReplyDateTime` フィールドで構成されます。ここで、`Id` はプライマリキーのパーティションキー、`ReplyDateTime` はソートキーを表します。
```
Reply ( Id, ReplyDateTime, ... )
```
`Reply` テーブルに Java クラスをマッピングした場合は、`DynamoDBMapper` を使用してテーブルをスキャンできます。たとえば、以下の Java コードは、`Reply` テーブル全体をスキャンし、特定の年の返信のみを返します。
**Example**
```
HashMap eav = new HashMap();
eav.put(":v1", new AttributeValue().withS("2015"));
DynamoDBScanExpression scanExpression = new DynamoDBScanExpression()
.withFilterExpression("begins_with(ReplyDateTime,:v1)")
.withExpressionAttributeValues(eav);
List replies = mapper.scan(Reply.class, scanExpression);
```
デフォルトでは、`scan` メソッドによって、「遅延ロード」されたコレクションが返されます。最初に結果が 1 ページのみ返され、必要に応じて、さらに次ページを要求するサービス呼び出しが行われます。一致するすべての項目を取得するには、`replies` コレクションを反復処理します。
コレクションで `size()` メソッドを呼び出すと、正確なカウントを提供するためにすべての結果がロードされます。これにより、プロビジョニングされたスループットが大量に消費され、非常に大きなテーブルでは JVM 内のすべてのメモリが消費されることさえあります。
インデックスをスキャンするには、最初にインデックスをマッパークラスとしてモデリングする必要があります。今、`Reply` テーブルには、`PostedBy-Message-Index` という名前のグローバルセカンダリインデックスがあると仮定します。このインデックスのパーティションキーは `PostedBy` キーで、ソートキーは `Message` です。このインデックスのマッパークラスは、[query](#DynamoDBMapper.Methods.query) セクションに示されています。また、`@DynamoDBIndexHashKey` と `@DynamoDBIndexRangeKey` の注釈を使用して、インデックスパーティションキーとソートキーを指定します。
以下のサンプルコードでは `PostedBy-Message-Index` をスキャンします。スキャンフィルタを使用しないので、インデックス内のすべての項目が返されます。
```
DynamoDBScanExpression scanExpression = new DynamoDBScanExpression()
.withIndexName("PostedBy-Message-Index")
.withConsistentRead(false);
List iList = mapper.scan(PostedByMessage.class, scanExpression);
Iterator indexItems = iList.iterator();
```
## scanPage
テーブルまたはセカンダリインデックスがスキャンされ、一致する結果が 1 ページ返されます。`scan` メソッドと同様に、オプションで `FilterExpression` を指定して結果セットをフィルタリングできます。ただし、`scanPage` では、データの最初の "ページ"、つまり、1 MB 以内に収まるデータ量のみが返されます。
## parallelScan
テーブル全体、またはセカンダリインデックスの並列スキャンが実行されます。テーブルの論理セグメントの数と、結果をフィルタするスキャン式を指定します。`parallelScan` では、スキャンタスクが複数のワーカーに分割され、論理セグメントごとに 1 つのワーカーが割り当てられます。ワーカーは、データを並列に処理し、結果を返します。
次の Java コード例では、`Product` テーブルに対して並列スキャンを実行します。
```
int numberOfThreads = 4;
Map eav = new HashMap();
eav.put(":n", new AttributeValue().withN("100"));
DynamoDBScanExpression scanExpression = new DynamoDBScanExpression()
.withFilterExpression("Price <= :n")
.withExpressionAttributeValues(eav);
List scanResult = mapper.parallelScan(Product.class, scanExpression, numberOfThreads);
```
## batchSave
`AmazonDynamoDB.batchWriteItem` メソッドに対する 1 つ以上の呼び出しを使用して、1 つ以上のテーブルにオブジェクトを保存します。このメソッドでは、トランザクション保証はなされません。
次の Java コードでは、2 つの項目 (書籍) を `ProductCatalog` テーブルに保存します。
```
Book book1 = new Book();
book1.setId(901);
book1.setProductCategory("Book");
book1.setTitle("Book 901 Title");
Book book2 = new Book();
book2.setId(902);
book2.setProductCategory("Book");
book2.setTitle("Book 902 Title");
mapper.batchSave(Arrays.asList(book1, book2));
```
## batchLoad
テーブルのプライマリキーを使用して、1 つ以上のテーブルから複数の項目を取り出します。
次の Java コードでは、2 つの異なるテーブルから 2 つの項目を取得します。
```
ArrayList