Amazon DynamoDB
開発者ガイド (API バージョン 2012-08-10)

DynamoDBMapper クラス

DynamoDBMapper クラスは、Amazon DynamoDB のエントリポイントです。DynamoDB エンドポイントへのアクセスを許可し、さまざまなテーブルのデータにアクセスできるようにします。また、アイテムに対する作成、読み取り、更新、削除 (CRUD) の各オペレーションの実行、クエリ、およびテーブルのスキャンを行うことができます。このクラスは、DynamoDB を操作するために以下のメソッドを提供します。

対応する Javadoc ドキュメントについては、AWS SDK for Java API Reference の「DynamoDBMapper」を参照してください。

save

指定したオブジェクトがテーブルに保存されます。このメソッドで必要なパラメータは、保存するオブジェクトだけです。DynamoDBMapperConfig オブジェクトを使用して、オプションの設定パラメータを入力できます。

同じプライマリキーを持つ項目が存在しない場合は、このメソッドによってテーブル内に新しい項目が作成されます。同じプライマリキーを持つ項目が存在する場合は、その既存の項目が更新されます。パーティションキーとソートキーが String 型で、@DynamoDBAutoGeneratedKey によって注釈が付けられている場合、初期化しなければ、ランダムな UUID (Universally Unique Identifier) が与えられます。@DynamoDBVersionAttribute で注釈が付けられたバージョンフィールドは、バージョンが 1 ずつ増えていきます。さらに、バージョンフィールドが更新されるかキーが生成されると、オペレーションの結果として、渡されたオブジェクトが更新されます。

デフォルトでは、マップされたクラスプロパティに対応する属性のみが更新されます。アイテムのその他の既存の属性には影響はありません。ただし、SaveBehavior.CLOBBER を指定すると、項目が完全に上書きされるようにすることができます。

mapper.save(obj, new DynamoDBMapperConfig(DynamoDBMapperConfig.SaveBehavior.CLOBBER));

バージョニングを有効にした場合は、クライアント側とサーバー側で項目のバージョンが一致する必要があります。ただし、SaveBehavior.CLOBBER オプションを使用する場合は、バージョンを一致させる必要はありません。バージョニングの詳細については、「バージョン番号を使用したオプティミスティックロック」を参照してください。

ロード

テーブルから項目を取り出します。取得する項目のプライマリキーを入力する必要があります。DynamoDBMapperConfig オブジェクトを使用して、オプションの設定パラメータを入力できます。たとえば次の Java ステートメントに示すように、オプションで強力な整合性のある読み込みをリクエストして、このメソッドによって最新の項目の値だけを取り出すようにすることができます。

CatalogItem item = mapper.load(CatalogItem.class, item.getId(), new DynamoDBMapperConfig(DynamoDBMapperConfig.ConsistentReads.CONSISTENT));

デフォルトでは、DynamoDB では結果整合性のある値を持つ項目が返されます。DynamoDB の結果整合性モデルの詳細については、「読み込み整合性」を参照してください。

delete

テーブルから項目を削除します。マッピングされたクラスのオブジェクトインスタンスを渡す必要があります。

バージョニングを有効にした場合は、クライアント側とサーバー側で項目のバージョンが一致する必要があります。ただし、SaveBehavior.CLOBBER オプションを使用する場合は、バージョンを一致させる必要はありません。バージョニングの詳細については、「バージョン番号を使用したオプティミスティックロック」を参照してください。

query

テーブルまたはセカンダリインデックスのクエリを実行します。複合プライマリキー (パーティションキーおよびソートキー) が存在する場合にのみ、テーブルまたはインデックスにクエリを実行できます。このメソッドでは、ソートキーに適用されるパーティションキー値とクエリフィルタを指定する必要があります。フィルタ式には、条件と値が含まれています。

フォーラムスレッドの返信を格納する Reply というテーブルがあるとします。各スレッドの件名については、0 以上の返信を受け取ることができます。Reply テーブルのプライマリキーは、Id および ReplyDateTime フィールドで構成されます。ここで、Id はプライマリキーのパーティションキー、ReplyDateTime はソートキーを表します。

Reply ( Id, ReplyDateTime, ... )

Reply クラスと DynamoDB の対応する Reply テーブルの間のマッピングを作成したとします。次の Java コードでは、DynamoDBMapper を使用して特定のスレッド件名に対する過去 2 週間のすべての返信を検索しています。

String forumName = "DynamoDB"; String forumSubject = "DynamoDB 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<String, AttributeValue> eav = new HashMap<String, AttributeValue>(); eav.put(":v1", new AttributeValue().withS(partitionKey)); eav.put(":v2",new AttributeValue().withS(twoWeeksAgoStr.toString())); DynamoDBQueryExpression<Reply> queryExpression = new DynamoDBQueryExpression<Reply>() .withKeyConditionExpression("Id = :v1 and ReplyDateTime > :v2") .withExpressionAttributeValues(eav); List<Reply> latestReplies = mapper.query(Reply.class, queryExpression);

このクエリでは、Reply オブジェクトのコレクションが返されます。

デフォルトでは、query メソッドによって、「遅延ロード」されたコレクションが返されます。最初に結果が 1 ページのみ返され、必要に応じて、さらに次ページを要求するサービス呼び出しが行われます。一致するすべての項目を取得するには、latestReplies コレクションを反復処理します。

インデックスにクエリを実行するには、最初にインデックスをマッパークラスとしてモデリングする必要があります。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 を使用してインデックスにクエリを実行し、特定のユーザーによって投稿されたメッセージのサブセットを取得できます。クエリを実行するインデックスを DynamoDB に知らせるため、withIndexName を指定する必要があります。次のコードでは、グローバルセカンダリインデックス をクエリします。グローバルセカンダリインデックスは、結果整合性のある読み込みをサポートしますが、強力な整合性のある読み込みはサポートしていないため、withConsistentRead(false) を指定する必要があります。

HashMap<String, AttributeValue> eav = new HashMap<String, AttributeValue>(); eav.put(":v1", new AttributeValue().withS("User A")); eav.put(":v2", new AttributeValue().withS("DynamoDB")); DynamoDBQueryExpression<PostedByMessage> queryExpression = new DynamoDBQueryExpression<PostedByMessage>() .withIndexName("PostedBy-Message-Index") .withConsistentRead(false) .withKeyConditionExpression("PostedBy = :v1 and begins_with(Message, :v2)") .withExpressionAttributeValues(eav); List<PostedByMessage> iList = mapper.query(PostedByMessage.class, queryExpression);

このクエリでは、PostedByMessage オブジェクトのコレクションが返されます。

queryPage

テーブルまたはセカンダリインデックスのクエリを実行し、一致する結果を 1 ページ返します。query メソッドと同様、パーティションキー値とソートキー属性に適用されるクエリフィルタを指定する必要があります。ただし、1 MB では、データの最初の "ページ"、つまり、queryPage 内に収まるデータ量のみが返ります。

scan

テーブル全体またはセカンダリインデックスがスキャンされます。オプションで FilterExpression を指定して結果セットをフィルタリングできます。

フォーラムスレッドの返信を格納する Reply というテーブルがあるとします。各スレッドの件名については、0 以上の返信を受け取ることができます。Reply テーブルのプライマリキーは、Id および ReplyDateTime フィールドで構成されます。ここで、Id はプライマリキーのパーティションキー、ReplyDateTime はソートキーを表します。

Reply ( Id, ReplyDateTime, ... )

Reply テーブルに Java クラスをマッピングした場合は、DynamoDBMapper を使用してテーブルをスキャンできます。たとえば、以下の Java コードは、Reply テーブル全体をスキャンし、特定の年の返信のみを返します。

HashMap<String, AttributeValue> eav = new HashMap<String, AttributeValue>(); eav.put(":v1", new AttributeValue().withS("2015")); DynamoDBScanExpression scanExpression = new DynamoDBScanExpression() .withFilterExpression("begins_with(ReplyDateTime,:v1)") .withExpressionAttributeValues(eav); List<Reply> replies = mapper.scan(Reply.class, scanExpression);

デフォルトでは、scan メソッドによって、「遅延ロード」されたコレクションが返されます。最初に結果が 1 ページのみ返され、必要に応じて、さらに次ページを要求するサービス呼び出しが行われます。一致するすべての項目を取得するには、replies コレクションを反復処理します。

インデックスをスキャンするには、最初にインデックスをマッパークラスとしてモデリングする必要があります。Reply テーブルに、PostedBy-Message-Index という名前の グローバルセカンダリインデックス があるとします。このインデックスのパーティションキーは PostedBy キーで、ソートキーは Message です。このインデックスのマッパークラスは、query セクションに示されています。また、@DynamoDBIndexHashKey@DynamoDBIndexRangeKey の注釈を使用して、インデックスパーティションキーとソートキーを指定します。

以下のサンプルコードでは PostedBy-Message-Index をスキャンします。スキャンフィルタを使用しないので、インデックス内のすべての項目が返されます。

DynamoDBScanExpression scanExpression = new DynamoDBScanExpression() .withIndexName("PostedBy-Message-Index") .withConsistentRead(false); List<PostedByMessage> iList = mapper.scan(PostedByMessage.class, scanExpression); Iterator<PostedByMessage> indexItems = iList.iterator();

scanPage

テーブルまたはセカンダリインデックスがスキャンされ、一致する結果が 1 ページ返されます。scan メソッドと同様に、オプションで FilterExpression を指定して結果セットをフィルタリングできます。ただし、scanPage では、データの最初の "ページ"、つまり、1 MB 内に収まるデータ量のみが返ります。

parallelScan

テーブルまたはセカンダリインデックス全体の並列スキャンが実行されます。テーブルの論理セグメントの数と、結果をフィルタするスキャン式を指定します。parallelScan では、スキャンタスクが複数のワーカーに分割され、論理セグメントごとに 1 つのワーカーが割り当てられます。ワーカーは、データを並列に処理し、結果を返します。

次の Java コード例では、Product テーブルに対して並列スキャンを実行します。

int numberOfThreads = 4; Map<String, AttributeValue> eav = new HashMap<String, AttributeValue> (); eav.put(":n", new AttributeValue().withN("100")); DynamoDBScanExpression scanExpression = new DynamoDBScanExpression() .withFilterExpression("Price >= :n") .withExpressionAttributeValues(eav); List<Product> scanResult = mapper.parallelScan(Product.class, scanExpression, numberOfThreads);

parallelScan の使用を示す Java コード例については、「例: クエリおよびスキャン」を参照してください。

batchSave

AmazonDynamoDB.batchWriteItem メソッドに対する 1 つ以上の呼び出しを使用して、1 つ以上のテーブルにオブジェクトを保存します。このメソッドでは、トランザクション保証はなされません。

次の Java コードでは、2 つの項目 (書籍) を ProductCatalog テーブルに保存します。

Book book1 = new Book(); book1.id = 901; book1.productCategory = "Book"; book1.title = "Book 901 Title"; Book book2 = new Book(); book2.id = 902; book2.productCategory = "Book"; book2.title = "Book 902 Title"; mapper.batchSave(Arrays.asList(book1, book2));

batchLoad

テーブルのプライマリキーを使用して、1 つ以上のテーブルから複数の項目を取り出します。

次の Java コードでは、2 つの異なるテーブルから 2 つの項目を取得します。

ArrayList<Object> itemsToGet = new ArrayList<Object>(); ForumItem forumItem = new ForumItem(); forumItem.setForumName("Amazon DynamoDB"); itemsToGet.add(forumItem); ThreadItem threadItem = new ThreadItem(); threadItem.setForumName("Amazon DynamoDB"); threadItem.setSubject("Amazon DynamoDB thread 1 message text"); itemsToGet.add(threadItem); Map<String, List<Object>> items = mapper.batchLoad(itemsToGet);

batchDelete

AmazonDynamoDB.batchWriteItem メソッドに対する 1 つ以上の呼び出しを使用して、1 つ以上のテーブルからオブジェクトを削除します。このメソッドでは、トランザクション保証はなされません。

次の Java コードでは、2 つの項目 (書籍) を ProductCatalog テーブルから削除します。

Book book1 = mapper.load(Book.class, 901); Book book2 = mapper.load(Book.class, 902); mapper.batchDelete(Arrays.asList(book1, book2));

バッチ書き込み

AmazonDynamoDB.batchWriteItem メソッドに対する 1 つ以上の呼び出しを使用して、1 つ以上のテーブルに対してオブジェクトの保存および削除を行います。このメソッドではトランザクション保証はなされず、バージョニング(条件付き入力または削除)もサポートされません。

次の Java コードでは、新しい項目を Forum テーブルと Thread テーブルに書き込み、ProductCatalog テーブルから項目を削除します。

// Create a Forum item to save Forum forumItem = new Forum(); forumItem.name = "Test BatchWrite Forum"; // Create a Thread item to save Thread threadItem = new Thread(); threadItem.forumName = "AmazonDynamoDB"; threadItem.subject = "My sample question"; // Load a ProductCatalog item to delete Book book3 = mapper.load(Book.class, 903); List<Object> objectsToWrite = Arrays.asList(forumItem, threadItem); List<Book> objectsToDelete = Arrays.asList(book3); mapper.batchWrite(objectsToWrite, objectsToDelete);

transactionWrite

AmazonDynamoDB.transactWriteItems メソッドに対する 1 回の呼び出しを使用して、1 つまたは複数のテーブルに対してオブジェクトの保存および削除を行います。

トランザクション固有の例外のリストについては、「TransactWriteItems エラー」を参照してください。

DynamoDB トランザクション、および提供されるアトミック性、整合性、分離、耐久性 (ACID) 保証の詳細については、「Amazon DynamoDB のトランザクション」を参照してください。

注記

このメソッドでは、以下をサポートしていません。

次の Java コードでは、ForumThread の各テーブルに、トランザクションとして新しい項目を書き込みます。

Thread s3ForumThread = new Thread(); s3ForumThread.forumName = "S3 Forum"; s3ForumThread.subject = "Sample Subject 1"; s3ForumThread.message = "Sample Question 1"; Forum s3Forum = new Forum(); s3Forum.name = "S3 Forum"; s3Forum.category = "Amazon Web Services"; s3Forum.threads = 1; TransactionWriteRequest transactionWriteRequest = new TransactionWriteRequest(); transactionWriteRequest.addPut(s3Forum); transactionWriteRequest.addPut(s3ForumThread); mapper.transactionWrite(transactionWriteRequest);

transactionLoad

AmazonDynamoDB.transactGetItems メソッドへの 1 回の呼び出しを使用して、1 つまたは複数のテーブルからオブジェクトをロードします。

トランザクション固有の例外のリストについては、「TransactGetItems エラー」を参照してください。

DynamoDB トランザクション、および提供されるアトミック性、整合性、分離、耐久性 (ACID) 保証の詳細については、「Amazon DynamoDB のトランザクション」を参照してください。

次の Java コードは、 ForumThread の各テーブルから、トランザクションとして一方の項目をロードします。

Forum dynamodbForum = new Forum(); dynamodbForum.name = "DynamoDB Forum"; Thread dynamodbForumThread = new Thread(); dynamodbForumThread.forumName = "DynamoDB Forum"; TransactionLoadRequest transactionLoadRequest = new TransactionLoadRequest(); transactionLoadRequest.addLoad(dynamodbForum); transactionLoadRequest.addLoad(dynamodbForumThread); mapper.transactionLoad(transactionLoadRequest);

count

指定されたスキャン式の値を求め、一致する項目数を返します。項目データは返されません。

generateCreateTableRequest

DynamoDB テーブルを表す POJO クラスを解析し、そのテーブルの CreateTableRequest を返します。

Amazon S3 のオブジェクトへのリンクを作成します。バケット名とキー名を指定する必要があります。キー名によって、バケット内のオブジェクトを一意に識別します。

createS3Link を使用するには、マッパークラスでゲッターメソッドとセッターメソッドを定義する必要があります。次のサンプルコードでは、これを示しており、新しい属性と getter/setter メソッドを CatalogItem クラスに追加しています。

@DynamoDBTable(tableName="ProductCatalog") public class CatalogItem { ... public S3Link productImage; .... @DynamoDBAttribute(attributeName = "ProductImage") public S3Link getProductImage() { return productImage; } public void setProductImage(S3Link productImage) { this.productImage = productImage; } ... }

次の Java コードでは、Product テーブルに書き込まれる新しい項目を定義しています。この項目には、製品イメージへのリンクがあり、そのイメージデータは Amazon S3 にアップロードされています。

CatalogItem item = new CatalogItem(); item.id = 150; item.title = "Book 150 Title"; String myS3Bucket = "myS3bucket"; String myS3Key = "productImages/book_150_cover.jpg"; item.setProductImage(mapper.createS3Link(myS3Bucket, myS3Key)); item.getProductImage().uploadFrom(new File("/file/path/book_150_cover.jpg")); mapper.save(item);

S3Link クラスには、他にも、Amazon S3 のオブジェクトを操作するためのさまざまなメソッドが用意されています。詳細については、「Javadocs for S3Link」を参照してください。

getS3ClientCache

Amazon S3 にアクセスするための基礎となる S3ClientCache を返します。S3ClientCache は、AmazonS3Client オブジェクトのスマートマップです。複数のクライアントがある場合、S3ClientCache によって、AWS リージョン別にクライアントを整理しやすくなり、新しい Amazon S3 クライアントをオンデマンドで作成できます。