メニュー
Amazon DynamoDB
開発者ガイド (API Version 2012-08-10)

DynamoDBContext クラス

DynamoDBContext クラスは、DynamoDB データベースのエントリポイントです。このクラスから DynamoDB に接続して、各種のテーブル内のデータにアクセスし、さまざまな CRUD オペレーションとクエリを実行することができます。DynamoDBContext クラスでは次のメソッドを使用できます。

Create​MultiTable​BatchGet

複数の個々の BatchGet オブジェクトで構成される MultiTableBatchGet オブジェクトを作成します。各 BatchGet オブジェクトは、1 つの DynamoDB テーブルから項目を取り出すときに使用できます。

1 つ以上のテーブルから項目を取り出すには、ExecuteBatchGet メソッドを使用し、MultiTableBatchGet オブジェクトをパラメータとして渡します。

Create​MultiTable​BatchWrite

複数の個々の BatchWrite オブジェクトで構成される MultiTableBatchWrite オブジェクトを作成します。これらの BatchWrite オブジェクトはそれぞれ、1 つの DynamoDB テーブルの項目を書き込んだり削除したりするために使用できます。

1 つ以上のテーブルに書き込むには、ExecuteBatchWrite メソッドを使用し、MultiTableBatchWrite オブジェクトをパラメータとして渡します。

Create​Batch​Get

テーブルから複数の項目を取り出すために使用できる BatchGet オブジェクトを作成します。詳細については、「バッチ取得: 複数の項目の取得 」を参照してください。

Create​Batch​Write

テーブルに複数の項目を入力する、またはテーブルから複数の項目を削除するために使用できる BatchWrite オブジェクトを作成します。詳細については、「バッチ書き込み: 複数の項目の書き込みおよび削除 」を参照してください。

Delete

テーブルから項目を削除します。このメソッドでは、削除する項目のプライマリキーが必要になります。プライマリキーの値、またはこのメソッドのパラメータとしてプライマリキーの値を使用するクライアント側オブジェクトを入力できます。

  • クライアント側オブジェクトをパラメータとして指定し、オプティミスティックロックを有効にすると、クライアント側とサーバー側のオブジェクトのバージョンが一致する場合のみ、削除が成功します。

  • プライマリキーの値だけをパラメータとして指定すると、オプティミスティックロックを有効にしているかどうかにかかわらず、削除が成功します。

注記

このオペレーションをバックグラウンドで実行するには、DeleteAsync メソッドを使用します。

Dispose

すべてのマネージドリソースとアンマネージドリソースの Dispose を実行します。

Execute​Batch​Get

1 つ以上のテーブルからデータを読み込みます。MultiTableBatchGet 内のすべての BatchGet オブジェクトを処理します。

注記

このオペレーションをバックグラウンドで実行するには、ExecuteBatchGetAsync メソッドを使用します。

Execute​Batch​Write

1 つ以上のテーブルにデータを書き込むまたは削除します。MultiTableBatchWrite 内のすべての BatchWrite オブジェクトを処理します。

注記

このオペレーションをバックグラウンドで実行するには、ExecuteBatchWriteAsync メソッドを使用します。

FromDocument

Document のインスタンスと仮定すると、FromDocument メソッドは、クライアント側のクラスのインスタンスを返します。

これは、オブジェクト永続性モデルと合わせてドキュメントモデルクラスを使用してデータオペレーションを行う場合に役立ちます。AWS SDK for .NET で使用されるドキュメントモデルクラスの詳細については、「.NET ドキュメントモデル」を参照してください。

doc という名前の Document オブジェクトがあり、Forum 項目の表現を含んでいるとします。(このオブジェクトの構成方法については、下の ToDocument メソッドの説明を参照してください)。次の C# コードスニペットに示すように、FromDocument を使用して Document から Forum 項目を取り出すことができます。

Copy
forum101 = context.FromDocument<Forum>(101);

注記

Document オブジェクトで IEnumerable インターフェイスを実装している場合、FromDocuments メソッドを使用できます。これにより、Document のすべてのクラスインスタンスを反復的に処理できます。

FromQuery

QueryOperationConfig オブジェクトに定義されたクエリパラメータを使用して、Query オペレーションを実行します。

注記

このオペレーションをバックグラウンドで実行するには、FromQueryAsync メソッドを使用します。

FromScan

ScanOperationConfig オブジェクトに定義されたスキャンパラメータを使用して、Scan オペレーションを実行します。

注記

このオペレーションをバックグラウンドで実行するには、FromScanAsync メソッドを使用します。

Get​Target​Table

指定した型のターゲットテーブルを取り出します。これは、任意のデータを DynamoDB テーブルにマッピングするためのカスタムコンバーターを記述していて、カスタムデータ型に関連付けられているテーブルを特定する必要がある場合に役立ちます。

Load

テーブルから項目を取り出します。このメソッドでは、取り出す項目のプライマリキーだけが必要になります。

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

注記

このオペレーションをバックグラウンドで実行するには、LoadAsync メソッドを使用します。

Query

指定したクエリパラメータに基づいてテーブルのクエリが実行されます。

複合プライマリキー (パーティションキーおよびソートキー) が存在する場合にのみ、テーブルにクエリを実行できます。クエリを実行する場合は、パーティションキーと、ソートキーに適用される条件を指定する必要があります。

クライアント側の Reply クラスが DynamoDB の Reply テーブルにマッピングされているとします。次の C# コードスニペットでは、Reply テーブルのクエリを実行し、過去 15 日間に投稿されたフォーラムスレッドの返信を検索しています。Reply テーブルには、Id パーティションキーと ReplyDateTime ソートキーを持つプライマリキーがあります。Reply テーブルの詳細については、「テーブルの作成とサンプルデータのロード」を参照してください。

Copy
DynamoDBContext context = new DynamoDBContext(client); string replyId = "DynamoDB#DynamoDB Thread 1"; //Partition key DateTime twoWeeksAgoDate = DateTime.UtcNow.Subtract(new TimeSpan(14, 0, 0, 0)); // Date to compare. IEnumerable<Reply> latestReplies = context.Query<Reply>(replyId, QueryOperator.GreaterThan, twoWeeksAgoDate);

これにより、Reply オブジェクトのコレクションが返されます。

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

テーブルにシンプルなプライマリキー (パーティションキー) がある場合は、Query メソッドを使用することはできません。代わりに Load メソッドを使用して、パーティションキーを入力して項目を取り出すことができます。

注記

このオペレーションをバックグラウンドで実行するには、QueryAsync メソッドを使用します。

Save

指定したオブジェクトがテーブルに保存されます。入力オブジェクトで指定されたプライマリキーがテーブル内に存在しない場合は、このメソッドによって新しい項目がテーブルに追加されます。プライマリキーが存在する場合は、このメソッドによって既存の項目が更新されます。

オプティミスティックロックを設定している場合には、クライアント側とサーバー側で項目のバージョンが一致する場合のみ、更新が正常に実行されます。詳細については、「DynamoDB で AWS SDK for .NET オブジェクト永続性モデルを使用した、バージョン番号によるオプティミスティックロック」を参照してください。

注記

このオペレーションをバックグラウンドで実行するには、SaveAsync メソッドを使用します。

Scan

テーブル全体のスキャンを実行します。

スキャン条件を指定することで、スキャン結果にフィルタを適用することができます。この条件は、テーブル内の任意の属性に適用することができます。クライアント側のクラス Book が、DynamoDB の ProductCatalog テーブルにマッピングされているとします。次の C# コードスニペットでは、テーブルがスキャンされ、価格が 0 未満の書籍項目だけが返されています。

Copy
IEnumerable<Book> itemsWithWrongPrice = context.Scan<Book>( new ScanCondition("Price", ScanOperator.LessThan, price), new ScanCondition("ProductCategory", ScanOperator.Equal, "Book") );

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

パフォーマンス上の理由から、テーブルについてはスキャンを避け、クエリを行うようにしてください。

注記

このオペレーションをバックグラウンドで実行するには、ScanAsync メソッドを使用します。

ToDocument

クラスインスタンスから、Document ドキュメントモデルクラスのインスタンスが返されます。

これは、オブジェクト永続性モデルと合わせてドキュメントモデルクラスを使用してデータオペレーションを行う場合に役立ちます。AWS SDK for .NET で使用されるドキュメントモデルクラスの詳細については、「.NET ドキュメントモデル」を参照してください。

クライアント側のクラスが Forum サンプルテーブルにマッピングされているとします。その場合は次の C# コードスニペットに示すように、DynamoDBContext を使用して、Forum テーブルから項目を Document オブジェクトとして取得することができます。

Copy
DynamoDBContext context = new DynamoDBContext(client); Forum forum101 = context.Load<Forum>(101); // Retrieve a forum by primary key. Document doc = context.ToDocument<Forum>(forum101);

DynamoDBContext でのオプションパラメータの指定

オブジェクト永続性モデルを使用する場合は、DynamoDBContext に次のオプションパラメータを指定できます。

  • ConsistentReadLoadQuery、または Scan オペレーションを使用してデータを取り出す場合は、このパラメータをオプションで追加して、データの最新の値をリクエストすることができます。

  • IgnoreNullValues – このパラメータにより、Save オペレーション時に属性の null 値を無視するように DynamoDBContext に指示できます。このパラメータが false の場合(または設定されていない場合)、null 値は、特定の属性を削除するディレクティブと見なされます。

  • SkipVersionCheck – このパラメータにより、項目を保存または削除する場合にバージョンの比較を行わないように DynamoDBContext に指示できます。バージョニングの詳細については、「DynamoDB で AWS SDK for .NET オブジェクト永続性モデルを使用した、バージョン番号によるオプティミスティックロック」を参照してください。

  • TableNamePrefix – すべてのテーブル名に特定の文字列をプレフィックスとして付けます。このパラメータが null の場合(または設定されていない場合)、プレフィックスは使用されません。

次の C# コードスニペットでは、前述のオプションパラメータのうち、2 つを指定して、新しい DynamoDBContext を作成しています。

Copy
AmazonDynamoDBClient client = new AmazonDynamoDBClient(); ... DynamoDBContext context = new DynamoDBContext(client, new DynamoDBContextConfig { ConsistentRead = true, SkipVersionCheck = true});

DynamoDBContext では、このコンテキストを使用して送信した各リクエストに、これらのオプションパラメータが含められます。

これらのパラメータを DynamoDBContext レベルで設定する代わりに、次の C# コードスニペットに示すように、DynamoDBContext を使用して実行する個々のオペレーションに対して指定することもできます。この例では特定の書籍項目がロードされています。DynamoDBContextLoad メソッドでは、前述のオプションパラメータを指定します。

Copy
AmazonDynamoDBClient client = new AmazonDynamoDBClient(); ... DynamoDBContext context = new DynamoDBContext(client); Book bookItem = context.Load<Book>(productId,new DynamoDBContextConfig{ ConsistentRead = true, SkipVersionCheck = true });

この場合 DynamoDBContext には、Get リクエストを送信する場合のみ、これらのパラメータが含まれます。