kvp in attributeList)
{
string attributeName = kvp.Key;
AttributeValue value = kvp.Value;
Console.WriteLine(
attributeName + " " +
(value.S == null ? "" : "S=[" + value.S + "]") +
(value.N == null ? "" : "N=[" + value.N + "]") +
(value.SS == null ? "" : "SS=[" + string.Join(",", value.SS.ToArray()) + "]") +
(value.NS == null ? "" : "NS=[" + string.Join(",", value.NS.ToArray()) + "]") +
(value.B == null ? "" : "B=[" + FromGzipMemoryStream(value.B) + "]")
);
}
Console.WriteLine("************************************************");
}
private static MemoryStream ToGzipMemoryStream(string value)
{
MemoryStream output = new MemoryStream();
using (GZipStream zipStream = new GZipStream(output, CompressionMode.Compress, true))
using (StreamWriter writer = new StreamWriter(zipStream))
{
writer.Write(value);
}
return output;
}
private static string FromGzipMemoryStream(MemoryStream stream)
{
using (GZipStream zipStream = new GZipStream(stream, CompressionMode.Decompress))
using (StreamReader reader = new StreamReader(zipStream))
{
return reader.ReadToEnd();
}
}
}
}
```
# DynamoDB でのセカンダリインデックスを使用したデータアクセス性の向上
Amazon DynamoDB によって、プライマリキーの値を指定して、テーブルの項目に高速アクセスすることが可能になります。しかし多くのアプリケーションでは、プライマリキー以外の属性を使って、データに効率的にアクセスできるようにセカンダリ（または代替）キーを 1 つ以上設定することで、メリットが得られることがあります。これに対応するために、1 つのテーブルで 1 つ以上のセカンダリインデックスを作成して、それらのインデックスに対して `Query` または `Scan` リクエストを実行することができます。
*セカンダリインデックス* は、テーブルからの属性のサブセットと、`Query` オペレーションをサポートする代替キーで構成されるデータ構造です。`Query` をテーブルで使用する場合と同じように、`Query` を使用してインデックスからデータを取得できます。テーブルには、複数のセカンダリインデックスを含めることができます。これにより、アプリケーションは複数の異なるクエリパターンにアクセスできます。
**注記**
また、テーブルを `Scan` するのと同じように、インデックスも `Scan` できます。
セカンダリインデックススキャンオペレーションのクロスアカウントアクセスは、現在、[リソースベースのポリシー](access-control-resource-based.md)ではサポートされていません。
すべてのセカンダリインデックスは 1 つのテーブルのみに関連付けられ、そこからデータを取得します。これはインデックスの*ベーステーブル*と呼ばれます。インデックスを作成する場合は、インデックスの代替キー (パーティションキーおよびソートキー) を定義します。また、ベーステーブルからインデックスに*射影* (コピー) したい属性を定義します。DynamoDB では、これらの属性とベーステーブルからのプライマリキー属性がインデックスにコピーされます。次に、テーブルに対してクエリまたはスキャンを実行する場合と同様に、インデックスに対してクエリまたはスキャンを実行します。
すべてのセカンダリインデックスは、DynamoDB によって自動的にメンテナンスされます。ベーステーブルの項目を追加、変更、または削除すると、そのテーブルのインデックスも更新され、この変更が反映されます。
DynamoDB は、次の 2 種類のセカンダリインデックスをサポートしています。
+ **[グローバルセカンダリインデックス](GSI.html) — **パーティションキーおよびソートキーを持つインデックス。ベーステーブルのものとは異なる場合があります。このインデックスに関するクエリがすべてのパーティションにまたがり、ベーステーブル内のすべてのデータを対象とする可能性があるため、グローバルセカンダリインデックスは「グローバル」と見なされます。グローバルセカンダリインデックスは、ベーステーブルとは別に独自のパーティション領域に保存され、ベーステーブルとは別にスケーリングします。
+ **[ローカルセカンダリインデックス](LSI.html) — **パーティションキーはベーステーブルと同じで、ソートキーが異なるインデックス。ローカルセカンダリインデックスは、ローカルセカンダリインデックスのすべてのパーティションの範囲が同じパーティションキーバリューを持つベーステーブルのパーティションに限定されるという意味で「ローカル」です。
グローバルセカンダリインデックスとローカルセカンダリインデックスの比較については、この動画を参照してください。
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/BkEu7zBWge8)
**Topics**
+ [DynamoDB のグローバルセカンダリインデックスの使用](GSI.md)
+ [ローカルセカンダリインデックス](LSI.md)
使用するインデックスの種類を決定するときは、アプリケーションの要件を考慮する必要があります。次の表に、グローバルセカンダリインデックスとローカルセカンダリインデックスの主な違いを示します。
****
| 特徴 | グローバルセカンダリインデックス | ローカルセカンダリインデックス |
| --- | --- | --- |
| キースキーマ | グローバルセカンダリインデックスのプライマリキーはシンプル (パーティションキー) または複合 (パーティションキーとソートキー) のいずれかとすることができます。 | ローカルセカンダリインデックスのプライマリキーは複合 (パーティションキーとソートキー) である必要があります。 |
| キーの属性 | インデックスパーティションキーとソートキー (存在する場合) は、文字列、数値、またはバイナリ型の任意のベーステーブル属性とすることができます。 | インデックスのパーティションキーは、ベーステーブルのパーティションキーと同じ属性です。ソートキーは、文字列、数値、またはバイナリ型の任意のベーステーブル属性とすることができます。 |
| パーティションキー値ごとのサイズ制限 | グローバルセカンダリインデックスのサイズ制限はありません。 | パーティションキーの値ごとに、すべてのインデックス付き項目の合計サイズが、10 GB 以下である必要があります。 |
| オンラインインデックスオペレーション | グローバルセカンダリインデックスは、テーブルの作成と同時に作成できます。また、新しいグローバルセカンダリインデックスを既存のテーブルに追加したり、既存のグローバルセカンダリインデックスを削除したりすることもできます。詳細については、「」を参照してください[DynamoDB のグローバルセカンダリインデックスの管理](GSI.OnlineOps.md) | ローカルセカンダリインデックスは、テーブルの作成と同時に作成されます。ローカルセカンダリインデックスを既存のテーブルに追加したり、既存のローカルセカンダリインデックスを削除したりすることはできません。 |
| クエリとパーティション | グローバルセカンダリインデックスでは、すべてのパーティションでテーブル全体に対してクエリを実行できます。 | ローカルセカンダリインデックスでは、クエリのパーティションキー値で指定された 1 つのパーティションに対してクエリを実行できます。 |
| 読み込み整合性 | グローバルセカンダリインデックスのクエリは結果整合性をサポートします。 | ローカルセカンダリインデックスのクエリを実行するとき、結果整合性または強い整合性のどちらかを選択できます。 |
| プロビジョニングされたスループットの消費 | 各グローバルセカンダリインデックスには、読み込み/書き込みアクティビティに対する独自のプロビジョニングされたスループット設定があります。グローバルセカンダリインデックスのクエリまたはスキャンでは、ベーステーブルからではなく、インデックスからキャパシティーユニットを使用します。同じことが、テーブルへの書き込みによるグローバルセカンダリインデックスの更新にも当てはまります。グローバルテーブルに関連付けられたグローバルセカンダリインデックスは、書き込みキャパシティユニットを使用します。 | ローカルセカンダリインデックスのクエリまたはスキャンでは、ベーステーブルから読み込みキャパシティーユニットを使用します。テーブルに書き込むと、そのローカルセカンダリインデックスも更新されます。この更新では、ベーステーブルから書き込みキャパシティユニットを使用します。グローバルテーブルに関連付けられたローカルセカンダリインデックスは、レプリケートされた書き込みキャパシティユニットを使用します。 |
| 射影される属性 | グローバルセカンダリインデックスのクエリまたはスキャンでは、インデックスに射影された属性のみをリクエストできます。DynamoDB では、テーブルから属性をフェッチしません。 | ローカルセカンダリインデックスをクエリまたはスキャンする場合、インデックスに射影されていない属性をリクエストできます。DynamoDB は、これらの属性をテーブルから自動的に取得します。 |
セカンダリインデックスを持つテーブルを複数作成する場合は、順次作成する必要があります。たとえば、最初のテーブルを作成し、そのテーブルが `ACTIVE` になるまで待ちます。次のテーブルを作成し、そのテーブルが `ACTIVE` になるまで待ちます。セカンダリインデックスを持つ複数のテーブルを同時に作成しようとすると、DynamoDB は `LimitExceededException` を返します。
各セカンダリインデックスは、関連付けられているベーステーブルと同じ[テーブルクラス](HowItWorks.TableClasses.html)と[キャパシティモード](capacity-mode.md)を使用します。各セカンダリインデックスには、以下を指定する必要があります。
+ 作成するインデックスのタイプ – グローバルセカンダリインデックスまたはローカルセカンダリインデックスのいずれか。
+ インデックスの名前。インデックスの名前付けルールは、「[Amazon DynamoDB のクォータ](ServiceQuotas.md)」に示すようにテーブルの場合と同じです。名前は関連付けられているベーステーブルに対して一意である必要がありますが、別のベーステーブルに関連付けられているインデックスでも同じ名前を使用できます。
+ インデックスのキースキーマ。インデックスキースキーマの各属性は、型が `String`、`Number`、または `Binary` の最上位属性である必要があります。ドキュメントとセットを含むその他のデータ型は使用できません。キースキーマのその他の要件は、インデックスの種類によって異なります。
+ グローバルセカンダリインデックスの場合、パーティションキーはベーステーブルの任意のスカラー属性にすることができます。ソートキーはオプションです。このキーもベーステーブルの任意のスカラー属性にすることができます。
+ ローカルセカンダリインデックスの場合、パーティションキーは、ベーステーブルのパーティションキーと同じである必要があります。ソートキーは、非キーベーステーブル属性である必要があります。
+ ベーステーブルからインデックスに射影する追加の属性 (ある場合)。この属性は、すべてのインデックスに自動的に射影されるテーブルのキー属性とは別の属性です。スカラー、ドキュメント、およびセットを含む任意のデータ型の属性を射影できます。
+ インデックスのプロビジョニングされたスループット設定（必要な場合）:
+ グローバルセカンダリインデックスの場合、読み込み/書き込みキャパシティーユニット設定を指定する必要があります。このプロビジョニングされたスループット設定は、ベーステーブルの設定から独立しています。
+ ローカルセカンダリインデックスの場合、読み込み/書き込みキャパシティーユニット設定を指定する必要はありません。ローカルセカンダリインデックスに対する読み込み/書き込みオペレーションは、そのベーステーブルのプロビジョニングされたスループット設定から使用します。
クエリに最大限の柔軟性を持たせるために、テーブルごとに最大 20 個のグローバルセカンダリインデックス (デフォルトのクォータ) および最大 5 個のローカルセカンダリインデックスを作成できます。
テーブルのセカンダリインデックスの詳細なリストを取得するには、`DescribeTable` オペレーションを使用します。`DescribeTable` は、テーブルのすべてのセカンダリインデックスの名前、ストレージサイズ、および項目数を返します。これらの値はリアルタイムでは更新されませんが、約 6 時間ごとに更新されます。
セカンダリインデックスのデータには、`Query` または `Scan` オペレーションを使用してアクセスできます。使用するベーステーブル名とインデックス名、結果で返される属性、および適用する条件式またはフィルタを指定する必要があります。DynamoDB は、結果を昇順で返すことも降順で返すこともできます。
テーブルを削除すると、そのテーブルに関連付けられているすべてのインデックスも削除されます。
ベストプラクティスについては、[DynamoDB でセカンダリインデックスを使用するためのベストプラクティス。](bp-indexes.md) を参照してください。
# DynamoDB のグローバルセカンダリインデックスの使用
アプリケーションによっては、さまざまな属性をクエリ基準に使用して、いろいろな種類のクエリを実行する必要があります。このような要件に対応するために、1 つまたは複数の*グローバルセカンダリインデックス*を作成して、Amazon DynamoDB でこれらのインデックスに対して `Query` リクエストを発行できます。
**Topics**
+ [シナリオ: グローバルセカンダリインデックスの使用](#GSI.scenario)
+ [属性の射影](#GSI.Projections)
+ [マルチ属性キースキーマ](#GSI.MultiAttributeKeys)
+ [グローバルセカンダリインデックスからのデータの読み込み](#GSI.Reading)
+ [テーブルとグローバルセカンダリインデックス間のデータ同期](#GSI.Writes)
+ [グローバルセカンダリインデックスがあるテーブルクラス](#GSI.tableclasses)
+ [グローバルセカンダリインデックスに対するプロビジョニングされたスループットに関する考慮事項](#GSI.ThroughputConsiderations)
+ [グローバルセカンダリインデックスのストレージに関する考慮事項](#GSI.StorageConsiderations)
+ [パターンの設計](GSI.DesignPatterns.md)
+ [DynamoDB のグローバルセカンダリインデックスの管理](GSI.OnlineOps.md)
+ [DynamoDB でのインデックスキー違反の検出と修正](GSI.OnlineOps.ViolationDetection.md)
+ [グローバルセカンダリインデックスの操作: Java](GSIJavaDocumentAPI.md)
+ [グローバルセカンダリインデックスの操作: .NET](GSILowLevelDotNet.md)
+ [AWS CLI を使用した DynamoDBでのグローバルセカンダリインデックスの操作](GCICli.md)
## シナリオ: グローバルセカンダリインデックスの使用
たとえば、`GameScores` という名前のテーブルがあり、モバイルゲームアプリケーションのユーザーとスコアを記録しているとします。`GameScores` の各項目は、パーティションキー (`UserId`) およびソートキー (`GameTitle`) で特定されます。次の図は、テーブル内の項目の構成を示しています。一部表示されていない属性もあります。
![\[ユーザー ID、タイトル、スコア、日付、および勝敗のリストを含む GameScores テーブル。\]](http://docs.aws.amazon.com/ja_jp/amazondynamodb/latest/developerguide/images/GSI_01.png)
ここで、各ゲームの最高スコアを表示する順位表アプリケーションを作成すると仮定します。キー属性 (`UserId` と `GameTitle`) を指定したクエリは非常に効率的です。ただし、アプリケーションが `GameScores` だけに基づいて `GameTitle` からデータを取り出す必要がある場合、`Scan` オペレーションを使用する必要があります。テーブルに追加される項目が増えるにつれ、すべてのデータのスキャンは低速で非効率的になります。このため、次のような質問に答えることが難しくなります。
+ ゲーム Meteor Blasters で記録された最高スコアはいくつですか?
+ Galaxy Invaders で最高スコアを獲得したユーザーは誰ですか?
+ 勝敗の最も高い比率は何ですか?
グローバルセカンダリインデックスを作成して、非キー属性に対するクエリの速度を上げることができます。グローバルセカンダリインデックスには、ベーステーブルからの属性の一部が格納されますが、それらはテーブルのプライマリキーとは異なるプライマリキーによって構成されます。インデックスキーは、テーブルからのキー属性を持つ必要がありません。また、テーブルと同じキースキーマを使用する必要もありません。
例えば、パーティションキーとして `GameTitle`、ソートキーとして `TopScore` を使用して、`GameTitleIndex` という名前のグローバルセカンダリインデックスを作成できます。ベーステーブルのプライマリキー属性は必ずインデックスに射影されるので、`UserId` 属性も存在します。次の図は、`GameTitleIndex` インデックスを示しています。
![\[タイトル、スコア、およびユーザー ID のリストを含む GameTitleIndex テーブル。\]](http://docs.aws.amazon.com/ja_jp/amazondynamodb/latest/developerguide/images/GSI_02.png)
これで、`GameTitleIndex` に対してクエリを実行し、Meteor Blasters のスコアを簡単に入手できるようになります。結果は、ソートキーの値 `TopScore` 別に並べられます。`ScanIndexForward` パラメータを false に設定した場合、結果は降順で返されます。つまり、最高スコアが最初に返されます。
すべてのグローバルセカンダリインデックスには、パーティションキーが必要で、オプションのソートキーを指定できます。インデックスキースキーマは、テーブルスキーマとは異なるものにすることができます。シンプルなプライマリキー (パーティションキー) を持つテーブルを作成し、複合プライマリキー (パーティションキーおよびソートキー) を使用してグローバルセカンダリインデックスを作成できます。またはその逆もあります。インデックスキー属性は、ベーステーブルからの任意の最上位 `String`、`Number`、または `Binary` 属性で構成できます。その他のスカラー型、ドキュメント型、およびセット型は許可されません。
必要な場合、他のベーステーブル属性をインデックスに射影できます。インデックスのクエリを行うと、DynamoDB ではこれらの射影された属性を効率的に取り出すことができます。ただし、グローバルセカンダリインデックス のクエリでは、ベーステーブルから属性をフェッチできません。たとえば、上記の図に示すように、`GameTitleIndex` にクエリを実行した場合、クエリは `TopScore` 以外の非キー属性にアクセスすることはできません (キー属性 `GameTitle` と `UserId` は自動的に射影されます)。
DynamoDB テーブルでは、各キー値は一意である必要があります。ただし、グローバルセカンダリインデックスのキー値は一意である必要はありません。たとえば、Comet Quest という名前のゲームが特に難しく、多くの新しいユーザーが試しても、ゼロを上回るスコアを獲得することができないとします。以下にこれを表すいくつかのデータを示します。
****
| UserId | GameTitle | TopScore |
| --- | --- | --- |
| 123 | Comet Quest | 0 |
| 201 | Comet Quest | 0 |
| 301 | Comet Quest | 0 |
このデータを `GameScores` テーブルに追加すると、DynamoDB はそのデータを `GameTitleIndex` に伝達します。`GameTitle` として Comet Quest を `TopScore` として 0 を指定してインデックスに対するクエリを実行すると、次のデータが返されます。
![\[タイトル、最上位スコア、およびユーザー ID のリストを含むテーブル。\]](http://docs.aws.amazon.com/ja_jp/amazondynamodb/latest/developerguide/images/GSI_05.png)
指定したキー値を持つ項目だけがレスポンスに表示されます。その一連のデータ内では、項目は特定の順に並んでいません。
グローバルセカンダリインデックスは、キー属性が実際に存在するデータ項目のみを追跡します。たとえば、別の新しい項目を `GameScores` テーブルに追加し、必須のプライマリキー属性だけを指定したとします。
****
| UserId | GameTitle |
| --- | --- |
| 400 | Comet Quest |
`TopScore` 属性を指定していないので、DynamoDB は、この項目を `GameTitleIndex` に伝達しません。このため、すべての Comet Quest 項目を対象に、`GameScores` に対してクエリを実行した場合、次の 4 つの項目が返されます。
![\[4 つのタイトル、最上位スコア、およびユーザー ID のリストを含むテーブル。\]](http://docs.aws.amazon.com/ja_jp/amazondynamodb/latest/developerguide/images/GSI_04.png)
`GameTitleIndex` に対して同様のクエリを実行すると、4 つではなく 3 つの項目が返されます。これは、`TopScore` が存在しない項目はインデックスに反映されないためです。
![\[3 つのタイトル、最上位スコア、およびユーザー ID のリストを含むテーブル。\]](http://docs.aws.amazon.com/ja_jp/amazondynamodb/latest/developerguide/images/GSI_05.png)
## 属性の射影
*射影*とは、テーブルからセカンダリインデックスにコピーされる属性のセットです。テーブルのパーティションキーとソートキーは常にインデックスに射影されます。アプリケーションのクエリ要件をサポートするために、他の属性を射影できます。インデックスをクエリすると、Amazon DynamoDB は、その属性が自身のテーブル内にあるかのように、プロジェクション内の任意の属性にアクセスできます。
セカンダリインデックスを作成するときは、インデックスに射影される属性を指定する必要があります。DynamoDB には、そのために次の 3 つのオプションが用意されています。
+ *KEYS\$1ONLY* – インデックス内の各項目は、テーブルパーティションキーとソートキーの値、およびインデックスキーの値のみで構成されます。`KEYS_ONLY` オプションを指定すると、セカンダリインデックスが最小になります。
+ *INCLUDE* – `KEYS_ONLY` の属性に加えて、セカンダリインデックスにその他の非キー属性が含まれるように指定できます。
+ *ALL* – セカンダリインデックスには、ソーステーブルのすべての属性が含まれます。すべてのテーブルデータがインデックスに複製されるため、`ALL` の射影にすると、セカンダリインデックスが最大になります。
前の図では、`GameTitleIndex` には 1 つの射影された属性 `UserId` のみがあります。そのため、アプリケーションはクエリで `UserId` および `GameTitle` を使用して各ゲームのトップスコアラーの `TopScore` を効率的に判断できますが、トップスコアラーの勝敗の最も高い比率は効率的に判断できません。そのためには、アプリケーションは基本テーブルで追加のクエリを実行して、各トップスコアラーの勝敗を取得する必要があります。このデータに対するクエリのサポートを効率化する方法として、次の図に示すように、これらの属性をベーステーブルからグローバルセカンダリインデックスに射影する方法があります。
![\[効率的なクエリのサポートのために非キー属性を GSI に射影する説明図。\]](http://docs.aws.amazon.com/ja_jp/amazondynamodb/latest/developerguide/images/GSI_06.png)
非キー属性 `Wins` と `Losses` がインデックスに射影されるので、アプリケーションは、任意のゲーム、またはゲームとユーザー ID の任意の組み合わせに対して、勝敗の比率を特定できます。
グローバルセカンダリインデックスに射影する属性を選択する場合には、プロビジョニングされるスループットコストとストレージコストのトレードオフを考慮する必要があります。
+ ごく一部の属性だけに最小のレイテンシーでアクセスする必要がある場合は、それらの属性だけをグローバルセカンダリインデックスに射影することを検討してください。インデックスが小さいほど少ないコストで格納でき、書き込みコストも低くなります。
+ アプリケーションが非キー属性に頻繁にアクセスする場合には、それらの属性をグローバルセカンダリインデックスに射影することを検討してください。グローバルセカンダリインデックスのストレージコストの増加は、頻繁にテーブルスキャンを実行するコストの減少で相殺されます。
+ ほとんどの非キー属性に頻繁にアクセスする場合は、それらの属性を (場合によっては、ベーステーブル全体を) グローバルセカンダリインデックスに射影することができます。これにより、最大限の柔軟性が得られます。ただし、ストレージコストは増加するか、倍になります。
+ アプリケーションでテーブルのクエリを頻繁に行う必要がなく、テーブル内のデータに対する書き込みや更新が多数になる場合は、`KEYS_ONLY` を射影することを検討してください。グローバルセカンダリインデックスは、最小サイズになりますが、それでもクエリのアクティビティに必要な場合は利用可能です。
## マルチ属性キースキーマ
グローバルセカンダリインデックスはマルチ属性キーをサポートしているため、複数の属性からパーティションキーとソートキーを作成できます。マルチ属性キーを使用すると、最大 4 つの属性からパーティションキーを、最大 4 つの属性からソートキーを、キースキーマごとに合計で最大 8 つの属性に作成できます。
マルチ属性キーは、属性を合成キーに手動で連結する必要がなくなるため、データモデルを簡素化します。`TOURNAMENT#WINTER2024#REGION#NA-EAST` のような複合文字列を作成する代わりに、ドメインモデルから自然属性を直接使用できます。DynamoDB は複合キーロジックを自動的に処理し、データ分散のために複数のパーティションキー属性をハッシュし、複数のソートキー属性にわたって階層型のソート順序を維持します。
例えば、試合をトーナメントとリージョン別に整理するゲームトーナメントシステムを考えてみましょう。マルチ属性キーを使用すると、パーティションキーを `tournamentId` と `region` の 2 つの異なる属性として定義できます。同様に、`round`、`bracket`、`matchId` などの複数の属性を使用してソートキーを定義し、自然な階層を作成できます。このアプローチでは、文字列の操作や解析を行わずに、データ型とコードをクリーンに保ちます。
マルチ属性キーを使用してグローバルセカンダリインデックスをクエリする場合は、等号条件を使用してすべてのパーティションキー属性を指定する必要があります。ソートキー属性の場合、キースキーマで定義されている順序で、左から右にクエリを実行できます。つまり、最初のソートキー属性のみ、最初の 2 つの属性を一緒に、またはすべての属性を一緒にクエリできますが、途中で属性をスキップすることはできません。`>`、`<`、`BETWEEN`、`begins_with()` などの不等条件は、クエリの最後の条件である必要があります。
マルチ属性キーは、既存のテーブルにグローバルセカンダリインデックスを作成する場合、特に効果的です。データ全体で合成キーをバックフィルすることなく、テーブルに既に存在する属性を使用できます。これにより、さまざまな属性の組み合わせを使用してデータを再編成するインデックスを作成することで、アプリケーションに新しいクエリパターンを簡単に追加できます。
マルチ属性キーの各属性は、独自のデータ型 `String` (S)、`Number` (N)、または `Binary` (B) を持つことができます。データ型を選択するときは、ゼロパディングを必要とせずに `Number` 属性を数値順にソートし、`String` 属性を辞書順にソートすることを検討してください。例えば、スコア属性に `Number` 型を使用する場合、値 5、50、500、1000 は自然な数値順にソートされます。同じ値を `String` 型とする場合は、先頭にゼロを埋めない限り、「1000」、「5」、「50」、「500」とソートされます。
マルチ属性キーを設計する場合は、属性を最も一般的なものから最も具体的な順に並べてください。パーティションキーの場合、常に一緒にクエリされ、適切なデータ分散を提供する属性を組み合わせます。ソートキーの場合、クエリの柔軟性を最大化するために、頻繁にクエリされる属性を階層の最初に配置します。この順序により、アクセスパターンに一致する任意の詳細度のレベルでクエリを実行できます。
実装例については、「[マルチ属性キー](GSI.DesignPattern.MultiAttributeKeys.md)」を参照してください。
## グローバルセカンダリインデックスからのデータの読み込み
グローバルセカンダリインデックスから項目を取得するには、`Query` および `Scan` オペレーションを使用します。`GetItem` および `BatchGetItem` オペレーションは、グローバルセカンダリインデックスでは使用できません。
### グローバルセカンダリインデックスのクエリ
`Query` オペレーションを使用して、グローバルセカンダリインデックスの 1 つ以上の項目にアクセスすることができます。クエリでは、使用するベーステーブル名とインデックス名、クエリ結果で返される属性、および適用するクエリ条件を指定する必要があります。DynamoDB は、結果を昇順で返すことも降順で返すこともできます。
順位表アプリケーションのゲームデータをリクエストする `Query` から返される次のデータについて考えます。
```
{
"TableName": "GameScores",
"IndexName": "GameTitleIndex",
"KeyConditionExpression": "GameTitle = :v_title",
"ExpressionAttributeValues": {
":v_title": {"S": "Meteor Blasters"}
},
"ProjectionExpression": "UserId, TopScore",
"ScanIndexForward": false
}
```
このクエリでは次のようになっています。
+ DynamoDB は、*GameTitle* パーティションキーを使用して *GameTitleIndex* にアクセスし、Meteor Blasters のインデックス項目を特定します。このキーを持つすべてのインデックス項目が、すばやく取り出せるように隣り合わせに格納されます。
+ このゲーム内で、DynamoDB はインデックスを使用して、このゲームのすべてのユーザーの ID と最高スコアにアクセスします。
+ `ScanIndexForward` パラメータが false に設定されているので、結果は降順で返されます。
### グローバルセカンダリインデックスのスキャン
`Scan` オペレーションを使用して、グローバルセカンダリインデックスからすべてのデータを取得することができます。リクエストにはベーステーブル名とインデックス名を指定する必要があります。`Scan` では、DynamoDB はインデックスのすべてのデータを読み込み、それをアプリケーションに返します。また、データの一部のみを返し、残りのデータを破棄するようにリクエストすることもできます。これを行うには、`FilterExpression` オペレーションの `Scan` パラメータを使用します。詳細については、「」を参照してください[Scan のフィルタ式](Scan.md#Scan.FilterExpression)
## テーブルとグローバルセカンダリインデックス間のデータ同期
DynamoDB では、各グローバルセカンダリインデックスをそのベーステーブルと自動的に同期させています。アプリケーションがテーブルに項目を書き込むか、削除すると、そのテーブルのすべてのグローバルセカンダリインデックスは、結果整合性モデルを使用して、非同期で更新されます。アプリケーションがインデックスに直接書き込むことはありません。ただし、DynamoDB でこれらのインデックスがどのように維持されるかを理解することは重要です。
グローバルセカンダリーインデックスは、基本テーブルから読み込み/書き込みキャパシティーモードを継承します。詳細については、「[DynamoDB でキャパシティモードを切り替える際の考慮事項](bp-switching-capacity-modes.md)」を参照してください。
グローバルセカンダリインデックスを作成するときは、1 つ以上のインデックスキー属性およびそれらのデータ型を指定します。つまり、ベーステーブルに項目を書き込むとき、それらの属性のデータ型が、インデックスキースキーマのデータ型に一致する必要があります。`GameTitleIndex` の場合、インデックス内の `GameTitle` パーティションキーは、`String` データ型として定義されています。インデックス内の `TopScore` ソートキーは、`Number` の型です。`GameScores` テーブルに項目を追加し、`GameTitle` または `TopScore` に対して別のデータ型を指定する場合、データ型の不一致により DynamoDB によって `ValidationException` が返されます。
テーブルに項目を入力するか、削除すると、そのテーブルのグローバルセカンダリインデックスは、結果整合性のある方法で更新されます。テーブルデータへの変更は、通常は、瞬時にグローバルセカンダリインデックスに伝達されます。ただし、万が一障害が発生した場合は、長い伝達遅延が発生することがあります。このため、アプリケーションでは、グローバルセカンダリインデックスに関するクエリに対して、最新でない結果が返される状況を予期し、それに対応する必要があります。
テーブルに項目を書き込む場合には、グローバルセカンダリインデックスのソートキーに対して属性を指定する必要はありません。`GameTitleIndex` を例にとると、`GameScores` テーブルに新しい項目を書き込むために、`TopScore` 属性に値を指定する必要はありません。このケースでは、DynamoDB はこの特定の項目のインデックスにデータを書き込むことはありません。
多数のグローバルセカンダリインデックスがあるテーブルは、インデックス数が少ないテーブルに比べて書き込みアクティビティに多くのコストを要します。詳細については、「[グローバルセカンダリインデックスに対するプロビジョニングされたスループットに関する考慮事項](#GSI.ThroughputConsiderations)」を参照してください。
## グローバルセカンダリインデックスがあるテーブルクラス
グローバルセカンダリインデックスは、常にベーステーブルと同じテーブルクラスを使用します。テーブルに新しいグローバルセカンダリインデックスが追加されるたびに、新しいインデックスはベーステーブルと同じテーブルクラスを使用します。テーブルのテーブルクラスが更新されると、関連するすべてのグローバルセカンダリインデックスも更新されます。
## グローバルセカンダリインデックスに対するプロビジョニングされたスループットに関する考慮事項
プロビジョニングモードのテーブルでグローバルセカンダリインデックスを作成するときには、そのインデックスに対して予想されるワークロードに応じた読み込み/書き込みキャパシティーユニットを指定する必要があります。グローバルセカンダリインデックスのプロビジョニングされたスループット設定は、そのベーステーブルの設定とは独立しています。グローバルセカンダリインデックスに対する `Query` オペレーションでは、ベーステーブルではなく、インデックスから読み込みキャパシティーユニットを使用します。テーブルで項目を入力、更新または削除すると、そのテーブルのグローバルセカンダリインデックスも更新されます。これらのインデックス更新は、ベーステーブルからではなく、インデックスから書き込みキャパシティーユニットを消費します。
例えば、グローバルセカンダリインデックスに対して `Query` を実行し、そのプロビジョニングされた読み込みキャパシティーを超えた場合、リクエストは調整されます。多量の書き込みアクティビティをテーブルに対して実行するときに、そのテーブルのグローバルセカンダリインデックスに十分な書き込み容量がない場合、そのテーブルに対する書き込みアクティビティは調整されます。
**重要**
スロットリングを避けるため、グローバルセカンダリインデックスのプロビジョニングされた書き込みキャパシティーは、ベーステーブルの書き込みキャパシティーと同じかそれより大きい必要があります。これは、新しい更新ではベーステーブルとグローバルセカンダリインデックスの両方に書き込むためです。
グローバルセカンダリインデックスのプロビジョニングされたスループット設定を表示するには、`DescribeTable` オペレーションを使用します。テーブルのすべてのグローバルセカンダリインデックスに関する詳細情報が返されます。
### 読み込みキャパシティユニット
グローバルセカンダリインデックスでは、結果整合性のある読み込みをサポートしており、各読み込みで、読み込みキャパシティーユニットの半分を消費します。つまり、1 回のグローバルセカンダリインデックスのクエリでは、1 読み込みキャパシティーユニットあたり最大 2 × 4 KB = 8 KB を取り出すことができます。
グローバルセカンダリインデックスのクエリの場合、DynamoDB はプロビジョニングされた読み込みアクティビティをテーブルに対するクエリと同じ方法で計算します。唯一の違いは、ベーステーブル内の項目のサイズではなくインデックスエントリのサイズに基づいて計算が行われることです。読み込みキャパシティーユニットの数は、返されたすべての項目について射影されたすべての属性のサイズの合計です。結果は、次の 4 KB 境界まで切り上げられます。DynamoDB がプロビジョニングされたスループットの利用率を計算する方法の詳細については、「[DynamoDB プロビジョンドキャパシティモード](provisioned-capacity-mode.md)」を参照してください。
`Query` オペレーションによって返される結果の最大サイズは 1 MB です。これには、返されるすべての項目にわたる、すべての属性の名前と値のサイズが含まれます。
例えば、各項目に 2,000 バイトのデータが格納されているグローバルセカンダリインデックスがあるとします。このインデックスに対して `Query` を実行したら、クエリの `KeyConditionExpression` が 8 項目に一致したとします。一致する項目の合計サイズは、2,000 バイト × 8 項目 = 16,000 バイトです。これは、最も近い 4 KB 境界に切り上げられます。グローバルセカンダリインデックスのクエリは結果整合性なので、合計コストは、0.5 × (16 KB / 4 KB)、つまり、2 読み込みキャパシティーユニットです。
### 書き込みキャパシティユニット
テーブルの項目が追加、更新、または削除されたときに、グローバルセカンダリインデックスがこの影響を受ける場合、グローバルセカンダリインデックスは、そのオペレーションに対してプロビジョニングされた書き込みキャパシティーユニットを使用します。書き込み用にプロビジョニングされたスループットの合計コストは、ベーステーブルに対する書き込みと、グローバルセカンダリインデックスの更新で消費された書き込みキャパシティーユニットの合計になります。テーブルへの書き込みには、グローバルセカンダリインデックスの更新は必要ないので、インデックスから使用される書き込み容量はありません。
テーブルへの書き込みに成功するように、テーブルとそのすべてのグローバルセカンダリインデックスに対するプロビジョニングされたスループット設定は、書き込みに対応できるだけの十分な書き込みキャパシティーを備えている必要があります。十分でない場合、書き込みが調整されます。
**重要**
グローバルセカンダリインデックス (GSI) を作成する際、基本テーブルへの書き込みによって生じる GSI アクティビティが GSI のプロビジョニングされた書き込み容量を超える場合、基本テーブルへの書き込み操作がスロットリングされる可能性があります。このスロットリングは、インデックス作成プロセスから本番ワークロードの中断の可能性に至るまで、すべての書き込み操作に影響します。詳細については、「[Amazon DynamoDB でのスロットリングのトラブルシューティング](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TroubleshootingThrottling.html)」を参照してください。
グローバルセカンダリインデックスに項目を書き込むコストは、いくつかの要因に左右されます。
+ インデックス付き属性が定義されたテーブルに新しい項目を書き込む場合、または既存の項目を更新して未定義のインデックス付き属性を定義する場合には、インデックスへの項目の挿入に 1 回の書き込みオペレーションが必要です。
+ テーブルに対する更新によってインデックス付きキー属性の値が（A から B に）変更された場合には、インデックスから既存の項目を削除し、インデックスに新しい項目を挿入するために、2 回の書き込みが必要です。
+ インデックス内に既存の項目があって、テーブルに対する書き込みによってインデックス付き属性が削除された場合は、インデックスから古い項目の射影を削除するために、1 回の書き込みが必要です。
+ 項目の更新の前後にインデックス内に項目が存在しない場合は、インデックスで追加の書き込みコストは発生しません。
+ テーブルに対する更新によってインデックスキースキーマの射影された属性の値のみが変更され、インデックス付きキー属性の値は変更されない場合は、インデックスに射影された属性の値を更新するために、1 回の書き込みが必要です。
これらすべての要因は、インデックス内の各項目のサイズが 1 KB 以下であるという前提で書き込みキャパシティーユニット数を算出します。インデックスエントリがそれよりも大きい場合は、書き込みキャパシティーユニットを追加する必要があります。クエリが返す必要がある属性を特定し、それらの属性だけをインデックスに射影することで、書き込みコストは最小になります。
## グローバルセカンダリインデックスのストレージに関する考慮事項
アプリケーションがテーブルに項目を書き込むと、DynamoDB では、正しい属性のサブセットが、それらの属性が現れる必要があるグローバルセカンダリインデックスに自動的にコピーされます。AWS アカウントでは、テーブル内の項目のストレージと、そのベーステーブルのグローバルセカンダリインデックスにある属性のストレージに対して課金されます。
インデックス項目が使用するスペースの量は、次の量の合計になります。
+ ベーステーブルのプライマリキー (パーティションキーとソートキー) のサイズのバイト数
+ インデックスキー属性のサイズのバイト数
+ 射影された属性（存在する場合）のサイズのバイト数
+ インデックス項目あたり 100 バイトのオーバーヘッド
グローバルセカンダリインデックスのストレージ要件の見積もりは、インデックス内の 1 項目の平均サイズの見積もり値に、ベーステーブル内のグローバルセカンダリインデックスキー属性を持つ項目の数を掛けて算出します。
特定の属性が定義されていない項目がテーブルに含まれていて、その属性がインデックスパーティションキーまたはソートキーとして定義されている場合、DynamoDB はその項目のデータをインデックスに書き込みません。
# パターンの設計
設計パターンは、グローバルセカンダリインデックスを使用する際の一般的な課題に対する実証済みのソリューションを提供します。これらのパターンは、特定のユースケースに合わせてインデックスを構築する方法を示すことで、効率的でスケーラブルなアプリケーションを構築するのに役立ちます。
各パターンには、独自のアプリケーションにパターンを適用するのに役立つコード例、ベストプラクティス、実際のユースケースを含む完全な実装ガイドが含まれています。
**Topics**
+ [マルチ属性キー](GSI.DesignPattern.MultiAttributeKeys.md)
# マルチ属性キーパターン
## 概要
マルチ属性キーを使用すると、それぞれ最大 4 つの属性で構成されるグローバルセカンダリインデックス (GSI) パーティションとソートキーを作成できます。これにより、クライアント側のコードが減り、最初にデータをモデル化し、後で新しいアクセスパターンを追加することが容易になります。
一般的なシナリオを考えてみましょう。複数の階層属性で項目をクエリする GSI を作成するには、従来、値を連結して合成キーを作成する必要があります。例えば、ゲームアプリでは、トーナメント、リージョン、ラウンドでトーナメントマッチをクエリするために、TOURNAMENT\$1WINTER2024\$1REGION\$1NA-EAST などの合成 GSI パーティションキーと ROUND\$1SEMIFINALS\$1BRACKET\$1UPPER などの合成ソートキーを作成できます。このアプローチは機能しますが、既存のテーブルに GSI を追加する場合は、データを書き込むときに文字列を連結し、読み取り時に解析し、既存のすべての項目にわたって合成キーをバックフィルする必要があります。これにより、コードが整理整頓され、個々のキーコンポーネントで型の安全性を維持することが困難になります。
マルチ属性キーは、GSI のこの問題を解決します。GSI パーティションキーは、tournamentId や region などの複数の既存の属性を使用して定義します。DynamoDB は複合キーロジックを自動的に処理し、データ分散のためにそれらをハッシュします。ドメインモデルから自然属性を使用して項目を記述すると、GSI は自動的にインデックスを作成します。連結なし、解析なし、バックフィルなし。コードはきれいに保たれ、データは入力され、クエリはシンプルになります。このアプローチは、自然属性のグループ化を含む階層データがある場合に特に役立ちます (トーナメント → リージョン → ラウンド、または組織 → 部門 → チームなど)。
## アプリケーションの例
このガイドでは、e スポーツプラットフォームのトーナメントマッチ追跡システムを構築する方法について説明します。プラットフォームは、ブラケット管理のためのトーナメントとリージョン、マッチング履歴のための選手、スケジューリングのための日付など、複数のディメンションにわたって試合を効率的にクエリする必要があります。
## データモデル
このチュートリアルでは、トーナメントマッチ追跡システムは 3 つの主要なアクセスパターンをサポートし、それぞれに異なるキー構造が必要です。
**アクセスパターン 1:** 一意の ID で特定の試合を検索する
+ **解決策:** パーティションキーとして `matchId` をベーステーブルと使用する
**アクセスパターン 2:** 特定のトーナメントとリージョンのすべての試合をクエリし、オプションでラウンド、ブラケット、または試合でフィルタリングする
+ **解決策:** マルチ属性パーティションキー (`tournamentId` \$1 `region`) とマルチ属性ソートキー (`round` \$1 `bracket` \$1 `matchId`) を持つグローバルセカンダリインデックス
+ **クエリの例:** 「NA-EAST リージョン内の All WINTER2024 の試合」、または「WINTER2024/NA-EAST の UPPER ブラケット内の All SEMIFINALS の試合」
**アクセスパターン 3:** 選手の試合履歴をクエリし、オプションで日付範囲またはトーナメントラウンドでフィルタリングする
+ **解決策:** 単一パーティションキー (`player1Id`) とマルチ属性ソートキー (`matchDate` \$1 `round`) を持つグローバルセカンダリインデックス
+ **クエリの例:** 「プレイヤー 101 のすべての試合」または「2024 年 1 月の選手 101 の試合」
従来およびマルチ属性アプローチの主な違いは、項目構造を調べるときにはっきりします。
**従来のグローバルセカンダリインデックスのアプローチ (連結キー):**
```
// Manual concatenation required for GSI keys
const item = {
matchId: 'match-001', // Base table PK
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '101',
// Synthetic keys needed for GSI
GSI_PK: `TOURNAMENT#${tournamentId}#REGION#${region}`, // Must concatenate
GSI_SK: `${round}#${bracket}#${matchId}`, // Must concatenate
// ... other attributes
};
```
**マルチ属性のグローバルセカンダリインデックスのアプローチ (ネイティブキー):**
```
// Use existing attributes directly - no concatenation needed
const item = {
matchId: 'match-001', // Base table PK
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '101',
matchDate: '2024-01-18',
// No synthetic keys needed - GSI uses existing attributes directly
// ... other attributes
};
```
マルチ属性キーでは、自然ドメイン属性を使用して項目を 1 回書き込みます。DynamoDB は、合成連結キーを必要とせずに、複数の GSI 間で自動的にインデックスを作成します。
**ベーステーブルスキーマ:**
+ パーティションキー: `matchId` (1 属性)
**グローバルセカンダリインデックススキーマ (マルチ属性キーを持つ TournamentRegionIndex):**
+ パーティションキー: `tournamentId`、`region` (2 属性)
+ ソートキー: `round`、`bracket`、`matchId` (3 属性)
**グローバルセカンダリインデックススキーマ (マルチ属性キーを持つ PlayerMatchHistoryIndex):**
+ パーティションキー: `player1Id` (1 属性)
+ ソートキー: `matchDate`、`round` (2 属性)
### ベーステーブル: TournamentMatches
| matchId (PK) | tournamentId | リージョン | round | ブラケット | player1Id | player2Id | matchDate | 勝者 | score |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| match-001 | WINTER2024 | NA-EAST | FINALS | CHAMPIONSHIP | 101 | 103 | 2024-01-20 | 101 | 3-1 |
| match-002 | WINTER2024 | NA-EAST | SEMIFINALS | UPPER | 101 | 105 | 2024-01-18 | 101 | 3-2 |
| match-003 | WINTER2024 | NA-EAST | SEMIFINALS | UPPER | 103 | 107 | 2024-01-18 | 103 | 3-0 |
| match-004 | WINTER2024 | NA-EAST | QUARTERFINALS | UPPER | 101 | 109 | 2024-01-15 | 101 | 3-1 |
| match-005 | WINTER2024 | NA-WEST | FINALS | CHAMPIONSHIP | 102 | 104 | 2024-01-20 | 102 | 3-2 |
| match-006 | WINTER2024 | NA-WEST | SEMIFINALS | UPPER | 102 | 106 | 2024-01-18 | 102 | 3-1 |
| match-007 | SPRING2024 | NA-EAST | QUARTERFINALS | UPPER | 101 | 108 | 2024-03-15 | 101 | 3-0 |
| match-008 | SPRING2024 | NA-EAST | QUARTERFINALS | LOWER | 103 | 110 | 2024-03-15 | 103 | 3-2 |
### GSI: TournamentRegionIndex (マルチ属性キー)
| tournamentId (PK) | リージョン (PK) | ラウンド (SK) | ブラケット (SK) | matchId (SK) | player1Id | player2Id | matchDate | 勝者 | score |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| WINTER2024 | NA-EAST | FINALS | CHAMPIONSHIP | match-001 | 101 | 103 | 2024-01-20 | 101 | 3-1 |
| WINTER2024 | NA-EAST | QUARTERFINALS | UPPER | match-004 | 101 | 109 | 2024-01-15 | 101 | 3-1 |
| WINTER2024 | NA-EAST | SEMIFINALS | UPPER | match-002 | 101 | 105 | 2024-01-18 | 101 | 3-2 |
| WINTER2024 | NA-EAST | SEMIFINALS | UPPER | match-003 | 103 | 107 | 2024-01-18 | 103 | 3-0 |
| WINTER2024 | NA-WEST | FINALS | CHAMPIONSHIP | match-005 | 102 | 104 | 2024-01-20 | 102 | 3-2 |
| WINTER2024 | NA-WEST | SEMIFINALS | UPPER | match-006 | 102 | 106 | 2024-01-18 | 102 | 3-1 |
| SPRING2024 | NA-EAST | QUARTERFINALS | LOWER | match-008 | 103 | 110 | 2024-03-15 | 103 | 3-2 |
| SPRING2024 | NA-EAST | QUARTERFINALS | UPPER | match-007 | 101 | 108 | 2024-03-15 | 101 | 3-0 |
### GSI: PlayerMatchHistoryIndex (マルチ属性キー)
| player1Id (PK) | matchDate (SK) | ラウンド (SK) | tournamentId | リージョン | ブラケット | matchId | player2Id | 勝者 | score |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 101 | 2024-01-15 | QUARTERFINALS | WINTER2024 | NA-EAST | UPPER | match-004 | 109 | 101 | 3-1 |
| 101 | 2024-01-18 | SEMIFINALS | WINTER2024 | NA-EAST | UPPER | match-002 | 105 | 101 | 3-2 |
| 101 | 2024-01-20 | FINALS | WINTER2024 | NA-EAST | CHAMPIONSHIP | match-001 | 103 | 101 | 3-1 |
| 101 | 2024-03-15 | QUARTERFINALS | SPRING2024 | NA-EAST | UPPER | match-007 | 108 | 101 | 3-0 |
| 102 | 2024-01-18 | SEMIFINALS | WINTER2024 | NA-WEST | UPPER | match-006 | 106 | 102 | 3-1 |
| 102 | 2024-01-20 | FINALS | WINTER2024 | NA-WEST | CHAMPIONSHIP | match-005 | 104 | 102 | 3-2 |
| 103 | 2024-01-18 | SEMIFINALS | WINTER2024 | NA-EAST | UPPER | match-003 | 107 | 103 | 3-0 |
| 103 | 2024-03-15 | QUARTERFINALS | SPRING2024 | NA-EAST | LOWER | match-008 | 110 | 103 | 3-2 |
## 前提条件
開始する前に、以下を確認してください。
### アカウントとアクセス許可
+ アクティブな AWS アカウント (必要に応じて[ここで作成](https://aws.amazon.com/free/))
+ DynamoDB オペレーションの IAM アクセス許可:
+ `dynamodb:CreateTable`
+ `dynamodb:DeleteTable`
+ `dynamodb:DescribeTable`
+ `dynamodb:PutItem`
+ `dynamodb:Query`
+ `dynamodb:BatchWriteItem`
**注記**
**セキュリティ上の注意:** 本番稼働用には、必要なアクセス許可のみを持つカスタム IAM ポリシーを作成します。このチュートリアルでは、AWS 管理ポリシー `AmazonDynamoDBFullAccessV2` を使用できます。
### 開発環境
+ マシンにインストールされている「Node.js」
+ 次のいずれかの方法を使用して設定される AWS 認証情報
**オプション 1: AWS CLI**
```
aws configure
```
**オプション 2: 環境変数**
```
export AWS_ACCESS_KEY_ID=your_access_key_here
export AWS_SECRET_ACCESS_KEY=your_secret_key_here
export AWS_DEFAULT_REGION=us-east-1
```
### 必要なパッケージのインストール
```
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
```
## 実装
### ステップ 1: マルチ属性キーを使用して GSI でテーブルを作成する
シンプルなベースキー構造と、マルチ属性キーを使用する GSI を持つテーブルを作成します。
#### コード例
```
import { DynamoDBClient, CreateTableCommand } from "@aws-sdk/client-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const response = await client.send(new CreateTableCommand({
TableName: 'TournamentMatches',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'matchId', KeyType: 'HASH' } // Simple PK
],
AttributeDefinitions: [
{ AttributeName: 'matchId', AttributeType: 'S' },
{ AttributeName: 'tournamentId', AttributeType: 'S' },
{ AttributeName: 'region', AttributeType: 'S' },
{ AttributeName: 'round', AttributeType: 'S' },
{ AttributeName: 'bracket', AttributeType: 'S' },
{ AttributeName: 'player1Id', AttributeType: 'S' },
{ AttributeName: 'matchDate', AttributeType: 'S' }
],
// GSIs with multi-attribute keys
GlobalSecondaryIndexes: [
{
IndexName: 'TournamentRegionIndex',
KeySchema: [
{ AttributeName: 'tournamentId', KeyType: 'HASH' }, // GSI PK attribute 1
{ AttributeName: 'region', KeyType: 'HASH' }, // GSI PK attribute 2
{ AttributeName: 'round', KeyType: 'RANGE' }, // GSI SK attribute 1
{ AttributeName: 'bracket', KeyType: 'RANGE' }, // GSI SK attribute 2
{ AttributeName: 'matchId', KeyType: 'RANGE' } // GSI SK attribute 3
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'PlayerMatchHistoryIndex',
KeySchema: [
{ AttributeName: 'player1Id', KeyType: 'HASH' }, // GSI PK
{ AttributeName: 'matchDate', KeyType: 'RANGE' }, // GSI SK attribute 1
{ AttributeName: 'round', KeyType: 'RANGE' } // GSI SK attribute 2
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}));
console.log("Table with multi-attribute GSI keys created successfully");
```
**主要な設計上の決定事項:**
**ベーステーブル:** ベーステーブルは、直接一致検索にシンプルな `matchId` パーティションキーを使用し、GSI が複雑なクエリパターンを提供する間、ベーステーブル構造を分かりやすく維持します。
**TournamentRegionIndex グローバルセカンダリインデックス:** `TournamentRegionIndex` グローバルセカンダリインデックスは、`tournamentId` \$1 `region` をマルチ属性パーティションキーとして使用し、両方の属性を組み合わせたハッシュによってデータが分散されるトーナメントリージョンの分離を作成し、特定のトーナメントリージョンのコンテキスト内で効率的なクエリを可能にします。マルチ属性ソートキー (`round` \$1 `bracket` \$1 `matchId`) は、階層の任意のレベルでクエリをサポートする階層ソートを提供し、一般的な (ラウンド) から特定の (マッチ ID) へ自然な順序で並べ替えます。
**PlayerMatchHistoryIndex グローバルセカンダリインデックス:** `PlayerMatchHistoryIndex` グローバルセカンダリインデックスは、パーティションキーとして `player1Id` を使用して選手ごとにデータを再編成し、特定の選手のクロストーナメントクエリを有効にします。マルチ属性ソートキー (`matchDate` \$1 `round`) は、日付範囲または特定のトーナメントラウンドでフィルタリングできる時系列の順序を提供します。
### ステップ 2: ネイティブ属性を使用してデータを挿入する
自然属性を使用してトーナメントマッチデータを追加します。GSI は、合成キーを必要とせずに、これらの属性を自動的にインデックス化します。
#### コード例
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Tournament match data - no synthetic keys needed for GSIs
const matches = [
// Winter 2024 Tournament, NA-EAST region
{
matchId: 'match-001',
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'FINALS',
bracket: 'CHAMPIONSHIP',
player1Id: '101',
player2Id: '103',
matchDate: '2024-01-20',
winner: '101',
score: '3-1'
},
{
matchId: 'match-002',
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '101',
player2Id: '105',
matchDate: '2024-01-18',
winner: '101',
score: '3-2'
},
{
matchId: 'match-003',
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '103',
player2Id: '107',
matchDate: '2024-01-18',
winner: '103',
score: '3-0'
},
{
matchId: 'match-004',
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'QUARTERFINALS',
bracket: 'UPPER',
player1Id: '101',
player2Id: '109',
matchDate: '2024-01-15',
winner: '101',
score: '3-1'
},
// Winter 2024 Tournament, NA-WEST region
{
matchId: 'match-005',
tournamentId: 'WINTER2024',
region: 'NA-WEST',
round: 'FINALS',
bracket: 'CHAMPIONSHIP',
player1Id: '102',
player2Id: '104',
matchDate: '2024-01-20',
winner: '102',
score: '3-2'
},
{
matchId: 'match-006',
tournamentId: 'WINTER2024',
region: 'NA-WEST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '102',
player2Id: '106',
matchDate: '2024-01-18',
winner: '102',
score: '3-1'
},
// Spring 2024 Tournament, NA-EAST region
{
matchId: 'match-007',
tournamentId: 'SPRING2024',
region: 'NA-EAST',
round: 'QUARTERFINALS',
bracket: 'UPPER',
player1Id: '101',
player2Id: '108',
matchDate: '2024-03-15',
winner: '101',
score: '3-0'
},
{
matchId: 'match-008',
tournamentId: 'SPRING2024',
region: 'NA-EAST',
round: 'QUARTERFINALS',
bracket: 'LOWER',
player1Id: '103',
player2Id: '110',
matchDate: '2024-03-15',
winner: '103',
score: '3-2'
}
];
// Insert all matches
for (const match of matches) {
await docClient.send(new PutCommand({
TableName: 'TournamentMatches',
Item: match
}));
console.log(`Added: ${match.matchId} - ${match.tournamentId}/${match.region} - ${match.round} ${match.bracket}`);
}
console.log(`\nInserted ${matches.length} tournament matches`);
console.log("No synthetic keys created - GSIs use native attributes automatically");
```
**データ構造の説明:**
**自然属性の使用:** 各属性は、文字列の連結や解析を必要とせずに実際のトーナメントの概念を表し、ドメインモデルへの直接マッピングを提供します。
**自動グローバルセカンダリインデックスの作成:** GSI、合成連結キーを必要とせずに、既存の属性 (TournamentRegionIndex `matchId`の場合は `tournamentId`、`region`、`round`、`bracket`、PlayerMatchHistoryIndex の場合は `player1Id`、`matchDate`、`round`) を使用して項目を自動的にインデックス作成します。
**バックフィルが不要:** マルチ属性キーを持つ新しいグローバルセカンダリインデックスを既存のテーブルに追加すると、DynamoDB は自然属性を使用して既存のすべての項目を自動的にインデックス化します。合成キーを使用して項目を更新する必要はありません。
### ステップ 3: すべてのパーティションキー属性を使用して TournamentRegionIndex グローバルセカンダリインデックスをクエリする
この例では、マルチ属性パーティションキー (`tournamentId` \$1 `region`) を持つ TournamentRegionIndex グローバルセカンダリインデックスをクエリします。すべてのパーティションキー属性は、クエリで等号条件で指定する必要があります。`tournamentId` 単独でクエリを実行したり、パーティションキー属性で不等価演算子を使用したりすることはできません。
#### コード例
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Query GSI: All matches for WINTER2024 tournament in NA-EAST region
const response = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region',
ExpressionAttributeNames: {
'#region': 'region', // 'region' is a reserved keyword
'#tournament': 'tournament'
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST'
}
}));
console.log(`Found ${response.Items.length} matches for WINTER2024/NA-EAST:\n`);
response.Items.forEach(match => {
console.log(` ${match.round} | ${match.bracket} | ${match.matchId}`);
console.log(` Players: ${match.player1Id} vs ${match.player2Id}`);
console.log(` Winner: ${match.winner}, Score: ${match.score}\n`);
});
```
**正常な出力:**
```
Found 4 matches for WINTER2024/NA-EAST:
FINALS | CHAMPIONSHIP | match-001
Players: 101 vs 103
Winner: 101, Score: 3-1
QUARTERFINALS | UPPER | match-004
Players: 101 vs 109
Winner: 101, Score: 3-1
SEMIFINALS | UPPER | match-002
Players: 101 vs 105
Winner: 101, Score: 3-2
SEMIFINALS | UPPER | match-003
Players: 103 vs 107
Winner: 103, Score: 3-0
```
**無効なクエリ:**
```
// Missing region attribute
KeyConditionExpression: 'tournamentId = :tournament'
// Using inequality on partition key attribute
KeyConditionExpression: 'tournamentId = :tournament AND #region > :region'
```
**パフォーマンス:** マルチ属性パーティションキーは共にハッシュされ、単一属性キーと同じ O(1) 検索パフォーマンスを提供します。
### ステップ 4: グローバルセカンダリインデックスのソートキー left-to-right をクエリする
ソートキー属性は、グローバルセカンダリインデックスで定義されている順序で左から右にクエリする必要があります。この例では、TournamentRegionIndex をさまざまな階層レベルでクエリする方法を示します。フィルタリングは、`round` のみ、`round` \$1 `bracket`、または 3 つのソートキー属性すべてで行います。途中で属性をスキップすることはできません。例えば、`bracket` のスキップ中に `round` や `matchId` でクエリを実行することはできません。
#### コード例
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Query 1: Filter by first sort key attribute (round)
console.log("Query 1: All SEMIFINALS matches");
const query1 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'SEMIFINALS'
}
}));
console.log(` Found ${query1.Items.length} matches\n`);
// Query 2: Filter by first two sort key attributes (round + bracket)
console.log("Query 2: SEMIFINALS UPPER bracket matches");
const query2 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round AND bracket = :bracket',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'SEMIFINALS',
':bracket': 'UPPER'
}
}));
console.log(` Found ${query2.Items.length} matches\n`);
// Query 3: Filter by all three sort key attributes (round + bracket + matchId)
console.log("Query 3: Specific match in SEMIFINALS UPPER bracket");
const query3 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round AND bracket = :bracket AND matchId = :matchId',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'SEMIFINALS',
':bracket': 'UPPER',
':matchId': 'match-002'
}
}));
console.log(` Found ${query3.Items.length} matches\n`);
// Query 4: INVALID - skipping round
console.log("Query 4: Attempting to skip first sort key attribute (WILL FAIL)");
try {
const query4 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND bracket = :bracket',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':bracket': 'UPPER'
}
}));
} catch (error) {
console.log(` Error: ${error.message}`);
console.log(` Cannot skip sort key attributes - must query left-to-right\n`);
}
```
**正常な出力:**
```
Query 1: All SEMIFINALS matches
Found 2 matches
Query 2: SEMIFINALS UPPER bracket matches
Found 2 matches
Query 3: Specific match in SEMIFINALS UPPER bracket
Found 1 matches
Query 4: Attempting to skip first sort key attribute (WILL FAIL)
Error: Query key condition not supported
Cannot skip sort key attributes - must query left-to-right
```
**Left-to-right クエリルール:** なにもスキップせずに左から右の順にクエリする必要があります。
**有効なパターン:**
+ 最初の属性のみ: `round = 'SEMIFINALS'`
+ 最初の 2 つの属性: `round = 'SEMIFINALS' AND bracket = 'UPPER'`
+ 3 つの属性すべて: `round = 'SEMIFINALS' AND bracket = 'UPPER' AND matchId = 'match-002'`
**無効なパターン:**
+ 最初の属性をスキップする: `bracket = 'UPPER'` (ラウンドをスキップ)
+ 順不同のクエリ: `matchId = 'match-002' AND round = 'SEMIFINALS'`
+ ギャップを残す: `round = 'SEMIFINALS' AND matchId = 'match-002'` (ブラケットをスキップ)
**注記**
**設計のヒント:** クエリの柔軟性を最大化するために、ソートキー属性を最も一般的なものから最も具体的な順に並べます。
### ステップ 5: グローバルセカンダリインデックスのソートキーで不等価条件を使用する
不等価条件は、クエリの最後の条件である必要があります。この例では、ソートキー属性で比較演算子 (`>=`、`BETWEEN`) とプレフィックスマッチング (`begins_with()`) を使用する方法を示します。不等価演算子を使用すると、その後にソートキー条件を追加することはできません。不等価はキー条件式の最終条件である必要があります。
#### コード例
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Query 1: Round comparison (inequality on first sort key attribute)
console.log("Query 1: Matches from QUARTERFINALS onwards");
const query1 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round >= :round',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'QUARTERFINALS'
}
}));
console.log(` Found ${query1.Items.length} matches\n`);
// Query 2: Round range with BETWEEN
console.log("Query 2: Matches between QUARTERFINALS and SEMIFINALS");
const query2 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round BETWEEN :start AND :end',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':start': 'QUARTERFINALS',
':end': 'SEMIFINALS'
}
}));
console.log(` Found ${query2.Items.length} matches\n`);
// Query 3: Prefix matching with begins_with (treated as inequality)
console.log("Query 3: Matches in brackets starting with 'U'");
const query3 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round AND begins_with(bracket, :prefix)',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'SEMIFINALS',
':prefix': 'U'
}
}));
console.log(` Found ${query3.Items.length} matches\n`);
// Query 4: INVALID - condition after inequality
console.log("Query 4: Attempting condition after inequality (WILL FAIL)");
try {
const query4 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round > :round AND bracket = :bracket',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'QUARTERFINALS',
':bracket': 'UPPER'
}
}));
} catch (error) {
console.log(` Error: ${error.message}`);
console.log(` Cannot add conditions after inequality - it must be last\n`);
}
```
**不等価演算子ルール:** 比較演算子 (`>`、`>=`、`<`、`<=`) を使用できます。`BETWEEN` は範囲クエリに、`begins_with()` はプレフィックスマッチングに使用できます。不等価は、クエリの最後の条件である必要があります。
**有効なパターン:**
+ 等価条件の後に不等価が続きます: `round = 'SEMIFINALS' AND bracket = 'UPPER' AND matchId > 'match-001'`
+ 最初の属性の不等価: `round BETWEEN 'QUARTERFINALS' AND 'SEMIFINALS'`
+ 最終条件としてのプレフィックスマッチング: `round = 'SEMIFINALS' AND begins_with(bracket, 'U')`
**無効なパターン:**
+ 不等価の後に条件を追加する: `round > 'QUARTERFINALS' AND bracket = 'UPPER'`
+ 複数の不等価の使用: `round > 'QUARTERFINALS' AND bracket > 'L'`
**重要**
`begins_with()` は不等価条件として扱われるため、追加のソートキー条件をフォローすることはできません。
### ステップ 6: マルチ属性ソートキーを使用して PlayerMatchHistoryIndex グローバルセカンダリインデックスをクエリする
この例では、単一のパーティションキー (`player1Id`) とマルチ属性ソートキー (`matchDate` \$1 `round`) を持つ PlayerMatchHistoryIndex をクエリします。これにより、トーナメント ID を知らずに特定の選手のすべてのマッチングをクエリすることで、クロストーナメント分析が可能になります。ベーステーブルでは、トーナメントとリージョンの組み合わせごとに個別のクエリが必要になります。
#### コード例
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Query 1: All matches for Player 101 across all tournaments
console.log("Query 1: All matches for Player 101");
const query1 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player',
ExpressionAttributeValues: {
':player': '101'
}
}));
console.log(` Found ${query1.Items.length} matches for Player 101:`);
query1.Items.forEach(match => {
console.log(` ${match.tournamentId}/${match.region} - ${match.matchDate} - ${match.round}`);
});
console.log();
// Query 2: Player 101 matches on specific date
console.log("Query 2: Player 101 matches on 2024-01-18");
const query2 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player AND matchDate = :date',
ExpressionAttributeValues: {
':player': '101',
':date': '2024-01-18'
}
}));
console.log(` Found ${query2.Items.length} matches\n`);
// Query 3: Player 101 SEMIFINALS matches on specific date
console.log("Query 3: Player 101 SEMIFINALS matches on 2024-01-18");
const query3 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player AND matchDate = :date AND round = :round',
ExpressionAttributeValues: {
':player': '101',
':date': '2024-01-18',
':round': 'SEMIFINALS'
}
}));
console.log(` Found ${query3.Items.length} matches\n`);
// Query 4: Player 101 matches in date range
console.log("Query 4: Player 101 matches in January 2024");
const query4 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player AND matchDate BETWEEN :start AND :end',
ExpressionAttributeValues: {
':player': '101',
':start': '2024-01-01',
':end': '2024-01-31'
}
}));
console.log(` Found ${query4.Items.length} matches\n`);
```
## パターンのバリエーション
### マルチ属性キーを使用した時系列データ
階層時間属性を使用して時系列クエリを最適化する
#### コード例
```
{
TableName: 'IoTReadings',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'readingId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'readingId', AttributeType: 'S' },
{ AttributeName: 'deviceId', AttributeType: 'S' },
{ AttributeName: 'locationId', AttributeType: 'S' },
{ AttributeName: 'year', AttributeType: 'S' },
{ AttributeName: 'month', AttributeType: 'S' },
{ AttributeName: 'day', AttributeType: 'S' },
{ AttributeName: 'timestamp', AttributeType: 'S' }
],
// GSI with multi-attribute keys for time-series queries
GlobalSecondaryIndexes: [{
IndexName: 'DeviceLocationTimeIndex',
KeySchema: [
{ AttributeName: 'deviceId', KeyType: 'HASH' },
{ AttributeName: 'locationId', KeyType: 'HASH' },
{ AttributeName: 'year', KeyType: 'RANGE' },
{ AttributeName: 'month', KeyType: 'RANGE' },
{ AttributeName: 'day', KeyType: 'RANGE' },
{ AttributeName: 'timestamp', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}],
BillingMode: 'PAY_PER_REQUEST'
}
// Query patterns enabled via GSI:
// - All readings for device in location
// - Readings for specific year
// - Readings for specific month in year
// - Readings for specific day
// - Readings in time range
```
**メリット:** 自然時間階層 (年 → 月 → 日 → タイムスタンプ) を使用すると、日付の解析や操作を行わずに、いつでも効率的にきめ細やかなクエリを実行できます。グローバルセカンダリインデックスは、自然時間属性を使用してすべての読み取り値を自動的にインデックス化します。
### マルチ属性キーを使用した e コマース注文
複数のディメンションを持つ注文を追跡する
#### コード例
```
{
TableName: 'Orders',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'orderId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'orderId', AttributeType: 'S' },
{ AttributeName: 'sellerId', AttributeType: 'S' },
{ AttributeName: 'region', AttributeType: 'S' },
{ AttributeName: 'orderDate', AttributeType: 'S' },
{ AttributeName: 'category', AttributeType: 'S' },
{ AttributeName: 'customerId', AttributeType: 'S' },
{ AttributeName: 'orderStatus', AttributeType: 'S' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'SellerRegionIndex',
KeySchema: [
{ AttributeName: 'sellerId', KeyType: 'HASH' },
{ AttributeName: 'region', KeyType: 'HASH' },
{ AttributeName: 'orderDate', KeyType: 'RANGE' },
{ AttributeName: 'category', KeyType: 'RANGE' },
{ AttributeName: 'orderId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'CustomerOrdersIndex',
KeySchema: [
{ AttributeName: 'customerId', KeyType: 'HASH' },
{ AttributeName: 'orderDate', KeyType: 'RANGE' },
{ AttributeName: 'orderStatus', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}
// SellerRegionIndex GSI queries:
// - Orders by seller and region
// - Orders by seller, region, and date
// - Orders by seller, region, date, and category
// CustomerOrdersIndex GSI queries:
// - Customer's orders
// - Customer's orders by date
// - Customer's orders by date and status
```
### 階層組織データ
モデル組織階層
#### コード例
```
{
TableName: 'Employees',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'employeeId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'employeeId', AttributeType: 'S' },
{ AttributeName: 'companyId', AttributeType: 'S' },
{ AttributeName: 'divisionId', AttributeType: 'S' },
{ AttributeName: 'departmentId', AttributeType: 'S' },
{ AttributeName: 'teamId', AttributeType: 'S' },
{ AttributeName: 'skillCategory', AttributeType: 'S' },
{ AttributeName: 'skillLevel', AttributeType: 'S' },
{ AttributeName: 'yearsExperience', AttributeType: 'N' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'OrganizationIndex',
KeySchema: [
{ AttributeName: 'companyId', KeyType: 'HASH' },
{ AttributeName: 'divisionId', KeyType: 'HASH' },
{ AttributeName: 'departmentId', KeyType: 'RANGE' },
{ AttributeName: 'teamId', KeyType: 'RANGE' },
{ AttributeName: 'employeeId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'SkillsIndex',
KeySchema: [
{ AttributeName: 'skillCategory', KeyType: 'HASH' },
{ AttributeName: 'skillLevel', KeyType: 'RANGE' },
{ AttributeName: 'yearsExperience', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'INCLUDE', NonKeyAttributes: ['employeeId', 'name'] }
}
],
BillingMode: 'PAY_PER_REQUEST'
}
// OrganizationIndex GSI query patterns:
// - All employees in company/division
// - Employees in specific department
// - Employees in specific team
// SkillsIndex GSI query patterns:
// - Employees by skill and experience level
```
### スパースマルチ属性キー
マルチ属性キーを組み合わせてスパース GSI を作成する
#### コード例
```
{
TableName: 'Products',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'productId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'productId', AttributeType: 'S' },
{ AttributeName: 'categoryId', AttributeType: 'S' },
{ AttributeName: 'subcategoryId', AttributeType: 'S' },
{ AttributeName: 'averageRating', AttributeType: 'N' },
{ AttributeName: 'reviewCount', AttributeType: 'N' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'CategoryIndex',
KeySchema: [
{ AttributeName: 'categoryId', KeyType: 'HASH' },
{ AttributeName: 'subcategoryId', KeyType: 'HASH' },
{ AttributeName: 'productId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'ReviewedProductsIndex',
KeySchema: [
{ AttributeName: 'categoryId', KeyType: 'HASH' },
{ AttributeName: 'averageRating', KeyType: 'RANGE' }, // Optional attribute
{ AttributeName: 'reviewCount', KeyType: 'RANGE' } // Optional attribute
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}
// Only products with reviews appear in ReviewedProductsIndex GSI
// Automatic filtering without application logic
// Multi-attribute sort key enables rating and count queries
```
### SaaS とマルチテナンシー
顧客分離を備えたマルチテナント SaaS プラットフォーム
#### コード例
```
// Table design
{
TableName: 'SaasData',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'resourceId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'resourceId', AttributeType: 'S' },
{ AttributeName: 'tenantId', AttributeType: 'S' },
{ AttributeName: 'customerId', AttributeType: 'S' },
{ AttributeName: 'resourceType', AttributeType: 'S' }
],
// GSI with multi-attribute keys for tenant-customer isolation
GlobalSecondaryIndexes: [{
IndexName: 'TenantCustomerIndex',
KeySchema: [
{ AttributeName: 'tenantId', KeyType: 'HASH' },
{ AttributeName: 'customerId', KeyType: 'HASH' },
{ AttributeName: 'resourceType', KeyType: 'RANGE' },
{ AttributeName: 'resourceId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}],
BillingMode: 'PAY_PER_REQUEST'
}
// Query GSI: All resources for tenant T001, customer C001
const resources = await docClient.send(new QueryCommand({
TableName: 'SaasData',
IndexName: 'TenantCustomerIndex',
KeyConditionExpression: 'tenantId = :tenant AND customerId = :customer',
ExpressionAttributeValues: {
':tenant': 'T001',
':customer': 'C001'
}
}));
// Query GSI: Specific resource type for tenant/customer
const documents = await docClient.send(new QueryCommand({
TableName: 'SaasData',
IndexName: 'TenantCustomerIndex',
KeyConditionExpression: 'tenantId = :tenant AND customerId = :customer AND resourceType = :type',
ExpressionAttributeValues: {
':tenant': 'T001',
':customer': 'C001',
':type': 'document'
}
}));
```
**メリット:** テナントと顧客のコンテキストと自然データ組織内の効率的なクエリ。
### 金融取引
GSI を使用した銀行システム追跡アカウントトランザクション
#### コード例
```
// Table design
{
TableName: 'BankTransactions',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'transactionId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'transactionId', AttributeType: 'S' },
{ AttributeName: 'accountId', AttributeType: 'S' },
{ AttributeName: 'year', AttributeType: 'S' },
{ AttributeName: 'month', AttributeType: 'S' },
{ AttributeName: 'day', AttributeType: 'S' },
{ AttributeName: 'transactionType', AttributeType: 'S' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'AccountTimeIndex',
KeySchema: [
{ AttributeName: 'accountId', KeyType: 'HASH' },
{ AttributeName: 'year', KeyType: 'RANGE' },
{ AttributeName: 'month', KeyType: 'RANGE' },
{ AttributeName: 'day', KeyType: 'RANGE' },
{ AttributeName: 'transactionId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'TransactionTypeIndex',
KeySchema: [
{ AttributeName: 'accountId', KeyType: 'HASH' },
{ AttributeName: 'transactionType', KeyType: 'RANGE' },
{ AttributeName: 'year', KeyType: 'RANGE' },
{ AttributeName: 'month', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}
// Query AccountTimeIndex GSI: All transactions for account in 2023
const yearTransactions = await docClient.send(new QueryCommand({
TableName: 'BankTransactions',
IndexName: 'AccountTimeIndex',
KeyConditionExpression: 'accountId = :account AND #year = :year',
ExpressionAttributeNames: { '#year': 'year' },
ExpressionAttributeValues: {
':account': 'ACC-12345',
':year': '2023'
}
}));
// Query AccountTimeIndex GSI: Transactions in specific month
const monthTransactions = await docClient.send(new QueryCommand({
TableName: 'BankTransactions',
IndexName: 'AccountTimeIndex',
KeyConditionExpression: 'accountId = :account AND #year = :year AND #month = :month',
ExpressionAttributeNames: { '#year': 'year', '#month': 'month' },
ExpressionAttributeValues: {
':account': 'ACC-12345',
':year': '2023',
':month': '11'
}
}));
// Query TransactionTypeIndex GSI: Deposits in 2023
const deposits = await docClient.send(new QueryCommand({
TableName: 'BankTransactions',
IndexName: 'TransactionTypeIndex',
KeyConditionExpression: 'accountId = :account AND transactionType = :type AND #year = :year',
ExpressionAttributeNames: { '#year': 'year' },
ExpressionAttributeValues: {
':account': 'ACC-12345',
':type': 'deposit',
':year': '2023'
}
}));
```
## 完全な例
次の例は、セットアップからクリーンアップまでのマルチ属性キーを示しています。
### コード例
```
import {
DynamoDBClient,
CreateTableCommand,
DeleteTableCommand,
waitUntilTableExists
} from "@aws-sdk/client-dynamodb";
import {
DynamoDBDocumentClient,
PutCommand,
QueryCommand
} from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
async function multiAttributeKeysDemo() {
console.log("Starting Multi-Attribute GSI Keys Demo\n");
// Step 1: Create table with GSIs using multi-attribute keys
console.log("1. Creating table with multi-attribute GSI keys...");
await client.send(new CreateTableCommand({
TableName: 'TournamentMatches',
KeySchema: [
{ AttributeName: 'matchId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'matchId', AttributeType: 'S' },
{ AttributeName: 'tournamentId', AttributeType: 'S' },
{ AttributeName: 'region', AttributeType: 'S' },
{ AttributeName: 'round', AttributeType: 'S' },
{ AttributeName: 'bracket', AttributeType: 'S' },
{ AttributeName: 'player1Id', AttributeType: 'S' },
{ AttributeName: 'matchDate', AttributeType: 'S' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'TournamentRegionIndex',
KeySchema: [
{ AttributeName: 'tournamentId', KeyType: 'HASH' },
{ AttributeName: 'region', KeyType: 'HASH' },
{ AttributeName: 'round', KeyType: 'RANGE' },
{ AttributeName: 'bracket', KeyType: 'RANGE' },
{ AttributeName: 'matchId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'PlayerMatchHistoryIndex',
KeySchema: [
{ AttributeName: 'player1Id', KeyType: 'HASH' },
{ AttributeName: 'matchDate', KeyType: 'RANGE' },
{ AttributeName: 'round', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}));
await waitUntilTableExists({ client, maxWaitTime: 120 }, { TableName: 'TournamentMatches' });
console.log("Table created\n");
// Step 2: Insert tournament matches
console.log("2. Inserting tournament matches...");
const matches = [
{ matchId: 'match-001', tournamentId: 'WINTER2024', region: 'NA-EAST', round: 'FINALS', bracket: 'CHAMPIONSHIP', player1Id: '101', player2Id: '103', matchDate: '2024-01-20', winner: '101', score: '3-1' },
{ matchId: 'match-002', tournamentId: 'WINTER2024', region: 'NA-EAST', round: 'SEMIFINALS', bracket: 'UPPER', player1Id: '101', player2Id: '105', matchDate: '2024-01-18', winner: '101', score: '3-2' },
{ matchId: 'match-003', tournamentId: 'WINTER2024', region: 'NA-WEST', round: 'FINALS', bracket: 'CHAMPIONSHIP', player1Id: '102', player2Id: '104', matchDate: '2024-01-20', winner: '102', score: '3-2' },
{ matchId: 'match-004', tournamentId: 'SPRING2024', region: 'NA-EAST', round: 'QUARTERFINALS', bracket: 'UPPER', player1Id: '101', player2Id: '108', matchDate: '2024-03-15', winner: '101', score: '3-0' }
];
for (const match of matches) {
await docClient.send(new PutCommand({ TableName: 'TournamentMatches', Item: match }));
}
console.log(`Inserted ${matches.length} tournament matches\n`);
// Step 3: Query GSI with multi-attribute partition key
console.log("3. Query TournamentRegionIndex GSI: WINTER2024/NA-EAST matches");
const gsiQuery1 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region',
ExpressionAttributeNames: { '#region': 'region' },
ExpressionAttributeValues: { ':tournament': 'WINTER2024', ':region': 'NA-EAST' }
}));
console.log(` Found ${gsiQuery1.Items.length} matches:`);
gsiQuery1.Items.forEach(match => {
console.log(` ${match.round} - ${match.bracket} - ${match.winner} won`);
});
// Step 4: Query GSI with multi-attribute sort key
console.log("\n4. Query PlayerMatchHistoryIndex GSI: All matches for Player 101");
const gsiQuery2 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player',
ExpressionAttributeValues: { ':player': '101' }
}));
console.log(` Found ${gsiQuery2.Items.length} matches for Player 101:`);
gsiQuery2.Items.forEach(match => {
console.log(` ${match.tournamentId}/${match.region} - ${match.matchDate} - ${match.round}`);
});
console.log("\nDemo complete");
console.log("No synthetic keys needed - GSIs use native attributes automatically");
}
async function cleanup() {
console.log("Deleting table...");
await client.send(new DeleteTableCommand({ TableName: 'TournamentMatches' }));
console.log("Table deleted");
}
// Run demo
multiAttributeKeysDemo().catch(console.error);
// Uncomment to cleanup:
// cleanup().catch(console.error);
```
**最小コードの雛形**
### コード例
```
// 1. Create table with GSI using multi-attribute keys
await client.send(new CreateTableCommand({
TableName: 'MyTable',
KeySchema: [
{ AttributeName: 'id', KeyType: 'HASH' } // Simple base table PK
],
AttributeDefinitions: [
{ AttributeName: 'id', AttributeType: 'S' },
{ AttributeName: 'attr1', AttributeType: 'S' },
{ AttributeName: 'attr2', AttributeType: 'S' },
{ AttributeName: 'attr3', AttributeType: 'S' },
{ AttributeName: 'attr4', AttributeType: 'S' }
],
GlobalSecondaryIndexes: [{
IndexName: 'MyGSI',
KeySchema: [
{ AttributeName: 'attr1', KeyType: 'HASH' }, // GSI PK attribute 1
{ AttributeName: 'attr2', KeyType: 'HASH' }, // GSI PK attribute 2
{ AttributeName: 'attr3', KeyType: 'RANGE' }, // GSI SK attribute 1
{ AttributeName: 'attr4', KeyType: 'RANGE' } // GSI SK attribute 2
],
Projection: { ProjectionType: 'ALL' }
}],
BillingMode: 'PAY_PER_REQUEST'
}));
// 2. Insert items with native attributes (no concatenation needed for GSI)
await docClient.send(new PutCommand({
TableName: 'MyTable',
Item: {
id: 'item-001',
attr1: 'value1',
attr2: 'value2',
attr3: 'value3',
attr4: 'value4',
// ... other attributes
}
}));
// 3. Query GSI with all partition key attributes
await docClient.send(new QueryCommand({
TableName: 'MyTable',
IndexName: 'MyGSI',
KeyConditionExpression: 'attr1 = :v1 AND attr2 = :v2',
ExpressionAttributeValues: {
':v1': 'value1',
':v2': 'value2'
}
}));
// 4. Query GSI with sort key attributes (left-to-right)
await docClient.send(new QueryCommand({
TableName: 'MyTable',
IndexName: 'MyGSI',
KeyConditionExpression: 'attr1 = :v1 AND attr2 = :v2 AND attr3 = :v3',
ExpressionAttributeValues: {
':v1': 'value1',
':v2': 'value2',
':v3': 'value3'
}
}));
// Note: If any attribute name is a DynamoDB reserved keyword, use ExpressionAttributeNames:
// KeyConditionExpression: 'attr1 = :v1 AND #attr2 = :v2'
// ExpressionAttributeNames: { '#attr2': 'attr2' }
```
## その他のリソース
+ [DynamoDB のベストプラクティス](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/best-practices.html)
+ [テーブルとデータの操作](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithTables.html)
+ [グローバルセカンダリインデックス](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html):
+ [クエリおよびスキャンオペレーション](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html)
# DynamoDB のグローバルセカンダリインデックスの管理
このセクションでは、Amazon DynamoDB でグローバルセカンダリインデックスを作成、変更、削除する方法について説明します。
**Topics**
+ [グローバルセカンダリインデックスを持つテーブルの作成](#GSI.Creating)
+ [テーブルのグローバルセカンダリインデックスの説明](#GSI.Describing)
+ [グローバルセカンダリインデックスの既存テーブルへの追加](#GSI.OnlineOps.Creating)
+ [グローバルセカンダリインデックスの削除](#GSI.OnlineOps.Deleting)
+ [作成時のグローバルセカンダリインデックスの変更](#GSI.OnlineOps.Creating.Modify)
## グローバルセカンダリインデックスを持つテーブルの作成
1 つ以上のグローバルセカンダリインデックスを持つテーブルを作成するには、`CreateTable` オペレーションと `GlobalSecondaryIndexes` パラメータを使用します。最大限のクエリの柔軟性を得るために、テーブルごとに最大 20 個のグローバルセカンダリインデックス (デフォルトのクォータ) を作成できます。
インデックスパーティションキーとして機能する属性を 1 つ指定する必要があります。必要に応じて、インデックスソートキーに別の属性を指定できます。これらのキー属性のいずれも、テーブルのキー属性と同じである必要はありません。例えば、*GameScores* テーブル (「[DynamoDB のグローバルセカンダリインデックスの使用](GSI.md)」参照) では、`TopScore` も `TopScoreDateTime` もキー属性ではありません。パーティションキーとして `TopScore`、ソートキーとして `TopScoreDateTime` を使用して、グローバルセカンダリインデックスを作成できます。このようなインデックスを使用して、ハイスコアとゲームのプレイ時刻との間に相関があるかどうかを判定できる可能性があります。
各インデックスキー属性は、`String`、`Number`、または `Binary` タイプのスカラーである必要があります。(ドキュメントまたはセットは指定できません)。グローバルセカンダリインデックスには、任意のデータ型の属性を射影できます。これには、スカラー、ドキュメント、およびセットが含まれます。データ型の詳細なリストについては、「[データ型](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes)」を参照してください。
プロビジョニング済みモードを使用する場合は、インデックスに `ReadCapacityUnits` および `WriteCapacityUnits` で構成される `ProvisionedThroughput` 設定をする必要があります。これらのプロビジョニングされたスループット設定は、テーブルの設定とは別ですが、同様の動作をします。詳細については、「」を参照してください[グローバルセカンダリインデックスに対するプロビジョニングされたスループットに関する考慮事項](GSI.md#GSI.ThroughputConsiderations)
グローバルセカンダリーインデックスは、基本テーブルから読み込み/書き込みキャパシティーモードを継承します。詳細については、「[DynamoDB でキャパシティモードを切り替える際の考慮事項](bp-switching-capacity-modes.md)」を参照してください。
**注記**
新しい GSI を作成する際、選択したパーティションキーが、新しいインデックスのパーティションキー値全体でデータやトラフィックの分散が不均一だったり、狭くなっているかを確認することが重要になります。この場合、バックフィル操作と書き込み操作が同時に発生し、ベーステーブルへの書き込みをスロットリングしている可能性があります。このサービスでは、このシナリオの可能性を最小限に抑えるための対策を講じていますが、インデックスパーティションキー、選択した射影、またはインデックスプライマリキーのスパース性について、カスタマーデータのインサイトを見える形で取得していません。
新しいグローバルセカンダリインデックスで、パーティションキー値全体でデータやトラフィックの分散が狭められたり、歪められたりしている可能性がある場合は、運用上重要なテーブルに新しいインデックスを追加する前に、次の点を考慮してください。
アプリケーションのトラフィック量が最も少ない時間帯にインデックスを追加するのが、最も安全な方法と言えます。
ベーステーブルとインデックスで CloudWatch Contributor Insights 有効にすることを検討してください。これにより、トラフィックの分散に関する貴重なインサイトが得られます。
プロセス全体を通して、CloudWatch メトリクス `WriteThrottleEvents`、`ThrottledRequests`、および `OnlineIndexPercentageProgress` を表示します。必要に応じて、プロビジョニングされた書き込みキャパシティを調整し、進行中の操作に対してスロットリングによる大きな影響を与えることなく、適切な時間内にバックフィルを完了します。`OnlineIndexConsumedWriteCapacity` と `OnlineThrottleEvents` は、インデックスバックフィル中は 0 と表示されると予想されます。
書き込みスロットリングによる運用上の影響が発生した場合は、インデックスの作成をキャンセルする準備をしてください。
## テーブルのグローバルセカンダリインデックスの説明
テーブルのすべてのグローバルセカンダリインデックスのステータスを表示するには、`DescribeTable` オペレーションを使用します。レスポンスの `GlobalSecondaryIndexes` 部分は、テーブル上のすべてのインデックスと、それぞれの現在のステータス (`IndexStatus`) を示しています。
グローバルセカンダリインデックスの `IndexStatus` は、次のいずれかになります。
+ `CREATING` – インデックスは現在作成されていますが、まだ使用することはできません。
+ `ACTIVE` – インデックスは使用可能になり、アプリケーションはインデックスに対して `Query` オペレーションを実行できます。
+ `UPDATING` – インデックスのプロビジョニングされたスループット設定の変更中です。
+ `DELETING` – インデックスは現在削除されているため、使用できなくなっています。
DynamoDB がグローバルセカンダリインデックスの作成を完了すると、インデックスのステータスが `CREATING` から `ACTIVE` に変わります。
## グローバルセカンダリインデックスの既存テーブルへの追加
既存のテーブルにグローバルセカンダリインデックスを追加するには、`UpdateTable` オペレーションと `GlobalSecondaryIndexUpdates` パラメータを使用します。以下の情報が必要です。
+ インデックス名。名前は、テーブル内のすべてのインデックスにおいて一意である必要があります。
+ インデックスのキースキーマ。インデックスパーティションキーには 1 つの属性を指定する必要があります。必要に応じて、インデックスソートキーに別の属性を指定できます。これらのキー属性のいずれも、テーブルのキー属性と同じである必要はありません。各スキーマ属性のデータ型は、`String`、`Number`、または `Binary` のスカラーである必要があります。
+ テーブルからインデックスに射影される属性は以下の通りです。
+ `KEYS_ONLY` – インデックス内の各項目は、テーブルパーティションキーとソートキーの値、およびインデックスキーの値のみで構成されます。
+ `INCLUDE` – `KEYS_ONLY` の属性に加えて、セカンダリインデックスにその他の非キー属性が含まれるように指定できます。
+ `ALL` – インデックスには、ソーステーブルのすべての属性が含まれます。
+ インデックスのプロビジョニングされたスループット設定で、`ReadCapacityUnits` および `WriteCapacityUnits` で構成されます。これは、テーブルのプロビジョニングされたスループット設定とは異なります。
`UpdateTable` オペレーションについて作成できるグローバルセカンダリインデックスは 1 つだけです。
### インデックス作成のフェーズ
新しいグローバルセカンダリインデックスを既存のテーブルに追加すると、インデックスの構築中もテーブルが使用可能になります。ただし、新しいインデックスは、そのステータスが `CREATING` から `ACTIVE` に変わるまでクエリオペレーションに使用できません。
**注記**
グローバルセカンダリインデックスの作成では、Application Auto Scaling を使用しません。`MIN` Application Auto Scaling の容量を増やしても、グローバルセカンダリインデックスの作成時間は短縮されません。
その裏では、DynamoDB は 2 つのフェーズでインデックスを構築しています。
**リソース割り当て**
DynamoDB は、インデックスの構築に必要なコンピューティングリソースとストレージリソースを割り当てます。
リソース割り当てフェーズでは、`IndexStatus` 属性は `CREATING`、`Backfilling` 属性は false です。`DescribeTable` オペレーションを使用して、テーブルとそのセカンダリインデックスすべてのステータスを取得します。
インデックスがリソース割り当てフェーズにある間は、インデックスやその親テーブルを削除することはできません。インデックスまたはテーブルのプロビジョニングされたスループットを変更することもできません。テーブル上の他のインデックスを追加したり削除したりすることはできません。ただし、これらの他のインデックスのプロビジョニングされたスループットは変更できます。
**バックフィル**
テーブルの各項目について、DynamoDB は、その射影 (`KEYS_ONLY`、`INCLUDE`、または `ALL`) に基づいて、インデックスに書き込む属性のセットを決定します。次に、これらの属性をインデックスに書き込みます。バックフィルフェーズでは、DynamoDB はテーブルで追加、削除、または更新される項目を追跡します。これらの項目の属性も、必要に応じてインデックスで追加、削除、または更新されます。
バックフィルフェーズでは、`IndexStatus` 属性は `CREATING` に設定されていて、`Backfilling` 属性は true です。`DescribeTable` オペレーションを使用して、テーブルとそのセカンダリインデックスすべてのステータスを取得します。
インデックスがバックフィルされている間は、親テーブルを削除することはできません。ただし、インデックスを削除したり、テーブルとそのグローバルセカンダリインデックスのプロビジョニングされたスループットを変更したりすることはできます。
バックフィルフェーズでは、違反する項目の書き込みの一部が成功し、他の項目が拒否されることがあります。バックフィル後、新しいインデックスのキースキーマに違反する項目への書き込みはすべて拒否されます。バックフィルフェーズの終了後に Violation Detector ツールを実行して、発生した可能性のあるキー違反を検出して解決することをお勧めします。詳細については、「」を参照してください[DynamoDB でのインデックスキー違反の検出と修正](GSI.OnlineOps.ViolationDetection.md)
リソース割り当てフェーズとバックフィルフェーズの進行中、インデックスは `CREATING` 状態になっています。この間、DynamoDB はテーブルに対して読み込みオペレーションを実行します。グローバルセカンダリインデックスを設定するためのベーステーブルからの読み込みオペレーションに対しては課金されません。
インデックス構築が完了すると、ステータスは `ACTIVE` に変わります。インデックスが `ACTIVE` になるまで、`Query` や `Scan` はできません。
**注記**
場合によっては、DynamoDB は、インデックスキーの違反のため、テーブルからインデックスにデータを書き込めない場合があります。これは、以下の場合に発生します。
属性値のデータ型が、インデックスキーのスキーマデータ型のデータ型と一致しません。
属性のサイズが、インデックスキー属性の最大長を超えています。
インデックスキー属性には、空の文字列または空のバイナリ属性値があります。
インデックスキー違反があっても、グローバルセカンダリインデックスの作成はできます。ただし、インデックスが `ACTIVE` になると、違反しているキーはインデックスに存在しなくなります。
DynamoDB には、これらの問題を検出して解決するためのスタンドアロンツールが用意されています。詳細については、「[DynamoDB でのインデックスキー違反の検出と修正](GSI.OnlineOps.ViolationDetection.md)」を参照してください。
### 大きなテーブルへのグローバルセカンダリインデックスの追加
グローバルセカンダリインデックスの構築に必要な時間は、次のようないくつかの要因によって異なります。
+ テーブルのサイズ
+ インデックスに含めることができるテーブル内の項目の数
+ インデックスに射影される属性の数。
+ インデックス構築中のメインテーブルへの書き込みアクティビティ
非常に大きなテーブルにグローバルセカンダリインデックスを追加する場合、作成プロセスが完了するまで時間がかかることがあります。進行状況をモニタリングし、インデックスに十分な書き込み容量があるかどうかを判断するには、次の Amazon CloudWatch メトリクスを参照してください。
+ `OnlineIndexPercentageProgress`
DynamoDB に関する CloudWatch メトリクスの詳細については、「[DynamoDB のメトリクス](metrics-dimensions.md#dynamodb-metrics)」を参照してください。
**重要**
グローバルセカンダリインデックスを作成または更新する前に、非常に大きなテーブルを許可リストする必要がある場合があります。AWS サポートに連絡して、テーブルの許可リストを作成してください。
インデックスがバックフィルされている間、DynamoDB は内部システム容量を使用してテーブルから読み込みます。これは、インデックスの作成による影響を最小限に抑え、テーブルの読み込みキャパシティーが不足しないようにするためです。
## グローバルセカンダリインデックスの削除
グローバルセカンダリインデックスが不要になった場合には、`UpdateTable` オペレーションを使用して削除することができます。
グローバルセカンダリインデックスは、1 回の `UpdateTable` オペレーションで 1 つだけ削除できます。
グローバルセカンダリインデックスが削除されている間、親テーブルの読み込みまたは書き込みアクティビティに影響はありません。削除の進行中でも、他のインデックスでプロビジョニングされたスループットを変更できます。
**注記**
`DeleteTable` アクションを使用してテーブルを削除すると、そのテーブルのすべてのグローバルセカンダリインデックスも削除されます。
アカウントではグローバルセカンダリインデックスの削除操作に対して課金されません。
## 作成時のグローバルセカンダリインデックスの変更
インデックスが作成されている間は、`DescribeTable` オペレーションを使用して、どのフェーズにあるかを判断します。インデックスの説明に含まれているブール属性 `Backfilling` は、DynamoDB がテーブルから項目を含むインデックスを現在ロードしているかどうかを示します。`Backfilling` が true の場合、リソース割り当てフェーズは完了していて、インデックスがバックフィルされています。
バックフィルフェーズでは、作成中のインデックスを削除できます。このフェーズでは、テーブルの他のインデックスを追加または削除することはできません。
**注記**
`CreateTable` オペレーションの一部として作成されたインデックスの場合、`Backfilling` 属性は `DescribeTable` 出力に現れません。詳細については、「[インデックス作成のフェーズ](#GSI.OnlineOps.Creating.Phases)」を参照してください。
# DynamoDB でのインデックスキー違反の検出と修正
グローバルセカンダリインデックスの作成のバックフィルフェーズでは、Amazon DynamoDB はテーブルの各項目を調べて、インデックスに含める適格性があるかどうかを判断します。一部の項目は、インデックスキー違反の原因となるため、適格でない場合があります。このような場合、項目はテーブルに残りますが、インデックスにはその項目に対応するエントリがなくなります。
インデックスキー違反は次の場合に発生します。
+ 属性値とインデックスキーのスキーマのデータ型が一致しない場合。たとえば、`GameScores` テーブルの項目の 1 つが、`String` 型の `TopScore` 値を持っていたとします。`Number` 型の `TopScore` のパーティションキーを持つグローバルセカンダリインデックスを追加した場合、テーブルの項目はインデックスキーに違反します。
+ テーブルの属性値が、インデックスキー属性の最大長を超えている場合。パーティションキーの最大長は 2048 バイトで、ソートキーの最大長は 1024 バイトです。テーブル内の対応する属性値のいずれかがこれらの制限を超えると、テーブルの項目はインデックスキーに違反します。
**注記**
インデックスキーとして使用される属性に String 属性または Binary 属性値が設定されている場合、属性値の長さは 0 より大きくする必要があります。そうしないと、テーブルの項目がインデックスキーに違反します。
現時点では、このツールはこのインデックスキー違反にフラグを設定しません。
インデックスキー違反が発生した場合でも、バックフィルフェーズは中断することなく続行されます。ただし、違反している項目は、インデックスに含まれません。バックフィルフェーズ完了後は、新しいインデックスのキースキーマに違反する項目へのすべての書き込みが拒否されます。
インデックスキーに違反するテーブル内の属性値を識別して修正するには、Violation Detector ツールを使用します。Violation Detector を実行するには、スキャンするテーブルの名前、グローバルセカンダリインデックスパーティションキーとソートキーの名前とデータ型、インデックスキー違反が見つかった場合に実行するアクションを指定する設定ファイルを作成します。Violation Detector は、次の 2 つのモードのいずれかで実行できます。
+ **検出モード** – インデックスキー違反を検出します。検出モードを使用して、グローバルセカンダリインデックスでキー違反の原因となるテーブル内の項目を報告します。(必要に応じて、違反しているテーブル項目が見つかるとすぐに削除するように要求できます)。検出モードからの出力はファイルに書き込まれるので、これを使用してさらに分析できます。
+ **修正モード** – インデックスキー違反を修正します。修正モードでは、Violation Detector は検出モードからの出力ファイルと同じ形式の入力ファイルを読み込みます。修正モードでは、入力ファイルからレコードを読み込み、各レコードについて、テーブル内の対応する項目を削除または更新します。(項目の更新を選択した場合は、入力ファイルを編集して、これらの更新に適切な値を設定する必要があります)。
## Violation Detector のダウンロードおよび実行
Violation Detector は、実行可能な Java Archive (`.jar` ファイル) で、Windows、macOS、または Linux コンピュータ上で実行されます。Violation Detector には Java 1.7 (以降) と Apache Maven が必要です。
+ [GitHub から Violation Detector をダウンロードします](https://github.com/awslabs/dynamodb-online-index-violation-detector)
`README.md` ファイルの指示に従って、Maven を使用して Violation Detector をダウンロードしてインストールします。
Violation Detector を起動するには、`ViolationDetector.java` を構築したディレクトリで、次のコマンドを入力します。
```
java -jar ViolationDetector.jar [options]
```
Violation Detector ツールのコマンドラインでは、以下のオプションが使用できます。
+ `-h | --help` – Violation Detector の使用方法の概要とオプションを出力します。
+ `-p | --configFilePath` `value` – Violation Detector 設定ファイルの完全修飾名。詳細については、「」を参照してください[Violation Detector 設定ファイル](#GSI.OnlineOps.ViolationDetection.ConfigFile)
+ `-t | --detect` `value` – テーブル内のインデックスキー違反を検出し、Violation Detector の出力ファイルに書き込みます。このパラメータの値が `keep` に設定されている場合、キー違反のある項目は変更されません。値が `delete` に設定されている場合、キー違反のある項目はテーブルから削除されます。
+ `-c | --correct` `value` – 入力ファイルからインデックスキー違反を読み込み、テーブル内の項目に対して修正アクションを実行します。このパラメータの値が `update` に設定されている場合、キー違反のある項目は、違反していない新しい値で更新されます。値が `delete` に設定されている場合、キー違反のある項目はテーブルから削除されます。
## Violation Detector 設定ファイル
実行時に、Violation Detector ツールには設定ファイルが必要です。このファイルのパラメータによって、Violation Detector がアクセスできる DynamoDB リソースと、プロビジョニングされたスループットを使用できる量が決まります。以下の表は、これらのパラメータの説明です。
****
| パラメータ名 | 説明 | 必須? |
| --- | --- | --- |
| `awsCredentialsFile` | AWS 認証情報を含むファイルの完全修飾名。認証情報ファイルの形式は、次のようになります。 accessKey = access_key_id_goes_here
secretKey = secret_key_goes_here
| はい |
| `dynamoDBRegion` | テーブルが存在する AWS リージョン。例: `us-west-2`。 | はい |
| `tableName` | スキャンされる DynamoDB テーブルの名前。 | はい |
| `gsiHashKeyName` | インデックスパーティションキーの名前。 | はい |
| `gsiHashKeyType` | インデックスパーティションキーのデータ型 – `String`、`Number`、または `Binary`: `S \| N \| B` | はい |
| `gsiRangeKeyName` | インデックスソートキーの名前。インデックスにシンプルなプライマリキー (パーティションキー) のみがある場合は、このパラメータを指定しないでください。 | いいえ |
| `gsiRangeKeyType` | インデックスソートキーのデータ型 – `String`、`Number`、または `Binary`: `S \| N \| B` インデックスにシンプルなプライマリキー (パーティションキー) のみがある場合は、このパラメータを指定しないでください。 | いいえ |
| `recordDetails` | インデックスキー違反の詳細を出力ファイルに書き込むかどうか。設定が `true` の場合 (デフォルト)、違反項目に関する完全な情報が報告されます。設定が `false` の場合、違反の数のみが報告されます。 | いいえ |
| `recordGsiValueInViolationRecord` | 違反しているインデックスキーの値を出力ファイルに書き込むかどうか。設定が `true` の場合 (デフォルト)、キー値が報告されます。設定が `false` の場合、キー値は報告されません。 | いいえ |
| `detectionOutputPath` | Violation Detector の出力ファイルのフルパス。このパラメータは、ローカルディレクトリまたはAmazon Simple Storage Service (Amazon S3) への書き込みをサポートしています。次に例を示します。 `detectionOutputPath = ``//local/path/filename.csv` `detectionOutputPath = ``s3://bucket/filename.csv` 出力ファイル内の情報は、CSV (Comma-Separated Values) 形式で表示されます。`detectionOutputPath` を設定しない場合、出力ファイル名は `violation_detection.csv` になり、現在の作業ディレクトリに書き込まれます。 | いいえ |
| `numOfSegments` | Violation Detector がテーブルをスキャンするときに使用される並列スキャンセグメントの数。デフォルト値は 1 です。これは、テーブルがシーケンシャルにスキャンされることを意味します。値が 2 以上の場合、Violation Detector はテーブルをその数の論理セグメントに分割し、同じ数のスキャンスレッドにします。`numOfSegments` の設定は最大 4,096 です。大きなテーブルの場合、並列スキャンはシーケンシャルスキャンよりも一般的に高速です。さらに、テーブルが複数のパーティションにまたがるほど大きい場合、並列スキャンによって読み込みアクティビティが複数のパーティションに均等に分散されます。DynamoDB の並列スキャンの詳細については、「[並列スキャン](Scan.md#Scan.ParallelScan)」を参照してください。 | いいえ |
| `numOfViolations` | 出力ファイルに書き込むインデックスキー違反の上限値。設定が `-1` の場合 (デフォルト)、テーブル全体がスキャンされます。正の整数に設定すると、Violation Detector は設定した数の違反を検出した後に停止します。 | いいえ |
| `numOfRecords` | スキャンされるテーブル内の項目数。設定が -1 の場合(デフォルト)、テーブル全体がスキャンされます。正の整数に設定すると、Violation Detector はテーブル内の設定した数の項目をスキャンした後に停止します。 | いいえ |
| `readWriteIOPSPercent` | テーブルスキャン中に使用される、プロビジョニングされた読み込みキャパシティーユニットの割合を調整します。有効な値の範囲は `1`～`100` です。デフォルト値 (`25`) は、Violation Detector がテーブルのプロビジョニングされた読み込みスループットの 25% 以下を使用することを意味します。 | いいえ |
| `correctionInputPath` | Violation Detector 修正入力ファイルのフルパス。Violation Detector を修正モードで実行すると、このファイルの内容を使用して、グローバルセカンダリインデックスに違反するテーブル内のデータ項目を変更または削除します。 `correctionInputPath` ファイルの形式は、`detectionOutputPath` ファイルの形式と同じです。これにより、検出モードからの出力を修正モードの入力として処理できます。 | いいえ |
| `correctionOutputPath` | Violation Detector 修正出力ファイルのフルパス。このファイルは、更新エラーがある場合にのみ作成されます。 このパラメータは、ローカルディレクトリまたは Amazon S3 への書き込みをサポートします。次に例を示します。 `correctionOutputPath = ``//local/path/filename.csv` `correctionOutputPath = ``s3://bucket/filename.csv` 出力ファイルの情報は CSV 形式で表示されます。`correctionOutputPath` を設定しない場合、出力ファイル名は `violation_update_errors.csv` になり、現在の作業ディレクトリに書き込まれます。 | いいえ |
## 検出
インデックスキー違反を検出するには、Violation Detector を `--detect` コマンドラインオプションで使用します。このオプションがどのように機能するかを示すには、`ProductCatalog` テーブルを検討してください。以下は、テーブルの項目の一覧です。プライマリキー (`Id`) と `Price` 属性のみを表示しています。
****
| ID (プライマリキー) | 価格 |
| --- | --- |
| 101 | 5 |
| 102 | 20 |
| 103 | 200 |
| 201 | 100 |
| 202 | 200 |
| 203 | 300 |
| 204 | 400 |
| 205 | 500 |
`Price` の値はすべて、`Number` 型です。ただし、DynamoDB はスキーマレスであるため、数値以外の `Price` の項目を追加することができます。たとえば、`ProductCatalog` テーブルに別の項目を追加するとします。
****
| ID (プライマリキー) | 価格 |
| --- | --- |
| 999 | "Hello" |
これで、テーブルには合計 9 つの項目が追加されました。
ここで、新しいグローバルセカンダリインデックスをテーブルに追加します: `PriceIndex`。このインデックスのプライマリキーは、パーティションキー `Price` で、`Number` 型です。インデックスが構築されると、8 つの項目が含まれますが、`ProductCatalog` テーブルには 9 つの項目があります。この不一致の理由は、値 `"Hello"` は `String` 型ですが、`PriceIndex` は `Number` 型のプライマリキーを持っているからです。`String` 値がグローバルセカンダリインデックスキーに違反するため、インデックスには存在しません。
この状況で Violation Detector を使用するには、まず次のような設定ファイルを作成します。
```
# Properties file for violation detection tool configuration.
# Parameters that are not specified will use default values.
awsCredentialsFile = /home/alice/credentials.txt
dynamoDBRegion = us-west-2
tableName = ProductCatalog
gsiHashKeyName = Price
gsiHashKeyType = N
recordDetails = true
recordGsiValueInViolationRecord = true
detectionOutputPath = ./gsi_violation_check.csv
correctionInputPath = ./gsi_violation_check.csv
numOfSegments = 1
readWriteIOPSPercent = 40
```
続いて、次の例のように、Violation Detector を実行します。
```
$ java -jar ViolationDetector.jar --configFilePath config.txt --detect keep
Violation detection started: sequential scan, Table name: ProductCatalog, GSI name: PriceIndex
Progress: Items scanned in total: 9, Items scanned by this thread: 9, Violations found by this thread: 1, Violations deleted by this thread: 0
Violation detection finished: Records scanned: 9, Violations found: 1, Violations deleted: 0, see results at: ./gsi_violation_check.csv
```
`recordDetails` 設定パラメータが `true` に設定されている場合、Violation Detector は、次の例のように、各違反の詳細を出力ファイルに書き込みます。
```
Table Hash Key,GSI Hash Key Value,GSI Hash Key Violation Type,GSI Hash Key Violation Description,GSI Hash Key Update Value(FOR USER),Delete Blank Attributes When Updating?(Y/N)
999,"{""S"":""Hello""}",Type Violation,Expected: N Found: S,,
```
出力ファイルは CSV 形式です。ファイルの最初の行はヘッダーで、2 行目以降はインデックスキーに違反する項目ごとに 1 つのレコードが続きます。これらの違反レコードのフィールドは次のとおりです。
+ **テーブルハッシュキー** – テーブル内の項目のパーティションキー値です。
+ **テーブル範囲キー** – テーブル内の項目のソートキー値です。
+ **GSI ハッシュキー値** – グローバルセカンダリインデックスのパーティションキー値です。
+ **GSI ハッシュキー違反タイプ** – `Type Violation` または `Size Violation`。
+ **GSI ハッシュキー違反の説明** – 違反の原因です。
+ **GSI ハッシュキー更新値 (ユーザー用)** – 修正モードでは、ユーザーが指定した属性の新しい値。
+ **GSI 範囲キー値** – グローバルセカンダリインデックスのソートキー値です。
+ **GSI 範囲キー違反タイプ** – `Type Violation` または `Size Violation`。
+ **GSI 範囲キー違反の説明** – 違反の原因です。
+ **GSI 範囲キーの更新値 (ユーザー用)** – 修正モードでは、ユーザーが指定した属性の新しい値。
+ **更新時に空白の属性を削除 (Y/N)** – 修正モードでは、テーブル内の違反項目を削除する (Y) か、保持する (N) かを決定します。ただし、次のフィールドのいずれかが空白の場合のみ実行されます。
+ `GSI Hash Key Update Value(FOR USER)`
+ `GSI Range Key Update Value(FOR USER)`
これらのフィールドのいずれかが空白でない場合、`Delete Blank Attribute When Updating(Y/N)` は何も実行しません。
**注記**
出力形式は、設定ファイルとコマンドラインオプションによって異なることがあります。例えば、テーブルに単純なプライマリキー (ソートキーなし) がある場合、出力にはソートキーフィールドは表示されません。
ファイル内の違反レコードがソート順でない可能性があります。
## 修正
インデックスキーの違反を修正するには、Violation Detector を `--correct` コマンドラインオプションで使用します。修正モードでは、Violation Detector は `correctionInputPath` パラメータで指定された入力ファイルを読み込みます。このファイルの形式は `detectionOutputPath` ファイルの形式と同じなので、検出からの出力を修正のための入力として使用できます。
Violation Detector には、インデックスキー違反を修正する 2 種類の方法があります。
+ **違反の削除** – 属性値に違反しているテーブル項目を削除します。
+ **違反の更新** – テーブル項目を更新し、違反している属性を違反しない値に置き換えます。
いずれの場合も、検出モードからの出力ファイルを修正モードの入力として使用できます。
`ProductCatalog` の例に進みます。違反している項目をテーブルから削除するとします。これを行うには、次のコマンドラインを使用します。
```
$ java -jar ViolationDetector.jar --configFilePath config.txt --correct delete
```
この時点で、違反している項目を削除するかどうかを確認するメッセージが表示されます。
```
Are you sure to delete all violations on the table?y/n
y
Confirmed, will delete violations on the table...
Violation correction from file started: Reading records from file: ./gsi_violation_check.csv, will delete these records from table.
Violation correction from file finished: Violations delete: 1, Violations Update: 0
```
`ProductCatalog` と `PriceIndex` の項目の数が同じになりました。
# グローバルセカンダリインデックスの操作: Java
AWS SDK for Java ドキュメント API を使用して、1 つ以上のグローバルセカンダリインデックスを持つ Amazon DynamoDB テーブルを作成し、テーブルのインデックスを記述し、インデックスを使用してクエリを実行できます。
以下に、テーブルオペレーションの一般的な手順を示します。
1. `DynamoDB` クラスのインスタンスを作成します。
1. 対応するリクエストオブジェクトを作成して、オペレーションについて必要なパラメータとオプションパラメータを入力します。
1. 前のステップで作成したクライアントが提供する適切なメソッドを呼び出します。
**Topics**
+ [グローバルセカンダリインデックスを持つテーブルを作成します](#GSIJavaDocumentAPI.CreateTableWithIndex)
+ [グローバルセカンダリインデックスを持つテーブルの説明](#GSIJavaDocumentAPI.DescribeTableWithIndex)
+ [グローバルセカンダリインデックスのクエリ](#GSIJavaDocumentAPI.QueryAnIndex)
+ [例: AWS SDK for Java ドキュメント API を使用したグローバルセカンダリインデックス](GSIJavaDocumentAPI.Example.md)
## グローバルセカンダリインデックスを持つテーブルを作成します
グローバルセカンダリインデックスは、テーブルの作成と同時に作成できます。これを行うには、`CreateTable` を使用し、1 つ以上のグローバルセカンダリインデックスの仕様を指定します。次の Java コード例では、気象データに関する情報を保持するテーブルを作成しています。パーティションキーは `Location` で、ソートキーは `Date` です。グローバルセカンダリインデックス `PrecipIndex` は、さまざまな場所の降水データへの高速アクセスを可能にします。
DynamoDB ドキュメント API を使用して、グローバルセカンダリインデックスを持つテーブルを作成する手順を次に示します。
1. `DynamoDB` クラスのインスタンスを作成します。
1. リクエスト情報を指定する `CreateTableRequest` クラスのインスタンスを作成します。
テーブル名、プライマリキー、およびプロビジョニングされたスループット値を指定する必要があります。グローバルセカンダリインデックスの場合は、インデックス名、プロビジョニングされたスループット設定、インデックスソートキーの属性定義、インデックスのキースキーマ、および属性射影を指定する必要があります。
1. リクエストオブジェクトをパラメータとして指定して、`createTable` メソッドを呼び出します。
以下の Java コード例は、前述のステップの例です。このコードは、グローバルセカンダリインデックス (`PrecipIndex`) を持つテーブル (`WeatherData`) を作成します。インデックスパーティションキーは `Date` で、ソートキーは `Precipitation` です。すべてのテーブル属性がインデックスに射影されます。ユーザーは、このインデックスに対するクエリを実行して、特定の日付の気象データを取得できます。必要に応じて、降水量によってデータを並べ替えることもできます。
`Precipitation` はテーブルのキー属性ではないため、必須ではありません。ただし、`Precipitation` のない `WeatherData` 項目は `PrecipIndex` に表示されません。
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
// Attribute definitions
ArrayList attributeDefinitions = new ArrayList();
attributeDefinitions.add(new AttributeDefinition()
.withAttributeName("Location")
.withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition()
.withAttributeName("Date")
.withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition()
.withAttributeName("Precipitation")
.withAttributeType("N"));
// Table key schema
ArrayList tableKeySchema = new ArrayList();
tableKeySchema.add(new KeySchemaElement()
.withAttributeName("Location")
.withKeyType(KeyType.HASH)); //Partition key
tableKeySchema.add(new KeySchemaElement()
.withAttributeName("Date")
.withKeyType(KeyType.RANGE)); //Sort key
// PrecipIndex
GlobalSecondaryIndex precipIndex = new GlobalSecondaryIndex()
.withIndexName("PrecipIndex")
.withProvisionedThroughput(new ProvisionedThroughput()
.withReadCapacityUnits((long) 10)
.withWriteCapacityUnits((long) 1))
.withProjection(new Projection().withProjectionType(ProjectionType.ALL));
ArrayList indexKeySchema = new ArrayList();
indexKeySchema.add(new KeySchemaElement()
.withAttributeName("Date")
.withKeyType(KeyType.HASH)); //Partition key
indexKeySchema.add(new KeySchemaElement()
.withAttributeName("Precipitation")
.withKeyType(KeyType.RANGE)); //Sort key
precipIndex.setKeySchema(indexKeySchema);
CreateTableRequest createTableRequest = new CreateTableRequest()
.withTableName("WeatherData")
.withProvisionedThroughput(new ProvisionedThroughput()
.withReadCapacityUnits((long) 5)
.withWriteCapacityUnits((long) 1))
.withAttributeDefinitions(attributeDefinitions)
.withKeySchema(tableKeySchema)
.withGlobalSecondaryIndexes(precipIndex);
Table table = dynamoDB.createTable(createTableRequest);
System.out.println(table.getDescription());
```
DynamoDB がテーブルを作成し、テーブルのステータスを `ACTIVE` に設定するまで待機する必要があります。その後、テーブルへのデータ項目の入力を開始できます。
## グローバルセカンダリインデックスを持つテーブルの説明
テーブルでグローバルセカンダリインデックスに関する情報を取得するには、`DescribeTable` を使用します。インデックスごとに、名前、キースキーマ、および射影された属性にアクセスできます。
テーブルのグローバルセカンダリインデックス情報にアクセスする手順を次に示します。
1. `DynamoDB` クラスのインスタンスを作成します。
1. 操作対象のインデックスを表すために、`Table` クラスのインスタンスを作成します。
1. `Table` オブジェクトの `describe` メソッドを呼び出します。
以下の Java コード例は、前述のステップの例です。
**Example**
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
Table table = dynamoDB.getTable("WeatherData");
TableDescription tableDesc = table.describe();
Iterator gsiIter = tableDesc.getGlobalSecondaryIndexes().iterator();
while (gsiIter.hasNext()) {
GlobalSecondaryIndexDescription gsiDesc = gsiIter.next();
System.out.println("Info for index "
+ gsiDesc.getIndexName() + ":");
Iterator kseIter = gsiDesc.getKeySchema().iterator();
while (kseIter.hasNext()) {
KeySchemaElement kse = kseIter.next();
System.out.printf("\t%s: %s\n", kse.getAttributeName(), kse.getKeyType());
}
Projection projection = gsiDesc.getProjection();
System.out.println("\tThe projection type is: "
+ projection.getProjectionType());
if (projection.getProjectionType().toString().equals("INCLUDE")) {
System.out.println("\t\tThe non-key projected attributes are: "
+ projection.getNonKeyAttributes());
}
}
```
## グローバルセカンダリインデックスのクエリ
テーブルに `Query` を実行するのとほぼ同じ方法で、グローバルセカンダリインデックスに対する `Query` を使用することができます。インデックス名、インデックスパーティションキーとソートキー (存在する場合) のクエリ条件、および返す属性を指定する必要があります。この例では、インデックスは `PrecipIndex` で、パーティションキーが `Date` で、ソートキーが `Precipitation` です。このインデックスクエリは、降水量がゼロより大きい特定の日付のすべての気象データを返します。
AWS SDK for Java ドキュメント API を使用してグローバルセカンダリインデックスをクエリする手順を次に示します。
1. `DynamoDB` クラスのインスタンスを作成します。
1. 操作対象のインデックスを表すために、`Table` クラスのインスタンスを作成します。
1. クエリするインデックスの `Index` クラスのインスタンスを作成します。
1. `Index` オブジェクトの `query` メソッドを呼び出します。
属性名 `Date` は DynamoDB の予約語です。したがって、式の属性名を `KeyConditionExpression` のプレースホルダーとして使用する必要があります。
以下の Java コード例は、前述のステップの例です。
**Example**
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
Table table = dynamoDB.getTable("WeatherData");
Index index = table.getIndex("PrecipIndex");
QuerySpec spec = new QuerySpec()
.withKeyConditionExpression("#d = :v_date and Precipitation = :v_precip")
.withNameMap(new NameMap()
.with("#d", "Date"))
.withValueMap(new ValueMap()
.withString(":v_date","2013-08-10")
.withNumber(":v_precip",0));
ItemCollection items = index.query(spec);
Iterator- iter = items.iterator();
while (iter.hasNext()) {
System.out.println(iter.next().toJSONPretty());
}
```
# 例: AWS SDK for Java ドキュメント API を使用したグローバルセカンダリインデックス
次の Java コード例は、グローバルセカンダリインデックスの操作方法を示しています。この例では、`Issues` というテーブルを作成しています。これは、ソフトウェア開発のためのシンプルなバグ追跡システムで使用できる可能性があります。パーティションキーは `IssueId` で、ソートキーは `Title` です。このテーブルには、次の 3 つのグローバルセカンダリインデックスがあります。
+ `CreateDateIndex` – パーティションキーは `CreateDate` で、ソートキーは `IssueId` です。テーブルキーに加えて、属性 `Description` および `Status` はインデックスに射影されます。
+ `TitleIndex` – パーティションキーは `Title` で、ソートキーは `IssueId` です。テーブルキー以外の属性はインデックスに射影されません。
+ `DueDateIndex` – パーティションキーは `DueDate` で、ソートキーはありません。すべてのテーブル属性がインデックスに射影されます。
`Issues` テーブルが作成されると、プログラムはソフトウェアのバグレポートを表すデータをテーブルにロードします。次に、グローバルセカンダリインデックスを使用してデータのクエリを実行します。最後に、プログラムは `Issues` テーブルを削除します。
以下の例をテストするための詳細な手順については、「[Java コードの例](CodeSamples.Java.md)」を参照してください。
**Example**
```
package com.amazonaws.codesamples.document;
import java.util.ArrayList;
import java.util.Iterator;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDB;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder;
import com.amazonaws.services.dynamodbv2.document.DynamoDB;
import com.amazonaws.services.dynamodbv2.document.Index;
import com.amazonaws.services.dynamodbv2.document.Item;
import com.amazonaws.services.dynamodbv2.document.ItemCollection;
import com.amazonaws.services.dynamodbv2.document.QueryOutcome;
import com.amazonaws.services.dynamodbv2.document.Table;
import com.amazonaws.services.dynamodbv2.document.spec.QuerySpec;
import com.amazonaws.services.dynamodbv2.document.utils.ValueMap;
import com.amazonaws.services.dynamodbv2.model.AttributeDefinition;
import com.amazonaws.services.dynamodbv2.model.CreateTableRequest;
import com.amazonaws.services.dynamodbv2.model.GlobalSecondaryIndex;
import com.amazonaws.services.dynamodbv2.model.KeySchemaElement;
import com.amazonaws.services.dynamodbv2.model.KeyType;
import com.amazonaws.services.dynamodbv2.model.Projection;
import com.amazonaws.services.dynamodbv2.model.ProvisionedThroughput;
public class DocumentAPIGlobalSecondaryIndexExample {
static AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
static DynamoDB dynamoDB = new DynamoDB(client);
public static String tableName = "Issues";
public static void main(String[] args) throws Exception {
createTable();
loadData();
queryIndex("CreateDateIndex");
queryIndex("TitleIndex");
queryIndex("DueDateIndex");
deleteTable(tableName);
}
public static void createTable() {
// Attribute definitions
ArrayList attributeDefinitions = new ArrayList();
attributeDefinitions.add(new AttributeDefinition().withAttributeName("IssueId").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("Title").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("CreateDate").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("DueDate").withAttributeType("S"));
// Key schema for table
ArrayList tableKeySchema = new ArrayList();
tableKeySchema.add(new KeySchemaElement().withAttributeName("IssueId").withKeyType(KeyType.HASH)); // Partition
// key
tableKeySchema.add(new KeySchemaElement().withAttributeName("Title").withKeyType(KeyType.RANGE)); // Sort
// key
// Initial provisioned throughput settings for the indexes
ProvisionedThroughput ptIndex = new ProvisionedThroughput().withReadCapacityUnits(1L)
.withWriteCapacityUnits(1L);
// CreateDateIndex
GlobalSecondaryIndex createDateIndex = new GlobalSecondaryIndex().withIndexName("CreateDateIndex")
.withProvisionedThroughput(ptIndex)
.withKeySchema(new KeySchemaElement().withAttributeName("CreateDate").withKeyType(KeyType.HASH), // Partition
// key
new KeySchemaElement().withAttributeName("IssueId").withKeyType(KeyType.RANGE)) // Sort
// key
.withProjection(
new Projection().withProjectionType("INCLUDE").withNonKeyAttributes("Description", "Status"));
// TitleIndex
GlobalSecondaryIndex titleIndex = new GlobalSecondaryIndex().withIndexName("TitleIndex")
.withProvisionedThroughput(ptIndex)
.withKeySchema(new KeySchemaElement().withAttributeName("Title").withKeyType(KeyType.HASH), // Partition
// key
new KeySchemaElement().withAttributeName("IssueId").withKeyType(KeyType.RANGE)) // Sort
// key
.withProjection(new Projection().withProjectionType("KEYS_ONLY"));
// DueDateIndex
GlobalSecondaryIndex dueDateIndex = new GlobalSecondaryIndex().withIndexName("DueDateIndex")
.withProvisionedThroughput(ptIndex)
.withKeySchema(new KeySchemaElement().withAttributeName("DueDate").withKeyType(KeyType.HASH)) // Partition
// key
.withProjection(new Projection().withProjectionType("ALL"));
CreateTableRequest createTableRequest = new CreateTableRequest().withTableName(tableName)
.withProvisionedThroughput(
new ProvisionedThroughput().withReadCapacityUnits((long) 1).withWriteCapacityUnits((long) 1))
.withAttributeDefinitions(attributeDefinitions).withKeySchema(tableKeySchema)
.withGlobalSecondaryIndexes(createDateIndex, titleIndex, dueDateIndex);
System.out.println("Creating table " + tableName + "...");
dynamoDB.createTable(createTableRequest);
// Wait for table to become active
System.out.println("Waiting for " + tableName + " to become ACTIVE...");
try {
Table table = dynamoDB.getTable(tableName);
table.waitForActive();
} catch (InterruptedException e) {
e.printStackTrace();
}
}
public static void queryIndex(String indexName) {
Table table = dynamoDB.getTable(tableName);
System.out.println("\n***********************************************************\n");
System.out.print("Querying index " + indexName + "...");
Index index = table.getIndex(indexName);
ItemCollection items = null;
QuerySpec querySpec = new QuerySpec();
if (indexName == "CreateDateIndex") {
System.out.println("Issues filed on 2013-11-01");
querySpec.withKeyConditionExpression("CreateDate = :v_date and begins_with(IssueId, :v_issue)")
.withValueMap(new ValueMap().withString(":v_date", "2013-11-01").withString(":v_issue", "A-"));
items = index.query(querySpec);
} else if (indexName == "TitleIndex") {
System.out.println("Compilation errors");
querySpec.withKeyConditionExpression("Title = :v_title and begins_with(IssueId, :v_issue)")
.withValueMap(
new ValueMap().withString(":v_title", "Compilation error").withString(":v_issue", "A-"));
items = index.query(querySpec);
} else if (indexName == "DueDateIndex") {
System.out.println("Items that are due on 2013-11-30");
querySpec.withKeyConditionExpression("DueDate = :v_date")
.withValueMap(new ValueMap().withString(":v_date", "2013-11-30"));
items = index.query(querySpec);
} else {
System.out.println("\nNo valid index name provided");
return;
}
Iterator
- iterator = items.iterator();
System.out.println("Query: printing results...");
while (iterator.hasNext()) {
System.out.println(iterator.next().toJSONPretty());
}
}
public static void deleteTable(String tableName) {
System.out.println("Deleting table " + tableName + "...");
Table table = dynamoDB.getTable(tableName);
table.delete();
// Wait for table to be deleted
System.out.println("Waiting for " + tableName + " to be deleted...");
try {
table.waitForDelete();
} catch (InterruptedException e) {
e.printStackTrace();
}
}
public static void loadData() {
System.out.println("Loading data into table " + tableName + "...");
// IssueId, Title,
// Description,
// CreateDate, LastUpdateDate, DueDate,
// Priority, Status
putItem("A-101", "Compilation error", "Can't compile Project X - bad version number. What does this mean?",
"2013-11-01", "2013-11-02", "2013-11-10", 1, "Assigned");
putItem("A-102", "Can't read data file", "The main data file is missing, or the permissions are incorrect",
"2013-11-01", "2013-11-04", "2013-11-30", 2, "In progress");
putItem("A-103", "Test failure", "Functional test of Project X produces errors", "2013-11-01", "2013-11-02",
"2013-11-10", 1, "In progress");
putItem("A-104", "Compilation error", "Variable 'messageCount' was not initialized.", "2013-11-15",
"2013-11-16", "2013-11-30", 3, "Assigned");
putItem("A-105", "Network issue", "Can't ping IP address 127.0.0.1. Please fix this.", "2013-11-15",
"2013-11-16", "2013-11-19", 5, "Assigned");
}
public static void putItem(
String issueId, String title, String description, String createDate, String lastUpdateDate, String dueDate,
Integer priority, String status) {
Table table = dynamoDB.getTable(tableName);
Item item = new Item().withPrimaryKey("IssueId", issueId).withString("Title", title)
.withString("Description", description).withString("CreateDate", createDate)
.withString("LastUpdateDate", lastUpdateDate).withString("DueDate", dueDate)
.withNumber("Priority", priority).withString("Status", status);
table.putItem(item);
}
}
```
# グローバルセカンダリインデックスの操作: .NET
AWS SDK for .NET 低レベル API を使用して、1 つ以上のグローバルセカンダリインデックスを含む Amazon DynamoDB テーブルを作成し、テーブルのインデックスを記述し、インデックスを使用してクエリを実行できます。これらのオペレーションは、対応する DynamoDB オペレーションにマッピングされます。詳細については、「[Amazon DynamoDB API リファレンス](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)」を参照してください。
以下に、.NET 低レベル API を使用したテーブルオペレーションの一般的な手順を示します。
1. `AmazonDynamoDBClient` クラスのインスタンスを作成します。
1. 対応するリクエストオブジェクトを作成して、オペレーションについて必要なパラメータとオプションパラメータを入力します。
たとえば、テーブルを作成するには `CreateTableRequest` オブジェクトを作成し、テーブルやインデックスにクエリを実行するには `QueryRequest` オブジェクトを作成します。
1. 前述のステップで作成したクライアントから提供された適切なメソッドを実行します。
**Topics**
+ [グローバルセカンダリインデックスを持つテーブルを作成します](#GSILowLevelDotNet.CreateTableWithIndex)
+ [グローバルセカンダリインデックスを持つテーブルの説明](#GSILowLevelDotNet.DescribeTableWithIndex)
+ [グローバルセカンダリインデックスのクエリ](#GSILowLevelDotNet.QueryAnIndex)
+ [例: AWS SDK for .NET 低レベル API を使用したグローバルセカンダリインデックス](GSILowLevelDotNet.Example.md)
## グローバルセカンダリインデックスを持つテーブルを作成します
グローバルセカンダリインデックスは、テーブルの作成と同時に作成できます。これを行うには、`CreateTable` を使用し、1 つ以上のグローバルセカンダリインデックスの仕様を指定します。次の C\$1 コード例では、気象データに関する情報を保持するテーブルを作成しています。パーティションキーは `Location` で、ソートキーは `Date` です。グローバルセカンダリインデックス `PrecipIndex` は、さまざまな場所の降水データへの高速アクセスを可能にします。
.NET 低レベル API を使用して、グローバルセカンダリインデックスを含むテーブルを作成する手順を次に示します。
1. `AmazonDynamoDBClient` クラスのインスタンスを作成します。
1. リクエスト情報を指定する `CreateTableRequest` クラスのインスタンスを作成します。
テーブル名、プライマリキー、およびプロビジョニングされたスループット値を指定する必要があります。グローバルセカンダリインデックスの場合は、インデックス名、プロビジョニングされたスループット設定、インデックスソートキーの属性定義、インデックスのキースキーマ、および属性射影を指定する必要があります。
1. リクエストオブジェクトをパラメータとして指定して、`CreateTable` メソッドを実行します。
以下の C\$1 サンプルコードは、前述のステップの例です。このコードは、グローバルセカンダリインデックス (`PrecipIndex`) を持つテーブル (`WeatherData`) を作成します。インデックスパーティションキーは `Date` で、ソートキーは `Precipitation` です。すべてのテーブル属性がインデックスに射影されます。ユーザーは、このインデックスに対するクエリを実行して、特定の日付の気象データを取得できます。必要に応じて、降水量によってデータを並べ替えることもできます。
`Precipitation` はテーブルのキー属性ではないため、必須ではありません。ただし、`Precipitation` のない `WeatherData` 項目は `PrecipIndex` に表示されません。
```
client = new AmazonDynamoDBClient();
string tableName = "WeatherData";
// Attribute definitions
var attributeDefinitions = new List()
{
{new AttributeDefinition{
AttributeName = "Location",
AttributeType = "S"}},
{new AttributeDefinition{
AttributeName = "Date",
AttributeType = "S"}},
{new AttributeDefinition(){
AttributeName = "Precipitation",
AttributeType = "N"}
}
};
// Table key schema
var tableKeySchema = new List()
{
{new KeySchemaElement {
AttributeName = "Location",
KeyType = "HASH"}}, //Partition key
{new KeySchemaElement {
AttributeName = "Date",
KeyType = "RANGE"} //Sort key
}
};
// PrecipIndex
var precipIndex = new GlobalSecondaryIndex
{
IndexName = "PrecipIndex",
ProvisionedThroughput = new ProvisionedThroughput
{
ReadCapacityUnits = (long)10,
WriteCapacityUnits = (long)1
},
Projection = new Projection { ProjectionType = "ALL" }
};
var indexKeySchema = new List {
{new KeySchemaElement { AttributeName = "Date", KeyType = "HASH"}}, //Partition key
{new KeySchemaElement{AttributeName = "Precipitation",KeyType = "RANGE"}} //Sort key
};
precipIndex.KeySchema = indexKeySchema;
CreateTableRequest createTableRequest = new CreateTableRequest
{
TableName = tableName,
ProvisionedThroughput = new ProvisionedThroughput
{
ReadCapacityUnits = (long)5,
WriteCapacityUnits = (long)1
},
AttributeDefinitions = attributeDefinitions,
KeySchema = tableKeySchema,
GlobalSecondaryIndexes = { precipIndex }
};
CreateTableResponse response = client.CreateTable(createTableRequest);
Console.WriteLine(response.CreateTableResult.TableDescription.TableName);
Console.WriteLine(response.CreateTableResult.TableDescription.TableStatus);
```
DynamoDB がテーブルを作成し、テーブルのステータスを `ACTIVE` に設定するまで待機する必要があります。その後、テーブルへのデータ項目の入力を開始できます。
## グローバルセカンダリインデックスを持つテーブルの説明
テーブルでグローバルセカンダリインデックスに関する情報を取得するには、`DescribeTable` を使用します。インデックスごとに、名前、キースキーマ、および射影された属性にアクセスできます。
.NET 低レベル API を使用してテーブルのグローバルセカンダリインデックス情報にアクセスするには次の手順に従います。
1. `AmazonDynamoDBClient` クラスのインスタンスを作成します。
1. リクエストオブジェクトをパラメータとして指定して、`describeTable` メソッドを実行します。
リクエスト情報を指定する `DescribeTableRequest` クラスのインスタンスを作成します。テーブル名を入力する必要があります。
以下の C\$1 サンプルコードは、前述のステップの例です。
**Example**
```
client = new AmazonDynamoDBClient();
string tableName = "WeatherData";
DescribeTableResponse response = client.DescribeTable(new DescribeTableRequest { TableName = tableName});
List globalSecondaryIndexes =
response.DescribeTableResult.Table.GlobalSecondaryIndexes;
// This code snippet will work for multiple indexes, even though
// there is only one index in this example.
foreach (GlobalSecondaryIndexDescription gsiDescription in globalSecondaryIndexes) {
Console.WriteLine("Info for index " + gsiDescription.IndexName + ":");
foreach (KeySchemaElement kse in gsiDescription.KeySchema) {
Console.WriteLine("\t" + kse.AttributeName + ": key type is " + kse.KeyType);
}
Projection projection = gsiDescription.Projection;
Console.WriteLine("\tThe projection type is: " + projection.ProjectionType);
if (projection.ProjectionType.ToString().Equals("INCLUDE")) {
Console.WriteLine("\t\tThe non-key projected attributes are: "
+ projection.NonKeyAttributes);
}
}
```
## グローバルセカンダリインデックスのクエリ
テーブルに `Query` を実行するのとほぼ同じ方法で、グローバルセカンダリインデックスに対する `Query` を使用することができます。インデックス名、インデックスパーティションキーとソートキー (存在する場合) のクエリ条件、および返す属性を指定する必要があります。この例では、インデックスは `PrecipIndex` で、パーティションキーが `Date` で、ソートキーが `Precipitation` です。このインデックスクエリは、降水量がゼロより大きい特定の日付のすべての気象データを返します。
.NET 低レベル API を使用して、グローバルセカンダリインデックスを含むテーブルにクエリを実行する手順を次に示します。
1. `AmazonDynamoDBClient` クラスのインスタンスを作成します。
1. リクエスト情報を指定する `QueryRequest` クラスのインスタンスを作成します。
1. リクエストオブジェクトをパラメータとして指定して、`query` メソッドを実行します。
属性名 `Date` は DynamoDB の予約語です。したがって、式の属性名を `KeyConditionExpression` のプレースホルダーとして使用する必要があります。
以下の C\$1 サンプルコードは、前述のステップの例です。
**Example**
```
client = new AmazonDynamoDBClient();
QueryRequest queryRequest = new QueryRequest
{
TableName = "WeatherData",
IndexName = "PrecipIndex",
KeyConditionExpression = "#dt = :v_date and Precipitation > :v_precip",
ExpressionAttributeNames = new Dictionary {
{"#dt", "Date"}
},
ExpressionAttributeValues = new Dictionary {
{":v_date", new AttributeValue { S = "2013-08-01" }},
{":v_precip", new AttributeValue { N = "0" }}
},
ScanIndexForward = true
};
var result = client.Query(queryRequest);
var items = result.Items;
foreach (var currentItem in items)
{
foreach (string attr in currentItem.Keys)
{
Console.Write(attr + "---> ");
if (attr == "Precipitation")
{
Console.WriteLine(currentItem[attr].N);
}
else
{
Console.WriteLine(currentItem[attr].S);
}
}
Console.WriteLine();
}
```
# 例: AWS SDK for .NET 低レベル API を使用したグローバルセカンダリインデックス
次の C\$1 コード例は、グローバルセカンダリインデックスの操作方法を示しています。この例では、`Issues` というテーブルを作成しています。これは、ソフトウェア開発のためのシンプルなバグ追跡システムで使用できる可能性があります。パーティションキーは `IssueId` で、ソートキーは `Title` です。このテーブルには、次の 3 つのグローバルセカンダリインデックスがあります。
+ `CreateDateIndex` – パーティションキーは `CreateDate` で、ソートキーは `IssueId` です。テーブルキーに加えて、属性 `Description` および `Status` はインデックスに射影されます。
+ `TitleIndex` – パーティションキーは `Title` で、ソートキーは `IssueId` です。テーブルキー以外の属性はインデックスに射影されません。
+ `DueDateIndex` – パーティションキーは `DueDate` で、ソートキーはありません。すべてのテーブル属性がインデックスに射影されます。
`Issues` テーブルが作成されると、プログラムはソフトウェアのバグレポートを表すデータをテーブルにロードします。次に、グローバルセカンダリインデックスを使用してデータのクエリを実行します。最後に、プログラムは `Issues` テーブルを削除します。
以下の例をテストするための詳細な手順については、「[.NET コード例](CodeSamples.DotNet.md)」を参照してください。
**Example**
```
using System;
using System.Collections.Generic;
using System.Linq;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DataModel;
using Amazon.DynamoDBv2.DocumentModel;
using Amazon.DynamoDBv2.Model;
using Amazon.Runtime;
using Amazon.SecurityToken;
namespace com.amazonaws.codesamples
{
class LowLevelGlobalSecondaryIndexExample
{
private static AmazonDynamoDBClient client = new AmazonDynamoDBClient();
public static String tableName = "Issues";
public static void Main(string[] args)
{
CreateTable();
LoadData();
QueryIndex("CreateDateIndex");
QueryIndex("TitleIndex");
QueryIndex("DueDateIndex");
DeleteTable(tableName);
Console.WriteLine("To continue, press enter");
Console.Read();
}
private static void CreateTable()
{
// Attribute definitions
var attributeDefinitions = new List()
{
{new AttributeDefinition {
AttributeName = "IssueId", AttributeType = "S"
}},
{new AttributeDefinition {
AttributeName = "Title", AttributeType = "S"
}},
{new AttributeDefinition {
AttributeName = "CreateDate", AttributeType = "S"
}},
{new AttributeDefinition {
AttributeName = "DueDate", AttributeType = "S"
}}
};
// Key schema for table
var tableKeySchema = new List() {
{
new KeySchemaElement {
AttributeName= "IssueId",
KeyType = "HASH" //Partition key
}
},
{
new KeySchemaElement {
AttributeName = "Title",
KeyType = "RANGE" //Sort key
}
}
};
// Initial provisioned throughput settings for the indexes
var ptIndex = new ProvisionedThroughput
{
ReadCapacityUnits = 1L,
WriteCapacityUnits = 1L
};
// CreateDateIndex
var createDateIndex = new GlobalSecondaryIndex()
{
IndexName = "CreateDateIndex",
ProvisionedThroughput = ptIndex,
KeySchema = {
new KeySchemaElement {
AttributeName = "CreateDate", KeyType = "HASH" //Partition key
},
new KeySchemaElement {
AttributeName = "IssueId", KeyType = "RANGE" //Sort key
}
},
Projection = new Projection
{
ProjectionType = "INCLUDE",
NonKeyAttributes = {
"Description", "Status"
}
}
};
// TitleIndex
var titleIndex = new GlobalSecondaryIndex()
{
IndexName = "TitleIndex",
ProvisionedThroughput = ptIndex,
KeySchema = {
new KeySchemaElement {
AttributeName = "Title", KeyType = "HASH" //Partition key
},
new KeySchemaElement {
AttributeName = "IssueId", KeyType = "RANGE" //Sort key
}
},
Projection = new Projection
{
ProjectionType = "KEYS_ONLY"
}
};
// DueDateIndex
var dueDateIndex = new GlobalSecondaryIndex()
{
IndexName = "DueDateIndex",
ProvisionedThroughput = ptIndex,
KeySchema = {
new KeySchemaElement {
AttributeName = "DueDate",
KeyType = "HASH" //Partition key
}
},
Projection = new Projection
{
ProjectionType = "ALL"
}
};
var createTableRequest = new CreateTableRequest
{
TableName = tableName,
ProvisionedThroughput = new ProvisionedThroughput
{
ReadCapacityUnits = (long)1,
WriteCapacityUnits = (long)1
},
AttributeDefinitions = attributeDefinitions,
KeySchema = tableKeySchema,
GlobalSecondaryIndexes = {
createDateIndex, titleIndex, dueDateIndex
}
};
Console.WriteLine("Creating table " + tableName + "...");
client.CreateTable(createTableRequest);
WaitUntilTableReady(tableName);
}
private static void LoadData()
{
Console.WriteLine("Loading data into table " + tableName + "...");
// IssueId, Title,
// Description,
// CreateDate, LastUpdateDate, DueDate,
// Priority, Status
putItem("A-101", "Compilation error",
"Can't compile Project X - bad version number. What does this mean?",
"2013-11-01", "2013-11-02", "2013-11-10",
1, "Assigned");
putItem("A-102", "Can't read data file",
"The main data file is missing, or the permissions are incorrect",
"2013-11-01", "2013-11-04", "2013-11-30",
2, "In progress");
putItem("A-103", "Test failure",
"Functional test of Project X produces errors",
"2013-11-01", "2013-11-02", "2013-11-10",
1, "In progress");
putItem("A-104", "Compilation error",
"Variable 'messageCount' was not initialized.",
"2013-11-15", "2013-11-16", "2013-11-30",
3, "Assigned");
putItem("A-105", "Network issue",
"Can't ping IP address 127.0.0.1. Please fix this.",
"2013-11-15", "2013-11-16", "2013-11-19",
5, "Assigned");
}
private static void putItem(
String issueId, String title,
String description,
String createDate, String lastUpdateDate, String dueDate,
Int32 priority, String status)
{
Dictionary item = new Dictionary();
item.Add("IssueId", new AttributeValue
{
S = issueId
});
item.Add("Title", new AttributeValue
{
S = title
});
item.Add("Description", new AttributeValue
{
S = description
});
item.Add("CreateDate", new AttributeValue
{
S = createDate
});
item.Add("LastUpdateDate", new AttributeValue
{
S = lastUpdateDate
});
item.Add("DueDate", new AttributeValue
{
S = dueDate
});
item.Add("Priority", new AttributeValue
{
N = priority.ToString()
});
item.Add("Status", new AttributeValue
{
S = status
});
try
{
client.PutItem(new PutItemRequest
{
TableName = tableName,
Item = item
});
}
catch (Exception e)
{
Console.WriteLine(e.ToString());
}
}
private static void QueryIndex(string indexName)
{
Console.WriteLine
("\n***********************************************************\n");
Console.WriteLine("Querying index " + indexName + "...");
QueryRequest queryRequest = new QueryRequest
{
TableName = tableName,
IndexName = indexName,
ScanIndexForward = true
};
String keyConditionExpression;
Dictionary expressionAttributeValues = new Dictionary();
if (indexName == "CreateDateIndex")
{
Console.WriteLine("Issues filed on 2013-11-01\n");
keyConditionExpression = "CreateDate = :v_date and begins_with(IssueId, :v_issue)";
expressionAttributeValues.Add(":v_date", new AttributeValue
{
S = "2013-11-01"
});
expressionAttributeValues.Add(":v_issue", new AttributeValue
{
S = "A-"
});
}
else if (indexName == "TitleIndex")
{
Console.WriteLine("Compilation errors\n");
keyConditionExpression = "Title = :v_title and begins_with(IssueId, :v_issue)";
expressionAttributeValues.Add(":v_title", new AttributeValue
{
S = "Compilation error"
});
expressionAttributeValues.Add(":v_issue", new AttributeValue
{
S = "A-"
});
// Select
queryRequest.Select = "ALL_PROJECTED_ATTRIBUTES";
}
else if (indexName == "DueDateIndex")
{
Console.WriteLine("Items that are due on 2013-11-30\n");
keyConditionExpression = "DueDate = :v_date";
expressionAttributeValues.Add(":v_date", new AttributeValue
{
S = "2013-11-30"
});
// Select
queryRequest.Select = "ALL_PROJECTED_ATTRIBUTES";
}
else
{
Console.WriteLine("\nNo valid index name provided");
return;
}
queryRequest.KeyConditionExpression = keyConditionExpression;
queryRequest.ExpressionAttributeValues = expressionAttributeValues;
var result = client.Query(queryRequest);
var items = result.Items;
foreach (var currentItem in items)
{
foreach (string attr in currentItem.Keys)
{
if (attr == "Priority")
{
Console.WriteLine(attr + "---> " + currentItem[attr].N);
}
else
{
Console.WriteLine(attr + "---> " + currentItem[attr].S);
}
}
Console.WriteLine();
}
}
private static void DeleteTable(string tableName)
{
Console.WriteLine("Deleting table " + tableName + "...");
client.DeleteTable(new DeleteTableRequest
{
TableName = tableName
});
WaitForTableToBeDeleted(tableName);
}
private static void WaitUntilTableReady(string tableName)
{
string status = null;
// Let us wait until table is created. Call DescribeTable.
do
{
System.Threading.Thread.Sleep(5000); // Wait 5 seconds.
try
{
var res = client.DescribeTable(new DescribeTableRequest
{
TableName = tableName
});
Console.WriteLine("Table name: {0}, status: {1}",
res.Table.TableName,
res.Table.TableStatus);
status = res.Table.TableStatus;
}
catch (ResourceNotFoundException)
{
// DescribeTable is eventually consistent. So you might
// get resource not found. So we handle the potential exception.
}
} while (status != "ACTIVE");
}
private static void WaitForTableToBeDeleted(string tableName)
{
bool tablePresent = true;
while (tablePresent)
{
System.Threading.Thread.Sleep(5000); // Wait 5 seconds.
try
{
var res = client.DescribeTable(new DescribeTableRequest
{
TableName = tableName
});
Console.WriteLine("Table name: {0}, status: {1}",
res.Table.TableName,
res.Table.TableStatus);
}
catch (ResourceNotFoundException)
{
tablePresent = false;
}
}
}
}
}
```
# AWS CLI を使用した DynamoDBでのグローバルセカンダリインデックスの操作
AWS CLI を使用して、1 つ以上のグローバルセカンダリインデックスを含む Amazon DynamoDB テーブルを作成し、テーブルのインデックスを記述し、インデックスを使用してクエリを実行できます。
**Topics**
+ [グローバルセカンダリインデックスを持つテーブルを作成します](#GCICli.CreateTableWithIndex)
+ [グローバルセカンダリインデックスを既存のテーブルに追加します](#GCICli.CreateIndexAfterTable)
+ [グローバルセカンダリインデックスを持つテーブルの説明](#GCICli.DescribeTableWithIndex)
+ [グローバルセカンダリインデックスのクエリ](#GCICli.QueryAnIndex)
## グローバルセカンダリインデックスを持つテーブルを作成します
グローバルセカンダリインデックスは、テーブルの作成と同時に作成できます。 これを行うには、`create-table` パラメータを使用し、1 つ以上のグローバルセカンダリインデックスの仕様を指定します。次の例では、`GameTitleIndex` と呼ばれるグローバルセカンダリインデックスを含む `GameScores` という名前のテーブルを作成します。ベーステーブルには、パーティションキー `UserId` とソートキー `GameTitle` があり、特定のゲームの個々のユーザーのベストスコアを効率的に見つけることができます。一方、GSI にはパーティションキー `GameTitle` とソートキー `TopScore` があり、特定のゲームの全体的な最高スコアをすばやく見つけることができます。
```
aws dynamodb create-table \
--table-name GameScores \
--attribute-definitions AttributeName=UserId,AttributeType=S \
AttributeName=GameTitle,AttributeType=S \
AttributeName=TopScore,AttributeType=N \
--key-schema AttributeName=UserId,KeyType=HASH \
AttributeName=GameTitle,KeyType=RANGE \
--provisioned-throughput ReadCapacityUnits=10,WriteCapacityUnits=5 \
--global-secondary-indexes \
"[
{
\"IndexName\": \"GameTitleIndex\",
\"KeySchema\": [{\"AttributeName\":\"GameTitle\",\"KeyType\":\"HASH\"},
{\"AttributeName\":\"TopScore\",\"KeyType\":\"RANGE\"}],
\"Projection\":{
\"ProjectionType\":\"INCLUDE\",
\"NonKeyAttributes\":[\"UserId\"]
},
\"ProvisionedThroughput\": {
\"ReadCapacityUnits\": 10,
\"WriteCapacityUnits\": 5
}
}
]"
```
DynamoDB がテーブルを作成し、テーブルのステータスを `ACTIVE` に設定するまで待機する必要があります。その後、テーブルへのデータ項目の入力を開始できます。[describe-table](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/describe-table.html) を使用して、テーブル作成のステータスを判断できます。
## グローバルセカンダリインデックスを既存のテーブルに追加します
グローバルセカンダリインデックスは、テーブルの作成後に追加したり変更したりすることもできます。これを行うには、`update-table` パラメータを使用し、1 つ以上のグローバルセカンダリインデックスの仕様を指定します。次の例では、前の例と同じスキーマを使用していますが、テーブルが既に作成されており、後で GSI を追加する場合を想定しています。
```
aws dynamodb update-table \
--table-name GameScores \
--attribute-definitions AttributeName=TopScore,AttributeType=N \
--global-secondary-index-updates \
"[
{
\"Create\": {
\"IndexName\": \"GameTitleIndex\",
\"KeySchema\": [{\"AttributeName\":\"GameTitle\",\"KeyType\":\"HASH\"},
{\"AttributeName\":\"TopScore\",\"KeyType\":\"RANGE\"}],
\"Projection\":{
\"ProjectionType\":\"INCLUDE\",
\"NonKeyAttributes\":[\"UserId\"]
}
}
}
]"
```
## グローバルセカンダリインデックスを持つテーブルの説明
テーブルのグローバルセカンダリインデックスに関する情報を取得するには、`describe-table` パラメータを使用します。インデックスごとに、名前、キースキーマ、および射影された属性にアクセスできます。
```
aws dynamodb describe-table --table-name GameScores
```
## グローバルセカンダリインデックスのクエリ
テーブルに `query` を実行するのとほぼ同じ方法で、グローバルセカンダリインデックスに対する `query` オペレーションを使用することができます。インデックス名、インデックスソートキーのクエリ条件、および返す属性を指定する必要があります。この例では、インデックスは `GameTitleIndex`、インデックスソートキーは `GameTitle` です。
返される属性は、インデックスに射影された属性だけです。このクエリを変更して非キー属性を選択することもできますが、これには比較的コストのかかるテーブルフェッチアクティビティが必要です。テーブルのフェッチの詳細については、「[属性の射影](GSI.md#GSI.Projections)」を参照してください。
```
aws dynamodb query --table-name GameScores\
--index-name GameTitleIndex \
--key-condition-expression "GameTitle = :v_game" \
--expression-attribute-values '{":v_game":{"S":"Alien Adventure"} }'
```
# ローカルセカンダリインデックス
ベーステーブルのプライマリキーを使用してデータのクエリを実行する必要があるのは、一部のアプリケーションだけです。ただし、代替のソートキーが役に立つ場合があります。アプリケーションでソートキーを選択できるようにするには、Amazon DynamoDB テーブルに 1 つ以上のローカルセカンダリインデックスを作成し、これらのインデックスに対して `Query` または `Scan` のリクエストを発行できます。
**Topics**
+ [シナリオ: ローカルセカンダリインデックスの使用](#LSI.Scenario)
+ [属性の射影](#LSI.Projections)
+ [ローカルセカンダリインデックスの作成](#LSI.Creating)
+ [ローカルセカンダリインデックスからのデータの読み込み](#LSI.Reading)
+ [項目の書き込みとローカルセカンダリインデックス](#LSI.Writes)
+ [ローカルセカンダリインデックスに対するプロビジョニングされたスループットに関する考慮事項](#LSI.ThroughputConsiderations)
+ [ローカルセカンダリインデックスのストレージに関する考慮事項](#LSI.StorageConsiderations)
+ [ローカルセカンダリインデックス内の項目コレクション](#LSI.ItemCollections)
+ [ローカルセカンダリインデックスの操作: Java](LSIJavaDocumentAPI.md)
+ [ローカルセカンダリインデックスの操作: .NET](LSILowLevelDotNet.md)
+ [DynamoDB AWS CLI でのローカルセカンダリインデックスの操作](LCICli.md)
## シナリオ: ローカルセカンダリインデックスの使用
例として、`Thread` テーブルを検討します。このテーブルは、[AWS ディスカッションフォーラム](https://forums.aws.amazon.com/)のようなアプリケーションで役立ちます。次の図は、テーブル内の項目の構成を示しています。一部表示されていない属性もあります。
![\[フォーラム名、件名、最後の投稿時刻、および返信数のリストを含む Thread テーブル。\]](http://docs.aws.amazon.com/ja_jp/amazondynamodb/latest/developerguide/images/LSI_01.png)
DynamoDB には、同じパーティションキー値を持つすべての項目が継続的に保存されます。この例では、特定の `ForumName` を指定すると、`Query` オペレーションはそのフォーラムのすべてのスレッドをすばやく見つけることができます。同じパーティションキー値を持つ項目のグループでは、項目がソートキーの値によって並べ替えられます。ソートキー (`Subject`) がクエリでも提供される場合、DynamoDB は返される結果を絞り込むことができます。例えば、「S3」フォーラムで、文字「a」で始まる `Subject` を持つすべてのスレッドを返すことができます。
リクエストによっては、より複雑なデータアクセスパターンが要求される場合があります。以下に例を示します。
+ ビューと返信の数が最も多いのはどのフォーラムか?
+ 特定のフォーラムでメッセージ数が最も多いのはどのスレッドか?
+ 特定の期間中に特定のフォーラムに投稿されたスレッド数は?
これらの質問に答えるには、`Query` アクションでは十分ではありません。代わりに、テーブル全体の `Scan` を実行する必要があります。膨大な数の項目があるテーブルでは、これにより、プロビジョニングされた読み込みスループットが大量に消費されることになり、完了するまでに長時間かかります。
ただし、`Replies` や `LastPostDateTime` などの非キー属性に 1 つ以上のローカルセカンダリインデックスを指定することができます。
*ローカルセカンダリインデックス*は特定のパーティションキー値の代替ソートキーを維持します。またローカルセカンダリインデックスには、ベーステーブルの一部またはすべての属性のコピーが含まれます。テーブルを作成する際に、ローカルセカンダリインデックスに射影する属性を指定します。ローカルセカンダリインデックスのデータは、ベーステーブルと同じパーティションキーと、異なるソートキーで構成されます。これにより、この異なるディメンションにわたってデータ項目に効率的にアクセスできます。クエリまたはスキャンの柔軟性を向上させるために、テーブルごとに最大 5 つのローカルセカンダリインデックスを作成できます。
たとえば、あるアプリケーションで、特定のフォーラムに過去 3 か月以内に投稿されたすべてのスレッドを検索する必要があるとします。ローカルセカンダリインデックスがない場合、アプリケーションは `Scan` テーブル全体の `Thread` を実行して、指定された時間枠から外れた投稿を破棄する必要があります。ローカルセカンダリインデックスがあれば、`Query` オペレーションでは `LastPostDateTime` をソートキーとして使用し、データをすばやく見つけることができます。
次の図は、`LastPostIndex` という名前のローカルセカンダリインデックスを示しています。パーティションキーは `Thread` テーブルのパーティションキーと同じですが、ソートキーは `LastPostDateTime` です。
![\[フォーラム名、件名、および最後の投稿時刻のリストを含む LastPostIndex テーブル。\]](http://docs.aws.amazon.com/ja_jp/amazondynamodb/latest/developerguide/images/LSI_02.png)
ローカルセカンダリインデックスは、すべて次の条件を満たす必要があります。
+ パーティションキーはそのベーステーブルのパーティションキーと同じである。
+ ソートキーは完全に 1 つのスカラー属性で構成されている。
+ ベーステーブルのソートキーがインデックスに射影され、非キー属性として機能する。
この例で、パーティションキーは `ForumName`、ローカルセカンダリインデックスのソートキーは `LastPostDateTime` です。さらに、ベーステーブルのソートキーの値 (この例では `Subject`) がインデックスに射影されますが、その値はインデックスキーの一部ではありません。アプリケーションが `ForumName` と `LastPostDateTime` に基づくリストを必要とする場合は、`Query` に対して `LastPostIndex` リクエストを実行できます。クエリ結果は `LastPostDateTime` によってソートされ、昇順または降順で返すことができます。このクエリは、特定の時間枠内に `LastPostDateTime` がある項目だけを返すなどのキー条件を適用することもできます。
すべてのローカルセカンダリインデックスには、そのベーステーブルからのパーティションキーとソートキーが自動的に格納されます。必要に応じて、非キー属性をインデックスに射影できます。インデックスのクエリを行うと、DynamoDB ではこれらの射影された属性を効率的に取り出すことができます。ローカルセカンダリインデックスにクエリを実行すると、インデックスに射影されて*いない*属性もクエリで取得できます。DynamoDB では、これらの属性をベーステーブルから自動的にフェッチしますが、レイテンシーが大きくなり、プロビジョニングされたスループットコストが高くなります。
任意のローカルセカンダリインデックスについて、異なるパーティションキーの値ごとに最大 10 GB のデータを保存できます。この数字には、ベーステーブル内のすべての項目に加えて、同じパーティションキーの値を持つインデックス内のすべての項目も含まれています。詳細については、「[ローカルセカンダリインデックス内の項目コレクション](#LSI.ItemCollections)」を参照してください。
## 属性の射影
`LastPostIndex` では、アプリケーションはクエリの基準として `ForumName` と `LastPostDateTime` を使用できます。ただし、追加の属性を取得する場合、DynamoDB は `Thread` テーブルに対して追加の読み取りオペレーションを実行する必要があります。このような追加の読み込みを*フェッチ*と言い、それによってクエリにプロビジョニングするスループットの合計量が増加することがあります。
ウェブページに「S3」内のすべてのスレッドと各スレッドの返信のリストを表示し、最新の返信の最後の返信日時で並べ替えるとします。このリストに入力するには、次の属性が必要になります。
+ `Subject`
+ `Replies`
+ `LastPostDateTime`
このデータのクエリを最も効率的に行い、フェッチオペレーションを回避するには、次の図に示すように、ローカルセカンダリインデックスにテーブルからの `Replies` 属性を射影します。
![\[フォーラム名、最後の投稿時刻、件名、および返信のリストを含む LastPostIndex テーブル。\]](http://docs.aws.amazon.com/ja_jp/amazondynamodb/latest/developerguide/images/LSI_03.png)
*射影*とは、テーブルからセカンダリインデックスにコピーされる属性のセットです。テーブルのパーティションキーとソートキーは常にインデックスに射影されます。アプリケーションのクエリ要件をサポートするために、他の属性を射影できます。インデックスをクエリすると、Amazon DynamoDB は、その属性が自身のテーブル内にあるかのように、プロジェクション内の任意の属性にアクセスできます。
セカンダリインデックスを作成するときは、インデックスに射影される属性を指定する必要があります。DynamoDB には、そのために次の 3 つのオプションが用意されています。
+ *KEYS\$1ONLY* – インデックス内の各項目は、テーブルパーティションキーとソートキーの値、およびインデックスキーの値のみで構成されます。`KEYS_ONLY` オプションを指定すると、セカンダリインデックスが最小になります。
+ *INCLUDE* – `KEYS_ONLY` の属性に加えて、セカンダリインデックスにその他の非キー属性が含まれるように指定できます。
+ *ALL* – セカンダリインデックスには、ソーステーブルのすべての属性が含まれます。すべてのテーブルデータがインデックスに複製されるため、`ALL` の射影にすると、セカンダリインデックスが最大になります。
前の図では、非キー属性の `Replies` が `LastPostIndex` に射影されています。アプリケーションでは `LastPostIndex` テーブル全体ではなく `Thread` に対するクエリを実行し、ウェブページに `Subject`、`Replies`、`LastPostDateTime` を表示することができます。他の非キー属性がリクエストされた場合、DynamoDB はそれらの属性を `Thread` テーブルからフェッチする必要があります。
アプリケーションの観点から見ると、ベーステーブルから追加の属性をフェッチする処理は、自動的で透過的なので、アプリケーションロジックを書き直す必要はありません。ただし、このようなフェッチによって、ローカルセカンダリインデックスを使用することで得られるパフォーマンスの利点が大幅に小さくなる可能性があります。
ローカルセカンダリインデックスに射影する属性を選択する場合には、プロビジョニングされるスループットコストとストレージコストのトレードオフを考慮する必要があります。
+ ごく一部の属性だけに最小のレイテンシーでアクセスする必要がある場合は、それらの属性だけをローカルセカンダリインデックスに射影することを検討してください。インデックスが小さいほど少ないコストで格納でき、書き込みコストも低くなります。まれにしかフェッチされない属性がある場合には、それらの属性を格納するコストよりも、プロビジョニングされるスループットのコストのほうが長期的に大きくなる可能性があります。
+ アプリケーションが非キー属性に頻繁にアクセスする場合には、それらの属性をローカルセカンダリインデックスに射影することを検討してください。ローカルセカンダリインデックスのストレージコストの増加は、頻繁にテーブルスキャンを実行するコストの減少で相殺されます。
+ ほとんどの非キー属性に頻繁にアクセスする場合は、それらの属性を (場合によっては、ベーステーブル全体を) ローカルセカンダリインデックスに射影することができます。それによってフェッチが不要になるため、柔軟性が最大になり、プロビジョニングされるスループットが最小限になります。ただし、ストレージコストが増加し、すべての属性を射影する場合には 2 倍にまで増大します。
+ アプリケーションでテーブルのクエリを頻繁に行う必要がなく、テーブル内のデータに対する書き込みや更新が多数になる場合は、*KEYS\$1ONLY* を射影することを検討してください。ローカルセカンダリインデックスは、最小サイズになりますが、それでもクエリのアクティビティに必要な場合は利用可能です。
## ローカルセカンダリインデックスの作成
テーブルで 1 つ以上のローカルセカンダリインデックスを作成するには、`CreateTable` オペレーションの `LocalSecondaryIndexes` パラメータを使用します。テーブルのローカルセカンダリインデックスは、テーブルが作成された時点で作成されます。テーブルを削除すると、そのテーブルにあるローカルセカンダリインデックスも削除されます。
ローカルセカンダリインデックスのソートキーにとなる 1 つの非キー属性を指定する必要があります。選択する属性はスカラー `String`、`Number`、または `Binary` である必要があります。その他のスカラー型、ドキュメント型、およびセット型は許可されません。データ型の詳細なリストについては、「[データ型](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes)」を参照してください。
**重要**
ローカルセカンダリインデックスがあるテーブルには、パーティションキーの値ごとに 10 GB のサイズ制限があります。ローカルセカンダリインデックスがあるテーブルには、1 つのパーティションキー値の合計サイズが 10 GB を超えない限り、任意の数の項目を格納できます。詳細については、「」を参照してください[項目コレクションのサイズ制限](#LSI.ItemCollections.SizeLimit)
ローカルセカンダリインデックスには、任意のデータ型の属性を射影できます。これには、スカラー、ドキュメント、およびセットが含まれます。データ型の詳細なリストについては、「[データ型](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes)」を参照してください。
## ローカルセカンダリインデックスからのデータの読み込み
`Query` および `Scan` オペレーションを使用して、ローカルセカンダリインデックスから項目を取得できます。`GetItem` および `BatchGetItem` オペレーションは、ローカルセカンダリインデックスでは使用できません。
### ローカルセカンダリインデックスのクエリ
DynamoDB テーブルでは、各項目のパーティションキー値とソートキー値の組み合わせは、一意である必要があります。ただし、ローカルセカンダリインデックスでは、ソートキーの値は、特定のパーティションキーの値に対して一意である必要がありません。ローカルセカンダリインデックスに同じソートキーを持つ複数の項目がある場合、`Query` オペレーションは、同じパーティションキーの値を持つすべての項目を返します。レスポンスでは、一致する項目は特定の順序で返されません。
結果整合性の読み込みまたは完全整合性の読み込みを使用して、ローカルセカンダリインデックスのクエリを行うことができます。必要な整合性のタイプを指定するには、`ConsistentRead` オペレーションの `Query` パラメータを使用します。ローカルセカンダリインデックスからの完全整合性の読み込みでは、常に最新の更新された値が返されます。クエリがベーステーブルからさらに属性をフェッチする必要がある場合、それらの属性はインデックスについて整合性があることになります。
**Example**
特定のフォーラムのディスカッションスレッドにあるデータをリクエストする `Query` から返される次のデータを考えてみます。
```
{
"TableName": "Thread",
"IndexName": "LastPostIndex",
"ConsistentRead": false,
"ProjectionExpression": "Subject, LastPostDateTime, Replies, Tags",
"KeyConditionExpression":
"ForumName = :v_forum and LastPostDateTime between :v_start and :v_end",
"ExpressionAttributeValues": {
":v_start": {"S": "2015-08-31T00:00:00.000Z"},
":v_end": {"S": "2015-11-31T00:00:00.000Z"},
":v_forum": {"S": "EC2"}
}
}
```
このクエリでは次のようになっています。
+ DynamoDB は `ForumName` パーティションキーを使用して `LastPostIndex` にアクセスし、「EC2」のインデックス項目を特定します。このキーを持つすべてのインデックス項目が、すばやく取り出せるように隣り合わせに格納されます。
+ このフォーラム内で、DynamoDB はインデックスを使用して、指定された `LastPostDateTime` 条件に一致するキーを検索します。
+ `Replies` 属性はインデックスに射影されているため、DynamoDB は追加でプロビジョニングされたスループットを使用することなく、この属性を取得できます。
+ `Tags` 属性はインデックスに射影されていないため、DynamoDB は `Thread` テーブルにアクセスしてこの属性をフェッチする必要があります。
+ 結果が、`LastPostDateTime` によってソートされ、返されます。インデックスのエントリはまずパーティションキーの値によって、次にソートキーの値によって並べ替えられ、保存される順序で `Query` から返されます （`ScanIndexForward` パラメータを使用すると、結果が降順で返されます）。
ローカルセカンダリインデックスには `Tags` 属性が射影されていないため、DynamoDB は、読み取りキャパシティユニットを追加で使用して、ベーステーブルからこの属性をフェッチする必要があります。このクエリを頻繁に実行する必要がある場合は、`Tags` 属性を `LastPostIndex` に射影して、ベーステーブルからフェッチされないようにする必要があります。ただし、`Tags` 属性をまれにしか使用しない場合は、`Tags` 属性をインデックスに射影するためにストレージを追加することが有効でない可能性があります。
### ローカルセカンダリインデックスのスキャン
`Scan` を使用して、ローカルセカンダリインデックスからすべてのデータを取得できます。リクエストにはベーステーブル名とインデックス名を指定する必要があります。`Scan` では、DynamoDB はインデックスのすべてのデータを読み込み、それをアプリケーションに返します。また、データの一部のみを返し、残りのデータを破棄するようにリクエストすることもできます。これを行うには、`FilterExpression` API の `Scan` パラメータを使用します。詳細については、「[Scan のフィルタ式](Scan.md#Scan.FilterExpression)」を参照してください。
## 項目の書き込みとローカルセカンダリインデックス
DynamoDB によって、すべてのローカルセカンダリインデックスがそれぞれのベーステーブルと自動的に同期されます。アプリケーションがインデックスに直接書き込むことはありません。ただし、DynamoDB でこれらのインデックスがどのように維持されるかを理解することは重要です。
ローカルセカンダリインデックスを作成する場合は、インデックスのソートキーになる属性を指定します。その属性のデータ型も指定します。つまり、ベーステーブルに項目を書き込むとき、その項目にインデックスキー属性が定義されている場合は、その型がインデックスキースキーマのデータ型に一致する必要があります。`LastPostIndex` の場合、インデックス内の `LastPostDateTime` ソートキーは、`String` データ型として定義されています。`Thread` テーブルに項目を追加し、`LastPostDateTime` に対して別のデータ型を指定する場合 (`Number` など)、データ型の不一致により DynamoDB によって `ValidationException` が返されます。
ベーステーブル内の項目とローカルセカンダリインデックス内の項目を 1 対 1 の関係にする必要はありません。この動作は、多くのアプリケーションにとってメリットになります。
多数のローカルセカンダリインデックスがあるテーブルは、インデックス数が少ないテーブルに比べて書き込みアクティビティに多くのコストを要します。詳細については、「[ローカルセカンダリインデックスに対するプロビジョニングされたスループットに関する考慮事項](#LSI.ThroughputConsiderations)」を参照してください。
**重要**
ローカルセカンダリインデックスがあるテーブルには、パーティションキーの値ごとに 10 GB のサイズ制限があります。ローカルセカンダリインデックスがあるテーブルには、1 つのパーティションキー値の合計サイズが 10 GB を超えない限り、任意の数の項目を格納できます。詳細については、「[項目コレクションのサイズ制限](#LSI.ItemCollections.SizeLimit)」を参照してください。
## ローカルセカンダリインデックスに対するプロビジョニングされたスループットに関する考慮事項
DynamoDB にテーブルを作成する場合には、テーブルで予想されるワークロードに応じた読み込み/書き込みキャパシティーユニットをプロビジョニングします。このワークロードには、テーブルのローカルセカンダリインデックスの読み込み/書き込みアクティビティが含まれます。
プロビジョニングされたスループット容量の現在の料金を確認するには、「[Amazon DynamoDB 料金](https://aws.amazon.com/dynamodb/pricing)」を参照してください。
### 読み込みキャパシティユニット
ローカルセカンダリインデックスに対してクエリを実行する場合、使用される読み込みキャパシティーユニットの数は、データのアクセス方法によって異なります。
テーブルに対するクエリと同様に、インデックスクエリでは `ConsistentRead` の値に応じて、結果整合性のある読み込みまたは強力な整合性のある読み込みを実行できます。1 回の強力な整合性のある読み込みでは、1 つの読み込みキャパシティーユニットが消費され、結果整合性のある読み込みではその半分が消費されます。したがって結果整合性のある読み込みを選択することで、読み込みキャパシティーユニットのコストを削減できます。
インデックスキーと射影された属性だけをリクエストするインデックスクエリの場合、DynamoDB はテーブルに対するクエリの場合と同じ方法で、プロビジョニングされた読み込みアクティビティを計算します。唯一の違いは、ベーステーブル内の項目のサイズではなくインデックスエントリのサイズに基づいて計算が行われることです。読み込みキャパシティーユニットの数は、返されたすべての項目について射影されたすべての属性のサイズの合計です。結果は、次の 4 KB 境界まで切り上げられます。DynamoDB がプロビジョニングされたスループットの利用率を計算する方法の詳細については、「[DynamoDB プロビジョンドキャパシティモード](provisioned-capacity-mode.md)」を参照してください。
ローカルセカンダリインデックスに射影されていない属性を読み込むインデックスクエリの場合、DynamoDB は射影された属性をインデックスから読み込むのに加えて、それらの属性をベーステーブルからフェッチする必要があります。これらのフェッチは、`Select` オペレーションの `ProjectionExpression` または `Query` パラメータに、射影されていない属性を含めた場合に実行されます。フェッチによってクエリ応答のレイテンシーが増加し、プロビジョニングされるスループットのコストも増加します。前述のローカルセカンダリインデックスからの読み込みに加えて、フェッチされるベーステーブル項目それぞれについて、読み込みキャパシティーユニットの料金がかかります。この料金は、リクエストした属性だけでなく、項目全体をテーブルから読み込むために発生するものです。
`Query` オペレーションによって返される結果の最大サイズは 1 MB です。これには、返されるすべての項目にわたる、すべての属性の名前と値のサイズが含まれます。ただし、ローカルセカンダリインデックスに対するクエリによって、DynamoDB がベーステーブルから項目の属性をフェッチする場合には、結果で示されるデータの最大サイズが小さくなる可能性があります。この場合、結果のサイズは次の合計になります。
+ インデックス内で一致する項目のサイズ (次の 4 KB に切り上げ)
+ ベーステーブル内で一致する各項目のサイズ (項目ごとに次の 4 KB に切り上げ)
この式を使用すると、クエリオペレーションによって返される結果の最大サイズは依然として 1 MB になります。
たとえば、各項目のサイズが 300 バイトであるテーブルがあるとします。そのテーブルにはローカルセカンダリインデックスがありますが、各項目のうち 200 バイトだけがインデックスに射影されます。このインデックスに対して `Query` を行うときに各項目についてテーブルのフェッチが必要で、クエリによって 4 つの項目が返されるとします。DynamoDB では、次のように合計されます。
+ インデックス内で一致する項目のサイズは 200 バイト × 4 項目 = 800 バイトになり、それが 4 KB に切り上げられます。
+ ベーステーブル内で一致する項目のサイズ: (300 バイト、4 KB に切り上げ) × 4 項目 = 16 KB。
それによって、結果データの合計サイズは 20 KB になります。
### 書き込みキャパシティユニット
テーブル内の項目が追加、更新、または削除された場合にローカルセカンダリインデックスを更新すると、テーブルにプロビジョニングされた書き込みキャパシティーユニットが消費されます。書き込み用にプロビジョニングされたスループットの合計コストは、テーブルに対する書き込みと、ローカルセカンダリインデックスの更新で消費された書き込みキャパシティーユニットの合計になります。
ローカルセカンダリインデックスに項目を書き込むコストは、いくつかの要因に左右されます。
+ インデックス付き属性が定義されたテーブルに新しい項目を書き込む場合、または既存の項目を更新して未定義のインデックス付き属性を定義する場合には、インデックスへの項目の挿入に 1 回の書き込みオペレーションが必要です。
+ テーブルに対する更新によってインデックス付きキー属性の値が（A から B に）変更された場合には、インデックスから既存の項目を削除し、インデックスに新しい項目を挿入するために、2 回の書き込みが必要です。
+ インデックス内に既存の項目があって、テーブルに対する書き込みによってインデックス付き属性が削除された場合は、インデックスから古い項目の射影を削除するために、1 回の書き込みが必要です。
+ 項目の更新の前後にインデックス内に項目が存在しない場合は、インデックスで追加の書き込みコストは発生しません。
これらすべての要因は、インデックス内の各項目のサイズが 1 KB 以下であるという前提で書き込みキャパシティーユニット数を算出します。インデックスエントリがそれよりも大きい場合は、書き込みキャパシティーユニットを追加する必要があります。クエリが返す必要がある属性を特定し、それらの属性だけをインデックスに射影することで、書き込みコストは最小になります。
## ローカルセカンダリインデックスのストレージに関する考慮事項
アプリケーションがテーブルに項目を書き込むと、DynamoDB では正しい属性のサブセットが、それらの属性が表示されるローカルセカンダリインデックスに自動的にコピーされます。AWS アカウントでは、テーブル内の項目のストレージと、そのベーステーブルのローカルセカンダリインデックスにある属性のストレージに対して課金されます。
インデックス項目が使用するスペースの量は、次の量の合計になります。
+ ベーステーブルのプライマリキー (パーティションキーとソートキー) のサイズのバイト数
+ インデックスキー属性のサイズのバイト数
+ 射影された属性（存在する場合）のサイズのバイト数
+ インデックス項目あたり 100 バイトのオーバーヘッド
ローカルセカンダリインデックスに必要なストレージは、インデックス内の 1 項目の平均サイズの見積もり値に、インデックス内の項目数を掛けて見積もることができます。
特定の属性が定義されていない項目がテーブルに含まれており、その属性がインデックスソートキーとして定義されている場合、DynamoDB はその項目に関連するデータをインデックスに書き込みません。
## ローカルセカンダリインデックス内の項目コレクション
**注記**
このセクションは、ローカルセカンダリインデックスがあるテーブルだけに関係します。
DynamoDB において、*項目コレクション*とは、テーブルおよびそのローカルセカンダリインデックス全体で同じパーティションキーの値を持つ項目のグループです。このセクションで使用する例では、`Thread` テーブルのパーティションキーは `ForumName` で、`LastPostIndex` のパーティションキーも `ForumName` です。同じ `ForumName` を持つテーブルとインデックス項目は、すべて同じ項目コレクションの一部です。例えば、`Thread` テーブルと `LastPostIndex` ローカルセカンダリインデックスには、フォーラム `EC2` 用の項目コレクションと、フォーラム `RDS` 用の別の項目コレクションがあります。
次の図は、フォーラム `S3` の項目コレクションを示しています。
![\[テーブル、および同じパーティションキー値 S3 を持つローカルセカンダリインデックスを含む DynamoDB 項目のコレクション。 \]](http://docs.aws.amazon.com/ja_jp/amazondynamodb/latest/developerguide/images/LSI_04.png)
この図では、項目コレクションは、`Thread` および `LastPostIndex` 内のすべての項目で構成されていて、`ForumName` パーティションキーの値は「S3」です。テーブルにその他のローカルセカンダリインデックスがあった場合には、`ForumName` が「S3」であるそれらのインデックス内の項目も、項目コレクションの一部になります。
DynamoDB では次のオペレーションのいずれかを使用して、項目コレクションに関する情報を返すことができます。
+ `BatchWriteItem`
+ `DeleteItem`
+ `PutItem`
+ `UpdateItem`
+ `TransactWriteItems`
これらのオペレーションでは、それぞれ `ReturnItemCollectionMetrics` パラメータがサポートされています。このパラメータを `SIZE` に設定すると、インデックス内の各項目コレクションのサイズに関する情報が表示されます。
**Example**
以下に、`UpdateItem` が `Thread` に設定されている、`ReturnItemCollectionMetrics` テーブルでの `SIZE` オペレーションの出力の例を示します。更新された項目には `ForumName` 値「EC2」があったため、出力にはその項目コレクションに関する情報が含まれています。
```
{
ItemCollectionMetrics: {
ItemCollectionKey: {
ForumName: "EC2"
},
SizeEstimateRangeGB: [0.0, 1.0]
}
}
```
`SizeEstimateRangeGB` オブジェクトは、この項目コレクションのサイズが 0 GB と 1 GB の間であることを示します。DynamoDB では、このサイズ見積りが定期的に更新されるため、項目を変更した時には次回の数字が異なる場合があります。
### 項目コレクションのサイズ制限
1 つ以上のローカルセカンダリインデックスを含む項目コレクションのサイズは、すべて最大 10 GB です。これは、ローカルセカンダリインデックスのないテーブルの項目コレクションには適用されません。また、グローバルセカンダリインデックスの項目コレクションにも適用されません。1 つ以上のローカルセカンダリインデックスを含むテーブルのみに影響します。
項目コレクションが 10 GB の制限を超えると、DynamoDB は `ItemCollectionSizeLimitExceededException` を返す可能性があります。この場合、その項目コレクションに項目を追加したり、項目サイズを大きくしたりすることができなくなる場合があります。（項目コレクションのサイズを小さくする読み込み/書き込みオペレーションは、引き続き実行できます)。その他の項目コレクションには項目を追加することができます。
項目コレクションのサイズを小さくするには、次のいずれかを実行します。
+ 問題になっているパーティションキーの値を持つ不要な項目を削除します。ベーステーブルからこれらの項目を削除すると、DynamoDB では同じパーティションキーの値を持つインデックスエントリも削除されます。
+ 属性を削除するか属性のサイズを小さくすることで、項目を更新します。これらの属性がローカルセカンダリインデックスに射影されている場合には、DynamoDB では対応するインデックスエントリのサイズも小さくなります。
+ 同じパーティションキーおよびソートキーを使用して新しいテーブルを作成し、古いテーブルから新しいテーブルに項目を移動します。これは、頻繁にアクセスされない履歴データがテーブルに含まれている場合に適した方法です。また、この履歴データを Amazon Simple Storage Service (Amazon S3) にアーカイブすることを検討することもできます。
項目コレクションの合計サイズが 10 GB 未満になると、再び同じパーティションキーの値を使用して項目を追加できます。
項目コレクションのサイズを監視するようにアプリケーションを設定することをお勧めします。1 つの方法としては、`ReturnItemCollectionMetrics`、`SIZE`、`BatchWriteItem`、または `DeleteItem` を使用する場合に、`PutItem` パラメータを `UpdateItem` に設定するというものがあります。アプリケーションで出力内の `ReturnItemCollectionMetrics` オブジェクトを調査し、項目コレクションがユーザー定義の制限（たとえば 8 GB）を超えた場合にエラーメッセージを記録するようにします。制限を 10 GB より低く設定すれば早期警告システムになり、項目コレクションが上限に達する前に余裕をもって何らかの対処をとることができます。
### 項目コレクションおよびパーティション
1 つ以上のローカルセカンダリインデックスを含むテーブルでは、各項目コレクションは 1 つのパーティションに保存されます。このような項目コレクションの合計サイズは、そのパーティションのキャパシティー (10 GB) に制限されます。データモデルにサイズに制限のない項目コレクションが含まれている場合や、一部の項目コレクションが将来に 10 GB を超えると合理的に予期されるアプリケーションでは、代わりにグローバルセカンダリインデックスの使用を検討します。
アプリケーションを設計する場合は、テーブルデータが異なるパーティションキー値に均一に分配されるようにする必要があります。ローカルセカンダリインデックス を持つテーブルについては、単一のパーティション内の単一の項目コレクションに読み込み/書き込みアクティビティの「ホットスポット」が作られないように、アプリケーションを設計します。
# ローカルセカンダリインデックスの操作: Java
AWS SDK for Java ドキュメント API を使用して、1 つ以上のローカルセカンダリインデックスを持つ Amazon DynamoDB テーブルを作成し、テーブルのインデックスを記述し、インデックスを使用してクエリを実行できます。
以下に、AWS SDK for Java ドキュメント API を使用したテーブルオペレーションの一般的な手順を示します。
1. `DynamoDB` クラスのインスタンスを作成します。
1. 対応するリクエストオブジェクトを作成して、オペレーションについて必要なパラメータとオプションパラメータを入力します。
1. 前のステップで作成したクライアントが提供する適切なメソッドを呼び出します。
**Topics**
+ [ローカルセカンダリインデックスを持つテーブルを作成する](#LSIJavaDocumentAPI.CreateTableWithIndex)
+ [ローカルセカンダリインデックスを持つテーブルの説明](#LSIJavaDocumentAPI.DescribeTableWithIndex)
+ [ローカルセカンダリインデックスのクエリ](#LSIJavaDocumentAPI.QueryAnIndex)
+ [例: Java ドキュメント API を使用したローカルセカンダリインデックス](LSIJavaDocumentAPI.Example.md)
## ローカルセカンダリインデックスを持つテーブルを作成する
ローカルセカンダリインデックスは、テーブルの作成と同時に作成する必要があります。これを行うには、`createTable` メソッドを使用し、1 つ以上のローカルセカンダリインデックスの仕様を指定します。次の Java コード例では、ミュージックコレクション内の曲に関する情報を保持するためのテーブルを作成しています。パーティションキーは `Artist` で、ソートキーは `SongTitle` です。セカンダリインデックス `AlbumTitleIndex` は、アルバムタイトルによるクエリを容易にします。
DynamoDB ドキュメント API を使用して、ローカルセカンダリインデックスを持つテーブルを作成する手順を次に示します。
1. `DynamoDB` クラスのインスタンスを作成します。
1. リクエスト情報を指定する `CreateTableRequest` クラスのインスタンスを作成します。
テーブル名、プライマリキー、およびプロビジョニングされたスループット値を指定する必要があります。ローカルセカンダリインデックスの場合は、インデックス名、インデックスソートキーの名前とデータ型、インデックスのキースキーマ、および属性射影を指定する必要があります。
1. リクエストオブジェクトをパラメータとして指定して、`createTable` メソッドを呼び出します。
以下の Java コード例は、前述のステップの例です。このコードは、`AlbumTitle` 属性に関するセカンダリインデックスを持つテーブル (`Music`) を作成します。テーブルパーティションキーとソートキー、およびインデックスソートキーのみが、インデックスに射影される属性です。
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
String tableName = "Music";
CreateTableRequest createTableRequest = new CreateTableRequest().withTableName(tableName);
//ProvisionedThroughput
createTableRequest.setProvisionedThroughput(new ProvisionedThroughput().withReadCapacityUnits((long)5).withWriteCapacityUnits((long)5));
//AttributeDefinitions
ArrayList attributeDefinitions= new ArrayList();
attributeDefinitions.add(new AttributeDefinition().withAttributeName("Artist").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("SongTitle").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("AlbumTitle").withAttributeType("S"));
createTableRequest.setAttributeDefinitions(attributeDefinitions);
//KeySchema
ArrayList tableKeySchema = new ArrayList();
tableKeySchema.add(new KeySchemaElement().withAttributeName("Artist").withKeyType(KeyType.HASH)); //Partition key
tableKeySchema.add(new KeySchemaElement().withAttributeName("SongTitle").withKeyType(KeyType.RANGE)); //Sort key
createTableRequest.setKeySchema(tableKeySchema);
ArrayList indexKeySchema = new ArrayList();
indexKeySchema.add(new KeySchemaElement().withAttributeName("Artist").withKeyType(KeyType.HASH)); //Partition key
indexKeySchema.add(new KeySchemaElement().withAttributeName("AlbumTitle").withKeyType(KeyType.RANGE)); //Sort key
Projection projection = new Projection().withProjectionType(ProjectionType.INCLUDE);
ArrayList nonKeyAttributes = new ArrayList();
nonKeyAttributes.add("Genre");
nonKeyAttributes.add("Year");
projection.setNonKeyAttributes(nonKeyAttributes);
LocalSecondaryIndex localSecondaryIndex = new LocalSecondaryIndex()
.withIndexName("AlbumTitleIndex").withKeySchema(indexKeySchema).withProjection(projection);
ArrayList localSecondaryIndexes = new ArrayList();
localSecondaryIndexes.add(localSecondaryIndex);
createTableRequest.setLocalSecondaryIndexes(localSecondaryIndexes);
Table table = dynamoDB.createTable(createTableRequest);
System.out.println(table.getDescription());
```
DynamoDB がテーブルを作成し、テーブルのステータスを `ACTIVE` に設定するまで待機する必要があります。その後、テーブルへのデータ項目の入力を開始できます。
## ローカルセカンダリインデックスを持つテーブルの説明
テーブルのローカルセカンダリインデックスに関する情報を取得するには、`describeTable` メソッドを使用します。インデックスごとに、名前、キースキーマ、および射影された属性にアクセスできます。
AWS SDK for Java ドキュメント API を使用して、テーブルのローカルセカンダリインデックス情報にアクセスするためのステップを次に示します。
1. `DynamoDB` クラスのインスタンスを作成します。
1. `Table` クラスのインスタンスを作成します。テーブル名を入力する必要があります。
1. `Table` オブジェクトの `describeTable` メソッドを呼び出します。
以下の Java コード例は、前述のステップの例です。
**Example**
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
String tableName = "Music";
Table table = dynamoDB.getTable(tableName);
TableDescription tableDescription = table.describe();
List localSecondaryIndexes
= tableDescription.getLocalSecondaryIndexes();
// This code snippet will work for multiple indexes, even though
// there is only one index in this example.
Iterator lsiIter = localSecondaryIndexes.iterator();
while (lsiIter.hasNext()) {
LocalSecondaryIndexDescription lsiDescription = lsiIter.next();
System.out.println("Info for index " + lsiDescription.getIndexName() + ":");
Iterator kseIter = lsiDescription.getKeySchema().iterator();
while (kseIter.hasNext()) {
KeySchemaElement kse = kseIter.next();
System.out.printf("\t%s: %s\n", kse.getAttributeName(), kse.getKeyType());
}
Projection projection = lsiDescription.getProjection();
System.out.println("\tThe projection type is: " + projection.getProjectionType());
if (projection.getProjectionType().toString().equals("INCLUDE")) {
System.out.println("\t\tThe non-key projected attributes are: " + projection.getNonKeyAttributes());
}
}
```
## ローカルセカンダリインデックスのクエリ
テーブルに `Query` を実行するのとほぼ同じ方法で、ローカルセカンダリインデックスに対する `Query` オペレーションを使用することができます。インデックス名、インデックスソートキーのクエリ条件、および返す属性を指定する必要があります。この例では、インデックスは `AlbumTitleIndex`、インデックスソートキーは `AlbumTitle` です。
返される属性は、インデックスに射影された属性だけです。このクエリを変更して非キー属性を選択することもできますが、これには比較的コストのかかるテーブルフェッチアクティビティが必要です。テーブルのフェッチの詳細については、「[属性の射影](LSI.md#LSI.Projections)」を参照してください。
AWS SDK for Java ドキュメント API を使用してローカルセカンダリインデックスをクエリする手順を次に示します。
1. `DynamoDB` クラスのインスタンスを作成します。
1. `Table` クラスのインスタンスを作成します。テーブル名を入力する必要があります。
1. `Index` クラスのインスタンスを作成します。インデックス名を入力する必要があります。
1. `Index` クラスの `query` メソッドを呼び出します。
以下の Java コード例は、前述のステップの例です。
**Example**
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
String tableName = "Music";
Table table = dynamoDB.getTable(tableName);
Index index = table.getIndex("AlbumTitleIndex");
QuerySpec spec = new QuerySpec()
.withKeyConditionExpression("Artist = :v_artist and AlbumTitle = :v_title")
.withValueMap(new ValueMap()
.withString(":v_artist", "Acme Band")
.withString(":v_title", "Songs About Life"));
ItemCollection items = index.query(spec);
Iterator
- itemsIter = items.iterator();
while (itemsIter.hasNext()) {
Item item = itemsIter.next();
System.out.println(item.toJSONPretty());
}
```
### ローカルセカンダリインデックスの整合性のある読み取り
結果整合性のある読み込みのみをサポートするグローバルセカンダリインデックスとは異なり、ローカルセカンダリインデックスは結果整合性のある読み込みと強力な整合性のある読み込みの両方をサポートします。ローカルセカンダリインデックスからの完全整合性の読み込みでは、常に最新の更新された値が返されます。クエリがベーステーブルからさらに属性をフェッチする必要がある場合、それらのフェッチされた属性もインデックスについて整合性があることになります。
デフォルトでは、`Query` は結果整合性のある読み込みを使用します。強力な整合性のある読み込みをリクエストするには、`QuerySpec` で `ConsistentRead` を `true` に設定します。次の例では、強力な整合性のある読み込みを使用して `AlbumTitleIndex` をクエリを実行します。
**Example**
```
QuerySpec spec = new QuerySpec()
.withKeyConditionExpression("Artist = :v_artist and AlbumTitle = :v_title")
.withValueMap(new ValueMap()
.withString(":v_artist", "Acme Band")
.withString(":v_title", "Songs About Life"))
.withConsistentRead(true);
```
**注記**
強力な整合性のある読み込みでは、返されるデータ 4 KB ごとに 1 つの読み込みキャパシティーユニット (切り上げ) が消費されますが、結果整合性のある読み込みではその半分が消費されます。例えば、9 KB のデータを返す強力な整合性のある読み込みでは、3 つの読み込みキャパシティーユニット (9 KB / 4 KB = 2.25、3 に切り上げ) が消費されますが、結果整合性のある読み込みを使用した同じクエリでは、1.5 の読み込みキャパシティーユニットが消費されます。アプリケーションがわずかに古くなる可能性のあるデータの読み取りを許容できる場合は、結果整合性のある読み込みを使用して読み込みキャパシティーの使用量を減らします。詳細については、「[読み込みキャパシティユニット](LSI.md#LSI.ThroughputConsiderations.Reads)」を参照してください。
# 例: Java ドキュメント API を使用したローカルセカンダリインデックス
次の Java コード例は、Amazon DynamoDB でローカルセカンダリインデックスを操作する方法を示しています。この例では、パーティションキーを `CustomerId` として 、ソートキーを `OrderId` として `CustomerOrders` という名前のテーブルを作成しています。このテーブルには、次の 2 つのローカルセカンダリインデックスがあります。
+ `OrderCreationDateIndex` – ソートキーは `OrderCreationDate` です。次の属性がインデックスに射影されます。
+ `ProductCategory`
+ `ProductName`
+ `OrderStatus`
+ `ShipmentTrackingId`
+ `IsOpenIndex` – ソートキーは `IsOpen` です。すべてのテーブル属性がインデックスに射影されます。
`CustomerOrders` テーブルが作成されると、プログラムは顧客の注文を表すデータをテーブルにロードします。次に、ローカルセカンダリインデックスを使用してデータにクエリを実行します。最後に、プログラムは `CustomerOrders` テーブルを削除します。
以下の例をテストするための詳細な手順については、「[Java コードの例](CodeSamples.Java.md)」を参照してください。
**Example**
```
package com.example.dynamodb;
import software.amazon.awssdk.core.waiters.WaiterResponse;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.*;
import software.amazon.awssdk.services.dynamodb.waiters.DynamoDbWaiter;
import java.util.HashMap;
import java.util.Map;
public class DocumentAPILocalSecondaryIndexExample {
static DynamoDbClient client = DynamoDbClient.create();
public static String tableName = "CustomerOrders";
public static void main(String[] args) {
createTable();
loadData();
query(null);
query("IsOpenIndex");
query("OrderCreationDateIndex");
deleteTable(tableName);
}
public static void createTable() {
CreateTableRequest request = CreateTableRequest.builder()
.tableName(tableName)
.provisionedThroughput(ProvisionedThroughput.builder()
.readCapacityUnits(1L)
.writeCapacityUnits(1L)
.build())
.attributeDefinitions(
AttributeDefinition.builder().attributeName("CustomerId").attributeType(ScalarAttributeType.S).build(),
AttributeDefinition.builder().attributeName("OrderId").attributeType(ScalarAttributeType.N).build(),
AttributeDefinition.builder().attributeName("OrderCreationDate").attributeType(ScalarAttributeType.N).build(),
AttributeDefinition.builder().attributeName("IsOpen").attributeType(ScalarAttributeType.N).build())
.keySchema(
KeySchemaElement.builder().attributeName("CustomerId").keyType(KeyType.HASH).build(),
KeySchemaElement.builder().attributeName("OrderId").keyType(KeyType.RANGE).build())
.localSecondaryIndexes(
LocalSecondaryIndex.builder()
.indexName("OrderCreationDateIndex")
.keySchema(
KeySchemaElement.builder().attributeName("CustomerId").keyType(KeyType.HASH).build(),
KeySchemaElement.builder().attributeName("OrderCreationDate").keyType(KeyType.RANGE).build())
.projection(Projection.builder()
.projectionType(ProjectionType.INCLUDE)
.nonKeyAttributes("ProductCategory", "ProductName")
.build())
.build(),
LocalSecondaryIndex.builder()
.indexName("IsOpenIndex")
.keySchema(
KeySchemaElement.builder().attributeName("CustomerId").keyType(KeyType.HASH).build(),
KeySchemaElement.builder().attributeName("IsOpen").keyType(KeyType.RANGE).build())
.projection(Projection.builder()
.projectionType(ProjectionType.ALL)
.build())
.build())
.build();
System.out.println("Creating table " + tableName + "...");
client.createTable(request);
try (DynamoDbWaiter waiter = client.waiter()) {
WaiterResponse response = waiter.waitUntilTableExists(r -> r.tableName(tableName));
response.matched().response().ifPresent(System.out::println);
}
}
public static void query(String indexName) {
System.out.println("\n***********************************************************\n");
System.out.println("Querying table " + tableName + "...");
if ("IsOpenIndex".equals(indexName)) {
System.out.println("\nUsing index: '" + indexName + "': Bob's orders that are open.");
System.out.println("Only a user-specified list of attributes are returned\n");
Map values = new HashMap<>();
values.put(":v_custid", AttributeValue.builder().s("bob@example.com").build());
values.put(":v_isopen", AttributeValue.builder().n("1").build());
QueryRequest request = QueryRequest.builder()
.tableName(tableName)
.indexName(indexName)
.keyConditionExpression("CustomerId = :v_custid and IsOpen = :v_isopen")
.expressionAttributeValues(values)
.projectionExpression("OrderCreationDate, ProductCategory, ProductName, OrderStatus")
.build();
System.out.println("Query: printing results...");
client.query(request).items().forEach(System.out::println);
} else if ("OrderCreationDateIndex".equals(indexName)) {
System.out.println("\nUsing index: '" + indexName + "': Bob's orders that were placed after 01/31/2015.");
System.out.println("Only the projected attributes are returned\n");
Map values = new HashMap<>();
values.put(":v_custid", AttributeValue.builder().s("bob@example.com").build());
values.put(":v_orddate", AttributeValue.builder().n("20150131").build());
QueryRequest request = QueryRequest.builder()
.tableName(tableName)
.indexName(indexName)
.keyConditionExpression("CustomerId = :v_custid and OrderCreationDate >= :v_orddate")
.expressionAttributeValues(values)
.select(Select.ALL_PROJECTED_ATTRIBUTES)
.build();
System.out.println("Query: printing results...");
client.query(request).items().forEach(System.out::println);
} else {
System.out.println("\nNo index: All of Bob's orders, by OrderId:\n");
Map values = new HashMap<>();
values.put(":v_custid", AttributeValue.builder().s("bob@example.com").build());
QueryRequest request = QueryRequest.builder()
.tableName(tableName)
.keyConditionExpression("CustomerId = :v_custid")
.expressionAttributeValues(values)
.build();
System.out.println("Query: printing results...");
client.query(request).items().forEach(System.out::println);
}
}
public static void deleteTable(String tableName) {
System.out.println("Deleting table " + tableName + "...");
client.deleteTable(DeleteTableRequest.builder().tableName(tableName).build());
try (DynamoDbWaiter waiter = client.waiter()) {
waiter.waitUntilTableNotExists(r -> r.tableName(tableName));
}
}
public static void loadData() {
System.out.println("Loading data into table " + tableName + "...");
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("alice@example.com").build(),
"OrderId", AttributeValue.builder().n("1").build(),
"IsOpen", AttributeValue.builder().n("1").build(),
"OrderCreationDate", AttributeValue.builder().n("20150101").build(),
"ProductCategory", AttributeValue.builder().s("Book").build(),
"ProductName", AttributeValue.builder().s("The Great Outdoors").build(),
"OrderStatus", AttributeValue.builder().s("PACKING ITEMS").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("alice@example.com").build(),
"OrderId", AttributeValue.builder().n("2").build(),
"IsOpen", AttributeValue.builder().n("1").build(),
"OrderCreationDate", AttributeValue.builder().n("20150221").build(),
"ProductCategory", AttributeValue.builder().s("Bike").build(),
"ProductName", AttributeValue.builder().s("Super Mountain").build(),
"OrderStatus", AttributeValue.builder().s("ORDER RECEIVED").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("alice@example.com").build(),
"OrderId", AttributeValue.builder().n("3").build(),
"OrderCreationDate", AttributeValue.builder().n("20150304").build(),
"ProductCategory", AttributeValue.builder().s("Music").build(),
"ProductName", AttributeValue.builder().s("A Quiet Interlude").build(),
"OrderStatus", AttributeValue.builder().s("IN TRANSIT").build(),
"ShipmentTrackingId", AttributeValue.builder().s("176493").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("1").build(),
"OrderCreationDate", AttributeValue.builder().n("20150111").build(),
"ProductCategory", AttributeValue.builder().s("Movie").build(),
"ProductName", AttributeValue.builder().s("Calm Before The Storm").build(),
"OrderStatus", AttributeValue.builder().s("SHIPPING DELAY").build(),
"ShipmentTrackingId", AttributeValue.builder().s("859323").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("2").build(),
"OrderCreationDate", AttributeValue.builder().n("20150124").build(),
"ProductCategory", AttributeValue.builder().s("Music").build(),
"ProductName", AttributeValue.builder().s("E-Z Listening").build(),
"OrderStatus", AttributeValue.builder().s("DELIVERED").build(),
"ShipmentTrackingId", AttributeValue.builder().s("756943").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("3").build(),
"OrderCreationDate", AttributeValue.builder().n("20150221").build(),
"ProductCategory", AttributeValue.builder().s("Music").build(),
"ProductName", AttributeValue.builder().s("Symphony 9").build(),
"OrderStatus", AttributeValue.builder().s("DELIVERED").build(),
"ShipmentTrackingId", AttributeValue.builder().s("645193").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("4").build(),
"IsOpen", AttributeValue.builder().n("1").build(),
"OrderCreationDate", AttributeValue.builder().n("20150222").build(),
"ProductCategory", AttributeValue.builder().s("Hardware").build(),
"ProductName", AttributeValue.builder().s("Extra Heavy Hammer").build(),
"OrderStatus", AttributeValue.builder().s("PACKING ITEMS").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("5").build(),
"OrderCreationDate", AttributeValue.builder().n("20150309").build(),
"ProductCategory", AttributeValue.builder().s("Book").build(),
"ProductName", AttributeValue.builder().s("How To Cook").build(),
"OrderStatus", AttributeValue.builder().s("IN TRANSIT").build(),
"ShipmentTrackingId", AttributeValue.builder().s("440185").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("6").build(),
"OrderCreationDate", AttributeValue.builder().n("20150318").build(),
"ProductCategory", AttributeValue.builder().s("Luggage").build(),
"ProductName", AttributeValue.builder().s("Really Big Suitcase").build(),
"OrderStatus", AttributeValue.builder().s("DELIVERED").build(),
"ShipmentTrackingId", AttributeValue.builder().s("893927").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("7").build(),
"OrderCreationDate", AttributeValue.builder().n("20150324").build(),
"ProductCategory", AttributeValue.builder().s("Golf").build(),
"ProductName", AttributeValue.builder().s("PGA Pro II").build(),
"OrderStatus", AttributeValue.builder().s("OUT FOR DELIVERY").build(),
"ShipmentTrackingId", AttributeValue.builder().s("383283").build()));
}
private static void putItem(Map item) {
client.putItem(PutItemRequest.builder().tableName(tableName).item(item).build());
}
}
```
# ローカルセカンダリインデックスの操作: .NET
**Topics**
+ [ローカルセカンダリインデックスを持つテーブルを作成する](#LSILowLevelDotNet.CreateTableWithIndex)
+ [ローカルセカンダリインデックスを持つテーブルの説明](#LSILowLevelDotNet.DescribeTableWithIndex)
+ [ローカルセカンダリインデックスのクエリ](#LSILowLevelDotNet.QueryAnIndex)
+ [例: AWS SDK for .NET 低レベル API を使用したローカルセカンダリインデックス](LSILowLevelDotNet.Example.md)
AWS SDK for .NET 低レベル API を使用して、1 つ以上のローカルセカンダリインデックスを含む Amazon DynamoDB テーブルを作成し、テーブルのインデックスを記述し、インデックスを使用してクエリを実行できます。これらのオペレーションは、対応する低レベル DynamoDB API アクションにマッピングされます。詳細については、「[.NET コード例](CodeSamples.DotNet.md)」を参照してください。
以下に、.NET 低レベル API を使用したテーブルオペレーションの一般的な手順を示します。
1. `AmazonDynamoDBClient` クラスのインスタンスを作成します。
1. 対応するリクエストオブジェクトを作成して、オペレーションについて必要なパラメータとオプションパラメータを入力します。
例えば、テーブルを作成するには `CreateTableRequest` オブジェクトを作成し、テーブルやインデックスにクエリを実行するには `QueryRequest` オブジェクトを作成します。
1. 前述のステップで作成したクライアントから提供された適切なメソッドを実行します。
## ローカルセカンダリインデックスを持つテーブルを作成する
ローカルセカンダリインデックスは、テーブルの作成と同時に作成する必要があります。これを行うには、`CreateTable` を使用し、1 つ以上のローカルセカンダリインデックスの仕様を指定します。次の C\$1 コード例では、ミュージックコレクション内の曲に関する情報を保持するためのテーブルを作成しています。パーティションキーは `Artist` で、ソートキーは `SongTitle` です。セカンダリインデックス `AlbumTitleIndex` は、アルバムタイトルによるクエリを容易にします。
.NET 低レベル API を使用して、ローカルセカンダリインデックスを含むテーブルを作成する手順を次に示します。
1. `AmazonDynamoDBClient` クラスのインスタンスを作成します。
1. リクエスト情報を指定する `CreateTableRequest` クラスのインスタンスを作成します。
テーブル名、プライマリキー、およびプロビジョニングされたスループット値を指定する必要があります。ローカルセカンダリインデックスの場合は、インデックス名、インデックスソートキーの名前とデータ型、インデックスのキースキーマ、および属性射影を指定する必要があります。
1. リクエストオブジェクトをパラメータとして指定して、`CreateTable` メソッドを実行します。
以下の C\$1 サンプルコードは、前述のステップの例です。このコードは、`AlbumTitle` 属性に関するセカンダリインデックスを持つテーブル (`Music`) を作成します。テーブルパーティションキーとソートキー、およびインデックスソートキーのみが、インデックスに射影される属性です。
```
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
string tableName = "Music";
CreateTableRequest createTableRequest = new CreateTableRequest()
{
TableName = tableName
};
//ProvisionedThroughput
createTableRequest.ProvisionedThroughput = new ProvisionedThroughput()
{
ReadCapacityUnits = (long)5,
WriteCapacityUnits = (long)5
};
//AttributeDefinitions
List attributeDefinitions = new List();
attributeDefinitions.Add(new AttributeDefinition()
{
AttributeName = "Artist",
AttributeType = "S"
});
attributeDefinitions.Add(new AttributeDefinition()
{
AttributeName = "SongTitle",
AttributeType = "S"
});
attributeDefinitions.Add(new AttributeDefinition()
{
AttributeName = "AlbumTitle",
AttributeType = "S"
});
createTableRequest.AttributeDefinitions = attributeDefinitions;
//KeySchema
List tableKeySchema = new List();
tableKeySchema.Add(new KeySchemaElement() { AttributeName = "Artist", KeyType = "HASH" }); //Partition key
tableKeySchema.Add(new KeySchemaElement() { AttributeName = "SongTitle", KeyType = "RANGE" }); //Sort key
createTableRequest.KeySchema = tableKeySchema;
List indexKeySchema = new List();
indexKeySchema.Add(new KeySchemaElement() { AttributeName = "Artist", KeyType = "HASH" }); //Partition key
indexKeySchema.Add(new KeySchemaElement() { AttributeName = "AlbumTitle", KeyType = "RANGE" }); //Sort key
Projection projection = new Projection() { ProjectionType = "INCLUDE" };
List nonKeyAttributes = new List();
nonKeyAttributes.Add("Genre");
nonKeyAttributes.Add("Year");
projection.NonKeyAttributes = nonKeyAttributes;
LocalSecondaryIndex localSecondaryIndex = new LocalSecondaryIndex()
{
IndexName = "AlbumTitleIndex",
KeySchema = indexKeySchema,
Projection = projection
};
List localSecondaryIndexes = new List();
localSecondaryIndexes.Add(localSecondaryIndex);
createTableRequest.LocalSecondaryIndexes = localSecondaryIndexes;
CreateTableResponse result = client.CreateTable(createTableRequest);
Console.WriteLine(result.CreateTableResult.TableDescription.TableName);
Console.WriteLine(result.CreateTableResult.TableDescription.TableStatus);
```
DynamoDB がテーブルを作成し、テーブルのステータスを `ACTIVE` に設定するまで待機する必要があります。その後、テーブルへのデータ項目の入力を開始できます。
## ローカルセカンダリインデックスを持つテーブルの説明
テーブルのローカルセカンダリインデックスに関する情報を取得するには、`DescribeTable` API を使用します。インデックスごとに、名前、キースキーマ、および射影された属性にアクセスできます。
.NET 低レベル API を使用してテーブルのローカルセカンダリインデックス情報にアクセスするには次の手順に従います。
1. `AmazonDynamoDBClient` クラスのインスタンスを作成します。
1. リクエスト情報を指定する `DescribeTableRequest` クラスのインスタンスを作成します。テーブル名を入力する必要があります。
1. リクエストオブジェクトをパラメータとして指定して、`describeTable` メソッドを実行します。
以下の C\$1 サンプルコードは、前述のステップの例です。
**Example**
```
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
string tableName = "Music";
DescribeTableResponse response = client.DescribeTable(new DescribeTableRequest() { TableName = tableName });
List localSecondaryIndexes =
response.DescribeTableResult.Table.LocalSecondaryIndexes;
// This code snippet will work for multiple indexes, even though
// there is only one index in this example.
foreach (LocalSecondaryIndexDescription lsiDescription in localSecondaryIndexes)
{
Console.WriteLine("Info for index " + lsiDescription.IndexName + ":");
foreach (KeySchemaElement kse in lsiDescription.KeySchema)
{
Console.WriteLine("\t" + kse.AttributeName + ": key type is " + kse.KeyType);
}
Projection projection = lsiDescription.Projection;
Console.WriteLine("\tThe projection type is: " + projection.ProjectionType);
if (projection.ProjectionType.ToString().Equals("INCLUDE"))
{
Console.WriteLine("\t\tThe non-key projected attributes are:");
foreach (String s in projection.NonKeyAttributes)
{
Console.WriteLine("\t\t" + s);
}
}
}
```
## ローカルセカンダリインデックスのクエリ
テーブルに `Query` を実行するのとほぼ同じ方法で、ローカルセカンダリインデックスに対する `Query` を使用することができます。インデックス名、インデックスソートキーのクエリ条件、および返す属性を指定する必要があります。この例では、インデックスは `AlbumTitleIndex`、インデックスソートキーは `AlbumTitle` です。
返される属性は、インデックスに射影された属性だけです。このクエリを変更して非キー属性を選択することもできますが、これには比較的コストのかかるテーブルフェッチアクティビティが必要です。テーブルのフェッチの詳細については、「[属性の射影](LSI.md#LSI.Projections)」を参照してください。
.NET 低レベル API を使用して、ローカルセカンダリインデックスを含むテーブルにクエリを実行する手順を次に示します。
1. `AmazonDynamoDBClient` クラスのインスタンスを作成します。
1. リクエスト情報を指定する `QueryRequest` クラスのインスタンスを作成します。
1. リクエストオブジェクトをパラメータとして指定して、`query` メソッドを実行します。
以下の C\$1 サンプルコードは、前述のステップの例です。
**Example**
```
QueryRequest queryRequest = new QueryRequest
{
TableName = "Music",
IndexName = "AlbumTitleIndex",
Select = "ALL_ATTRIBUTES",
ScanIndexForward = true,
KeyConditionExpression = "Artist = :v_artist and AlbumTitle = :v_title",
ExpressionAttributeValues = new Dictionary()
{
{":v_artist",new AttributeValue {S = "Acme Band"}},
{":v_title",new AttributeValue {S = "Songs About Life"}}
},
};
QueryResponse response = client.Query(queryRequest);
foreach (var attribs in response.Items)
{
foreach (var attrib in attribs)
{
Console.WriteLine(attrib.Key + " ---> " + attrib.Value.S);
}
Console.WriteLine();
}
```
# 例: AWS SDK for .NET 低レベル API を使用したローカルセカンダリインデックス
次の C\$1 コード例は、Amazon DynamoDB でローカルセカンダリインデックスを操作する方法を示しています。この例では、パーティションキーを `CustomerId` として 、ソートキーを `OrderId` として `CustomerOrders` という名前のテーブルを作成しています。このテーブルには、次の 2 つのローカルセカンダリインデックスがあります。
+ `OrderCreationDateIndex` – ソートキーは `OrderCreationDate` です。次の属性がインデックスに射影されます。
+ `ProductCategory`
+ `ProductName`
+ `OrderStatus`
+ `ShipmentTrackingId`
+ `IsOpenIndex` – ソートキーは `IsOpen` です。すべてのテーブル属性がインデックスに射影されます。
`CustomerOrders` テーブルが作成されると、プログラムは顧客の注文を表すデータをテーブルにロードします。次に、ローカルセカンダリインデックスを使用してデータにクエリを実行します。最後に、プログラムは `CustomerOrders` テーブルを削除します。
以下の例をテストするための詳細な手順については、「[.NET コード例](CodeSamples.DotNet.md)」を参照してください。
**Example**
```
using System;
using System.Collections.Generic;
using System.Linq;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DataModel;
using Amazon.DynamoDBv2.DocumentModel;
using Amazon.DynamoDBv2.Model;
using Amazon.Runtime;
using Amazon.SecurityToken;
namespace com.amazonaws.codesamples
{
class LowLevelLocalSecondaryIndexExample
{
private static AmazonDynamoDBClient client = new AmazonDynamoDBClient();
private static string tableName = "CustomerOrders";
static void Main(string[] args)
{
try
{
CreateTable();
LoadData();
Query(null);
Query("IsOpenIndex");
Query("OrderCreationDateIndex");
DeleteTable(tableName);
Console.WriteLine("To continue, press Enter");
Console.ReadLine();
}
catch (AmazonDynamoDBException e) { Console.WriteLine(e.Message); }
catch (AmazonServiceException e) { Console.WriteLine(e.Message); }
catch (Exception e) { Console.WriteLine(e.Message); }
}
private static void CreateTable()
{
var createTableRequest =
new CreateTableRequest()
{
TableName = tableName,
ProvisionedThroughput =
new ProvisionedThroughput()
{
ReadCapacityUnits = (long)1,
WriteCapacityUnits = (long)1
}
};
var attributeDefinitions = new List()
{
// Attribute definitions for table primary key
{ new AttributeDefinition() {
AttributeName = "CustomerId", AttributeType = "S"
} },
{ new AttributeDefinition() {
AttributeName = "OrderId", AttributeType = "N"
} },
// Attribute definitions for index primary key
{ new AttributeDefinition() {
AttributeName = "OrderCreationDate", AttributeType = "N"
} },
{ new AttributeDefinition() {
AttributeName = "IsOpen", AttributeType = "N"
}}
};
createTableRequest.AttributeDefinitions = attributeDefinitions;
// Key schema for table
var tableKeySchema = new List()
{
{ new KeySchemaElement() {
AttributeName = "CustomerId", KeyType = "HASH"
} }, //Partition key
{ new KeySchemaElement() {
AttributeName = "OrderId", KeyType = "RANGE"
} } //Sort key
};
createTableRequest.KeySchema = tableKeySchema;
var localSecondaryIndexes = new List();
// OrderCreationDateIndex
LocalSecondaryIndex orderCreationDateIndex = new LocalSecondaryIndex()
{
IndexName = "OrderCreationDateIndex"
};
// Key schema for OrderCreationDateIndex
var indexKeySchema = new List()
{
{ new KeySchemaElement() {
AttributeName = "CustomerId", KeyType = "HASH"
} }, //Partition key
{ new KeySchemaElement() {
AttributeName = "OrderCreationDate", KeyType = "RANGE"
} } //Sort key
};
orderCreationDateIndex.KeySchema = indexKeySchema;
// Projection (with list of projected attributes) for
// OrderCreationDateIndex
var projection = new Projection()
{
ProjectionType = "INCLUDE"
};
var nonKeyAttributes = new List()
{
"ProductCategory",
"ProductName"
};
projection.NonKeyAttributes = nonKeyAttributes;
orderCreationDateIndex.Projection = projection;
localSecondaryIndexes.Add(orderCreationDateIndex);
// IsOpenIndex
LocalSecondaryIndex isOpenIndex
= new LocalSecondaryIndex()
{
IndexName = "IsOpenIndex"
};
// Key schema for IsOpenIndex
indexKeySchema = new List()
{
{ new KeySchemaElement() {
AttributeName = "CustomerId", KeyType = "HASH"
}}, //Partition key
{ new KeySchemaElement() {
AttributeName = "IsOpen", KeyType = "RANGE"
}} //Sort key
};
// Projection (all attributes) for IsOpenIndex
projection = new Projection()
{
ProjectionType = "ALL"
};
isOpenIndex.KeySchema = indexKeySchema;
isOpenIndex.Projection = projection;
localSecondaryIndexes.Add(isOpenIndex);
// Add index definitions to CreateTable request
createTableRequest.LocalSecondaryIndexes = localSecondaryIndexes;
Console.WriteLine("Creating table " + tableName + "...");
client.CreateTable(createTableRequest);
WaitUntilTableReady(tableName);
}
public static void Query(string indexName)
{
Console.WriteLine("\n***********************************************************\n");
Console.WriteLine("Querying table " + tableName + "...");
QueryRequest queryRequest = new QueryRequest()
{
TableName = tableName,
ConsistentRead = true,
ScanIndexForward = true,
ReturnConsumedCapacity = "TOTAL"
};
String keyConditionExpression = "CustomerId = :v_customerId";
Dictionary expressionAttributeValues = new Dictionary {
{":v_customerId", new AttributeValue {
S = "bob@example.com"
}}
};
if (indexName == "IsOpenIndex")
{
Console.WriteLine("\nUsing index: '" + indexName
+ "': Bob's orders that are open.");
Console.WriteLine("Only a user-specified list of attributes are returned\n");
queryRequest.IndexName = indexName;
keyConditionExpression += " and IsOpen = :v_isOpen";
expressionAttributeValues.Add(":v_isOpen", new AttributeValue
{
N = "1"
});
// ProjectionExpression
queryRequest.ProjectionExpression = "OrderCreationDate, ProductCategory, ProductName, OrderStatus";
}
else if (indexName == "OrderCreationDateIndex")
{
Console.WriteLine("\nUsing index: '" + indexName
+ "': Bob's orders that were placed after 01/31/2013.");
Console.WriteLine("Only the projected attributes are returned\n");
queryRequest.IndexName = indexName;
keyConditionExpression += " and OrderCreationDate > :v_Date";
expressionAttributeValues.Add(":v_Date", new AttributeValue
{
N = "20130131"
});
// Select
queryRequest.Select = "ALL_PROJECTED_ATTRIBUTES";
}
else
{
Console.WriteLine("\nNo index: All of Bob's orders, by OrderId:\n");
}
queryRequest.KeyConditionExpression = keyConditionExpression;
queryRequest.ExpressionAttributeValues = expressionAttributeValues;
var result = client.Query(queryRequest);
var items = result.Items;
foreach (var currentItem in items)
{
foreach (string attr in currentItem.Keys)
{
if (attr == "OrderId" || attr == "IsOpen"
|| attr == "OrderCreationDate")
{
Console.WriteLine(attr + "---> " + currentItem[attr].N);
}
else
{
Console.WriteLine(attr + "---> " + currentItem[attr].S);
}
}
Console.WriteLine();
}
Console.WriteLine("\nConsumed capacity: " + result.ConsumedCapacity.CapacityUnits + "\n");
}
private static void DeleteTable(string tableName)
{
Console.WriteLine("Deleting table " + tableName + "...");
client.DeleteTable(new DeleteTableRequest()
{
TableName = tableName
});
WaitForTableToBeDeleted(tableName);
}
public static void LoadData()
{
Console.WriteLine("Loading data into table " + tableName + "...");
Dictionary item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "alice@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "1"
};
item["IsOpen"] = new AttributeValue
{
N = "1"
};
item["OrderCreationDate"] = new AttributeValue
{
N = "20130101"
};
item["ProductCategory"] = new AttributeValue
{
S = "Book"
};
item["ProductName"] = new AttributeValue
{
S = "The Great Outdoors"
};
item["OrderStatus"] = new AttributeValue
{
S = "PACKING ITEMS"
};
/* no ShipmentTrackingId attribute */
PutItemRequest putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "alice@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "2"
};
item["IsOpen"] = new AttributeValue
{
N = "1"
};
item["OrderCreationDate"] = new AttributeValue
{
N = "20130221"
};
item["ProductCategory"] = new AttributeValue
{
S = "Bike"
};
item["ProductName"] = new AttributeValue
{
S = "Super Mountain"
};
item["OrderStatus"] = new AttributeValue
{
S = "ORDER RECEIVED"
};
/* no ShipmentTrackingId attribute */
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "alice@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "3"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130304"
};
item["ProductCategory"] = new AttributeValue
{
S = "Music"
};
item["ProductName"] = new AttributeValue
{
S = "A Quiet Interlude"
};
item["OrderStatus"] = new AttributeValue
{
S = "IN TRANSIT"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "176493"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "1"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130111"
};
item["ProductCategory"] = new AttributeValue
{
S = "Movie"
};
item["ProductName"] = new AttributeValue
{
S = "Calm Before The Storm"
};
item["OrderStatus"] = new AttributeValue
{
S = "SHIPPING DELAY"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "859323"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "2"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130124"
};
item["ProductCategory"] = new AttributeValue
{
S = "Music"
};
item["ProductName"] = new AttributeValue
{
S = "E-Z Listening"
};
item["OrderStatus"] = new AttributeValue
{
S = "DELIVERED"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "756943"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "3"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130221"
};
item["ProductCategory"] = new AttributeValue
{
S = "Music"
};
item["ProductName"] = new AttributeValue
{
S = "Symphony 9"
};
item["OrderStatus"] = new AttributeValue
{
S = "DELIVERED"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "645193"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "4"
};
item["IsOpen"] = new AttributeValue
{
N = "1"
};
item["OrderCreationDate"] = new AttributeValue
{
N = "20130222"
};
item["ProductCategory"] = new AttributeValue
{
S = "Hardware"
};
item["ProductName"] = new AttributeValue
{
S = "Extra Heavy Hammer"
};
item["OrderStatus"] = new AttributeValue
{
S = "PACKING ITEMS"
};
/* no ShipmentTrackingId attribute */
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "5"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130309"
};
item["ProductCategory"] = new AttributeValue
{
S = "Book"
};
item["ProductName"] = new AttributeValue
{
S = "How To Cook"
};
item["OrderStatus"] = new AttributeValue
{
S = "IN TRANSIT"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "440185"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "6"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130318"
};
item["ProductCategory"] = new AttributeValue
{
S = "Luggage"
};
item["ProductName"] = new AttributeValue
{
S = "Really Big Suitcase"
};
item["OrderStatus"] = new AttributeValue
{
S = "DELIVERED"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "893927"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "7"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130324"
};
item["ProductCategory"] = new AttributeValue
{
S = "Golf"
};
item["ProductName"] = new AttributeValue
{
S = "PGA Pro II"
};
item["OrderStatus"] = new AttributeValue
{
S = "OUT FOR DELIVERY"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "383283"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
}
private static void WaitUntilTableReady(string tableName)
{
string status = null;
// Let us wait until table is created. Call DescribeTable.
do
{
System.Threading.Thread.Sleep(5000); // Wait 5 seconds.
try
{
var res = client.DescribeTable(new DescribeTableRequest
{
TableName = tableName
});
Console.WriteLine("Table name: {0}, status: {1}",
res.Table.TableName,
res.Table.TableStatus);
status = res.Table.TableStatus;
}
catch (ResourceNotFoundException)
{
// DescribeTable is eventually consistent. So you might
// get resource not found. So we handle the potential exception.
}
} while (status != "ACTIVE");
}
private static void WaitForTableToBeDeleted(string tableName)
{
bool tablePresent = true;
while (tablePresent)
{
System.Threading.Thread.Sleep(5000); // Wait 5 seconds.
try
{
var res = client.DescribeTable(new DescribeTableRequest
{
TableName = tableName
});
Console.WriteLine("Table name: {0}, status: {1}",
res.Table.TableName,
res.Table.TableStatus);
}
catch (ResourceNotFoundException)
{
tablePresent = false;
}
}
}
}
}
```
# DynamoDB AWS CLI でのローカルセカンダリインデックスの操作
AWS CLI を使用して、1 つ以上のローカルセカンダリインデックスを含む Amazon DynamoDB テーブルを作成し、テーブルのインデックスを記述し、インデックスを使用してクエリを実行できます。
**Topics**
+ [ローカルセカンダリインデックスを持つテーブルを作成する](#LCICli.CreateTableWithIndex)
+ [ローカルセカンダリインデックスを持つテーブルの説明](#LCICli.DescribeTableWithIndex)
+ [ローカルセカンダリインデックスのクエリ](#LCICli.QueryAnIndex)
## ローカルセカンダリインデックスを持つテーブルを作成する
ローカルセカンダリインデックスは、テーブルの作成と同時に作成する必要があります。これを行うには、`create-table` パラメータを使用し、1 つ以上のローカルセカンダリインデックスの仕様を指定します。次の例では、ミュージックコレクション内の曲に関する情報を保持するためのテーブル (`Music`) を作成しています。パーティションキーは `Artist` で、ソートキーは `SongTitle` です。`AlbumTitle` 属性に関するセカンダリインデックス `AlbumTitleIndex` は、アルバムタイトルによるクエリを容易にします。
```
aws dynamodb create-table \
--table-name Music \
--attribute-definitions AttributeName=Artist,AttributeType=S AttributeName=SongTitle,AttributeType=S \
AttributeName=AlbumTitle,AttributeType=S \
--key-schema AttributeName=Artist,KeyType=HASH AttributeName=SongTitle,KeyType=RANGE \
--provisioned-throughput \
ReadCapacityUnits=10,WriteCapacityUnits=5 \
--local-secondary-indexes \
"[{\"IndexName\": \"AlbumTitleIndex\",
\"KeySchema\":[{\"AttributeName\":\"Artist\",\"KeyType\":\"HASH\"},
{\"AttributeName\":\"AlbumTitle\",\"KeyType\":\"RANGE\"}],
\"Projection\":{\"ProjectionType\":\"INCLUDE\", \"NonKeyAttributes\":[\"Genre\", \"Year\"]}}]"
```
DynamoDB がテーブルを作成し、テーブルのステータスを `ACTIVE` に設定するまで待機する必要があります。その後、テーブルへのデータ項目の入力を開始できます。[describe-table](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/describe-table.html) を使用して、テーブル作成のステータスを判断できます。
## ローカルセカンダリインデックスを持つテーブルの説明
テーブルのローカルセカンダリインデックスに関する情報を取得するには、`describe-table` パラメータを使用します。インデックスごとに、名前、キースキーマ、および射影された属性にアクセスできます。
```
aws dynamodb describe-table --table-name Music
```
## ローカルセカンダリインデックスのクエリ
テーブルに `query` を実行するのとほぼ同じ方法で、ローカルセカンダリインデックスに対する `query` オペレーションを使用することができます。インデックス名、インデックスソートキーのクエリ条件、および返す属性を指定する必要があります。この例では、インデックスは `AlbumTitleIndex`、インデックスソートキーは `AlbumTitle` です。
返される属性は、インデックスに射影された属性だけです。このクエリを変更して非キー属性を選択することもできますが、これには比較的コストのかかるテーブルフェッチアクティビティが必要です。テーブルのフェッチの詳細については、「[属性の射影](LSI.md#LSI.Projections)」を参照してください。
```
aws dynamodb query \
--table-name Music \
--index-name AlbumTitleIndex \
--key-condition-expression "Artist = :v_artist and AlbumTitle = :v_title" \
--expression-attribute-values '{":v_artist":{"S":"Acme Band"},":v_title":{"S":"Songs About Life"} }'
```
# DynamoDB トランザクションで複雑なワークフローを管理する
Amazon DynamoDB Transactions は、テーブル内およびテーブル間の複数の項目を調整したり、変更しないといった、デベロッパーのエクスペリエンスを簡素化します。トランザクションによって DynamoDB に不可分性、一貫性、分離性、耐久性 (ACID) が実現されるため、アプリケーション内でのデータの精度を維持することができます。
DynamoDB トランザクション読み込み/書き込み API を使用し、1 つのオースオアナッシングオペレーションとして複数の項目の追加、更新、または削除が必要となる複雑なビジネスワークフローを管理できます。たとえば、ビデオゲームデベロッパーであれば、ゲーム内での項目交換やゲーム内購入の際に、プレイヤーのプロファイル更新の正確性を確保できます。
トランザクション書き込み API を使用して、複数の `Put`、`Update`、`Delete`、`ConditionCheck` の各アクションをグループ化できます。その後、アクションを単一の `TransactWriteItems` オペレーションとして送信できます。このオペレーションはユニットとして成功または失敗します。同じことが複数の `Get` アクションにも当てはまります。この場合、1 つの `TransactGetItems` オペレーションとしてグループ化し、送信できます。
DynamoDB テーブルのトランザクションを有効にするために、追加コストはかかりません。料金の支払いは、トランザクションの一部である読み込みまたは書き込みに対してのみ行われます。DynamoDB は、トランザクション内の各項目の基になっている 2 つの読み込みまたは書き込みを実行します。1 つはトランザクションの準備用で、もう 1 つはトランザクションのコミット用です。これらの基になっている 2 つの読み込み/書き込みオペレーションは、Amazon CloudWatch メトリクスに表示されます。
DynamoDB トランザクションを開始するには、最新の AWS SDK または AWS Command Line Interface (AWS CLI) をダウンロードします。その後、「[DynamoDB トランザクションの例](transaction-example.md)」に従います。
以下のセクションでは、トランザクション API の詳細についての概要とそれらを DynamoDB で使用する方法を示します。
**Topics**
+ [仕組み](transaction-apis.md)
+ [トランザクションでの IAM の使用](transaction-apis-iam.md)
+ [サンプルのコード](transaction-example.md)
# Amazon DynamoDB Transactions: 仕組み
Amazon DynamoDB Transactions を使用すれば、複数のアクションをまとめてグループ化し、1 つのオールオアナッシングの `TransactWriteItems` または `TransactGetItems` オペレーションとして送信できます。以下のセクションでは、API オペレーション、容量管理、ベストプラクティス、DynamoDB でのトランザクション操作の使用に関する他の詳細について説明します。
**Topics**
+ [TransactWriteItems API](#transaction-apis-txwriteitems)
+ [TransactGetItems API](#transaction-apis-txgetitems)
+ [DynamoDB トランザクションの分離レベル](#transaction-isolation)
+ [DynamoDB でのトランザクション競合の処理](#transaction-conflict-handling)
+ [DynamoDB アクセラレーター (DAX) でのトランザクション API の使用](#transaction-apis-dax)
+ [トランザクションの容量管理](#transaction-capacity-handling)
+ [トランザクションのベストプラクティス](#transaction-best-practices)
+ [グローバルテーブルでのトランザクション API の使用](#transaction-integration)
+ [DynamoDB トランザクションと AWSLabs トランザクションクライアントライブラリ](#transaction-vs-library)
## TransactWriteItems API
`TransactWriteItems` は、最大 100 の書き込みアクションを 1 つのオールオアナッシングオペレーションにグループ化する、同期的でべき等な書き込みオペレーションです。これらのアクションは、同じ AWS アカウントおよび同じリージョン内の 1 つ以上の DynamoDB テーブルにある最大 100 個の異なる項目をターゲットにすることができます。トランザクション内のアイテムの合計サイズは 4 MB を超えることはできません。すべて成功するかどれも成功しないかのどちらとなるように、アトミックに実行されます。
**注記**
`TransactWriteItems` オペレーションは、含まれるすべてのアクションを正常に完了する必要があり、そうでない場合は変更がまったく行われないという点で `BatchWriteItem` オペレーションとは異なります。`BatchWriteItem` オペレーションでは、バッチ内の一部のアクションのみ成功し、他のアクションは成功しないことがあり得ます。
インデックスを使用してトランザクションを実行することはできません。
同じトランザクション内の複数のオペレーションが同じ項目をターゲットとすることはできません。たとえば、同じトランザクション内で同じ項目に対して `ConditionCheck` を実行し、`Update` アクションも実行することはできません。
以下のタイプのアクションをトランザクションに追加できます。
+ `Put` — `PutItem` オペレーションを開始し、条件付きで、または条件をまったく指定せずに、新しい項目を作成するか、古い項目を新しい項目に置き換えます。
+ `Update` — `UpdateItem` オペレーションを開始し、既存の項目の属性を編集するか、まだ存在しない場合は新しい項目をテーブルに追加します。条件付きまたは条件なしで既存の項目で属性を追加、削除、更新するには、このアクションを使用します。
+ `Delete` — `DeleteItem` オペレーションを開始し、プライマリキーにより識別される 1 つの項目をテーブルで削除します。
+ `ConditionCheck` — 項目が存在することを確認するか、項目の特定の属性の条件を確認します。
DynamoDB でトランザクションが完了すると、変更のグローバルセカンダリインデックス (GSIs)、ストリーム、バックアップへの伝播が開始されます。この伝播は以下のとおり、徐々に行われます。同じトランザクションからのストリームレコードは異なるタイミングで表示されるため、他のトランザクションからのレコードとインターリーブする可能性があります。ストリームコンシューマーは、トランザクションの原子性や順番が保証されていると想定すべきではありません。
トランザクションで変更された項目のアトミックスナップショットを確保するには、TransactGetItems オペレーションを使用して、関連するすべての項目をまとめて読み取ります。このオペレーションを使用すると、データの一貫したビューが得られ、完了済みのトランザクションからのすべての変更が表示されるか、まったく表示されません。
伝播は即時に実行されるわけでないため、伝播中にテーブルがバックアップから復元された場合や([RestoreTableFromBackup](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_RestoreTableFromBackup.html))、特定時点のエクスポートが行われた場合 ([ExportTableToPointInTime](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_ExportTableToPointInTime.html))、含まれるのが最近のトランザクション中に行われた変更の一部のみとなる場合もあります。
### べき等性
`TransactWriteItems` 呼び出しを行ってリクエストが*冪等*であることを確認する場合、オプションでクライアントトークンを含めることができます。トランザクションを冪等にすると、接続のタイムアウトや他の接続問題に伴って同じオペレーションが複数回送信された場合に、アプリケーションエラーを防ぐことができます。
元の `TransactWriteItems` 呼び出しが成功した場合、同じクライアントトークンを持つ以降の `TransactWriteItems` 呼び出しは変更なしで正常に返ります。`ReturnConsumedCapacity` パラメータが設定されている場合、最初の `TransactWriteItems` 呼び出しは変更時に消費された書き込みキャパシティーユニットの数を返します。同じクライアントトークンを持つ以降の `TransactWriteItems` 呼び出しは、項目の読み取り時に消費された読み取りキャパシティユニットの数を返します。
**冪等性について重要な点**
+ クライアントトークンは、それを使用するリクエストが完了してから 10 分間有効です。10 分後、同じクライアントトークンを使用するリクエストは新しいリクエストとして扱われます。10 分が経過してから、同じリクエストに同じクライアントトークンを再利用しないでください。
+ 10 分間のべき等性期間内に同じクライアントトークンを使用してリクエストを繰り返すとき、他の一部のリクエストパラメータを変更した場合、DynamoDB は `IdempotentParameterMismatch` 例外を返します。
### 書き込みのエラー処理
以下の条件下では、書き込みトランザクションが成功しません。
+ いずれかの条件式の条件が満たされていない場合。
+ 同じ `TransactWriteItems` オペレーション内の複数のアクションが同じ項目をターゲットとしているために、トランザクション検証エラーが発生した場合。
+ `TransactWriteItems` リクエストが、`TransactWriteItems` リクエスト内の 1 つ以上の項目に対する継続中の `TransactWriteItems` オペレーションと競合する場合。この場合、リクエストは `TransactionCanceledException` で失敗します。
+ トランザクションを完了するプロビジョンドキャパシティーが足りない場合。
+ 項目サイズが大きくなりすぎる (400 KB 超)、ローカルセカンダリインデックス (LSI) が大きくなりすぎる、またはトランザクションにより変更が加えられたために同様の検証エラーが発生した場合。
+ 無効なデータ形式などのユーザーエラーがある場合。
`TransactWriteItems` オペレーションとの競合がどのように処理されるかについて詳しくは、「[DynamoDB でのトランザクション競合の処理](#transaction-conflict-handling)」を参照してください。
## TransactGetItems API
`TransactGetItems` は、最大 100 個の `Get` アクションをまとめてグループ化する同期読み取りオペレーションです。これらのアクションは、同じ AWS アカウントおよびリージョン内の 1 つ以上の DynamoDB テーブルにある最大 100 個の異なる項目をターゲットにすることができます。トランザクション内の項目の合計サイズは 4 MB を超えることはできません。
`Get` アクションは、すべて成功するかすべて失敗するかのどちらとなるように、アトミックに実行されます。
+ `Get` — `GetItem` オペレーションを開始し、指定されたプライマリキーを持つ項目の属性のセットを取得します。一致する項目が見つからない場合、`Get` はデータを返しません。
### 読み込みのエラー処理
以下の条件下では、読み取りトランザクションが成功しません。
+ `TransactGetItems` リクエストが、`TransactWriteItems` リクエスト内の 1 つ以上の項目に対する継続中の `TransactGetItems` オペレーションと競合する場合。この場合、リクエストは `TransactionCanceledException` で失敗します。
+ トランザクションを完了するプロビジョンドキャパシティーが足りない場合。
+ 無効なデータ形式などのユーザーエラーがある場合。
`TransactGetItems` オペレーションとの競合がどのように処理されるかについて詳しくは、「[DynamoDB でのトランザクション競合の処理](#transaction-conflict-handling)」を参照してください。
## DynamoDB トランザクションの分離レベル
トランザクションオペレーション (`TransactWriteItems` または `TransactGetItems`) と他のオペレーションの分離レベルは、次のとおりです。
### SERIALIZABLE
*直列化可能*分離レベルでは、複数の同時オペレーションの結果は、前のオペレーションが完了するまでオペレーションが開始されない場合と同じになります。
以下のタイプのオペレーション間には、直列化可能分離があります。
+ トランザクションオペレーションと標準書き込みオペレーション (`PutItem`、`UpdateItem`、または `DeleteItem`) の間。
+ トランザクションオペレーションと標準読み取りオペレーション (`GetItem`) の間。
+ `TransactWriteItems` オペレーションと `TransactGetItems` オペレーションの間。
トランザクションオペレーション間と `BatchWriteItem` オペレーション内の個々の標準書き込み間には直列化可能分離がありますが、トランザクションとユニットとしての `BatchWriteItem` オペレーションの間には直列化可能分離はありません。
同様に、トランザクションオペレーションと `GetItems` オペレーションの個別の `BatchGetItem` 間の分離レベルは直列化可能です。ただし、トランザクションとユニットとしての `BatchGetItem` オペレーション間の分離レベルは*コミット済み読み取り*です。
単一の `GetItem` リクエストは、`TransactWriteItems` リクエストの前または後に行う 2 つの方法のいずれかで、`TransactWriteItems` リクエストに関してシリアル化することができます。同時実行 `TransactWriteItems` リクエストのキーに対する複数の `GetItem` リクエストは、任意の順序で実行できるため、結果は*読み込みがコミット*されます。
たとえば、項目 A と項目 B の `GetItem` リクエストが、項目 A と項目 B の両方を変更する `TransactWriteItems` リクエストと同時に実行される場合、次の 4 つの可能性があります。
+ 両方の `GetItem` リクエストは、`TransactWriteItems` リクエストの前に実行されます。
+ 両方の `GetItem` リクエストは、`TransactWriteItems` リクエストの後に実行されます。
+ 項目 A の `GetItem` リクエストは、`TransactWriteItems` リクエストの前に実行されます。項目 B の場合、`GetItem` は `TransactWriteItems` の後に実行されます。
+ 項目 B の `GetItem` リクエストは、`TransactWriteItems` リクエストの前に実行されます。項目 A の場合、`GetItem` は `TransactWriteItems` の後に実行されます。
複数の `GetItem` リクエストにシリアル化可能な分離レベルが望ましい場合は、`TransactGetItems` を使用してください。
処理中に同じトランザクション書き込みリクエストの一部であった複数の項目に対して非トランザクション読み取りが行われた場合、一部の項目の新しい状態と他の項目の古い状態を読み取ることができる可能性があります。トランザクション書き込みリクエストに含まれていたすべての項目の新しい状態を読み取ることができるのは、トランザクションが完了したことを示すトランザクション書き込みの応答が成功した場合のみです。
トランザクションが正常に完了し、応答が受信されると、DynamoDB の結果整合性モデルにより、*結果整合性のある*読み込みオペレーションが短期間、古い状態を返す可能性があります。トランザクションの直後に最新のデータを確実に読み取るには、`ConsistentRead` を true に設定して、[*強力な整合性のある*](HowItWorks.ReadConsistency.md#HowItWorks.ReadConsistency.Strongly)読み込みを使用する必要があります。
### コミット済み読み取り
*コミット済み読み取り*分離により、読み取りオペレーションは常に項目のコミット済み値を返します。つまり、読み取りによって、最終的に成功しなかったトランザクション書き込みの状態を表すビューが項目に表示されることはありません。コミット済み読み取り分離では、読み取りオペレーションの直後に項目の変更が防止されません。
分離レベルは、トランザクションオペレーションと、複数の標準読み取り (`BatchGetItem`、`Query`、または `Scan`) が関係する読み取りオペレーションの間ではコミット済み読み取りです。トランザクション書き込みにより `BatchGetItem`、`Query`、または `Scan` オペレーションの途中で項目が更新された場合、その後の読み取りオペレーションの部分では、新しくコミットされた値 (`ConsistentRead)` を使用) か、場合によってはそれ以前のコミット済み値 (結果整合性のある読み込み) を返します。
### オペレーションの概要
以下の表は、トランザクションオペレーション (`TransactWriteItems` または `TransactGetItems`) と他のオペレーションの間の分離レベルをまとめたものです。
| オペレーション | 分離レベル |
| --- | --- |
| `DeleteItem` | *直列化可能* |
| `PutItem` | *直列化可能* |
| `UpdateItem` | *直列化可能* |
| `GetItem` | *直列化可能* |
| `BatchGetItem` | *コミット済み読み取り*\$1 |
| `BatchWriteItem` | *直列化不可*\$1 |
| `Query` | *コミット済み読み取り* |
| `Scan` | *コミット済み読み取り* |
| 他のトランザクションオペレーション | *直列化可能* |
アスタリスク (\$1) が付いたレベルは、ユニットとしてオペレーションに適用されます。ただし、これらのオペレーション内の個々のアクションの分離レベルは*直列化可能*です。
## DynamoDB でのトランザクション競合の処理
トランザクション競合は、トランザクション内の項目に対する項目レベルの同時リクエスト中に発生する場合があります。トランザクション競合は、次のシナリオで発生する場合があります。
+ 項目に対する `PutItem`、`UpdateItem`、または `DeleteItem` リクエストが、同じ項目を含む継続中の `TransactWriteItems` リクエストと競合する。
+ `TransactWriteItems` リクエスト内の項目が、継続中の別の `TransactWriteItems` リクエストの一部である。
+ `TransactGetItems` リクエスト内の項目が、継続中の `TransactWriteItems`、`BatchWriteItem`、`PutItem`、`UpdateItem`、または `DeleteItem` リクエストの一部である。
**注記**
`PutItem`、`UpdateItem`、または `DeleteItem` リクエストが拒否された場合、リクエストは `TransactionConflictException` で失敗します。
`TransactWriteItems` または `TransactGetItems` 内の項目レベルのリクエストが拒否された場合、リクエストは `TransactionCanceledException` で失敗します。そのリクエストが失敗した場合、AWS SDK はリクエストを再試行しません。
AWS SDK for Java を使用している場合、例外には `TransactItems` リクエストパラメータの項目リスト通りに順序付けられた [CancellationReasons](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_CancellationReason.html) のリストが含まれます。他の言語の場合、リストの文字列表現が例外のエラーメッセージに含まれます。
継続中の `TransactWriteItems` オペレーションまたは `TransactGetItems` オペレーションが同時 `GetItem` リクエストと競合している場合、両方のオペレーションが成功する可能性があります。
[TransactionConflict CloudWatch メトリクス](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/metrics-dimensions.html)は、項目レベルのリクエストが失敗するたびに増分されます。
## DynamoDB アクセラレーター (DAX) でのトランザクション API の使用
`TransactWriteItems` と `TransactGetItems` が、どちらも DynamoDB と同じ分離レベルで DynamoDB アクセラレーター (DAX) でサポートされています。
`TransactWriteItems` は DAX を介して書き込みます。DAX は DynamoDB に `TransactWriteItems` コールを渡し、応答を返します。書き込み後にキャッシュにデータを追加するために、DAX は、`TransactWriteItems` オペレーション内の各項目に対してバックグラウンドで `TransactGetItems` をコールします。これにより、追加の読み込み容量単位が消費されます。（詳しくは、[トランザクションの容量管理](#transaction-capacity-handling) を参照してください）。この機能により、アプリケーションロジックをシンプルに保ち、トランザクション処理と非トランザクション処理の両方に DAX を使用できます。
`TransactGetItems` コールは、項目がローカルにキャッシュされることなく DAX を通過します。これは、DAX の強い整合性のある読み込み API と同じです。
## トランザクションの容量管理
DynamoDB テーブルのトランザクションを有効にするために、追加コストはかかりません。料金の支払いは、トランザクションの一部である読み込みまたは書き込みに対してのみ行われます。DynamoDB は、トランザクション内の各項目の基になっている 2 つの読み込みまたは書き込みを実行します。1 つはトランザクションの準備用で、もう 1 つはトランザクションのコミット用です。基になっている 2 つの読み込み/書き込みオペレーションは、Amazon CloudWatch メトリクスに表示されます。
容量をテーブルにプロビジョニングするとき、トランザクション API により要求される追加の読み取りと書き込みを計画してください。たとえば、アプリケーションが 1 秒あたり 1 件のトランザクションを実行し、各トランザクションは 500 バイトの項目を 3 個テーブルに書き込むとします。各項目には、2 つの書き込みキャパシティーユニット (WCU) が必要です。1 つはトランザクションの準備用で、もう 1 つはトランザクションのコミット用です。したがって、テーブルには WCU を 6 個プロビジョニングする必要があります。
前の例で DynamoDB アクセラレーター (DAX) を使用していた場合、`TransactWriteItems` のコールで項目ごとに 2 つの読み込み容量単位 (RCU) も使用します。したがって、テーブルには追加の RCU を 6 個プロビジョニングする必要があります。
同様に、アプリケーションが 1 秒あたり 1 件の読み込みトランザクションを実行し、各トランザクションは 500 バイトの項目を 3 個テーブルで読み取る場合、読み込み容量単位 (RCU) を 6 個テーブルにプロビジョンする必要があります。各項目を読み取るには、2 つの RCU が必要です。1 つはトランザクションの準備用で、もう 1 つはトランザクションのコミット用です。
さらに、SDK のデフォルトの動作は、`TransactionInProgressException` 例外が発生した場合にトランザクションを再試行します。これらの再試行で消費される追加の読み込みキャパシティーユニット (RCU) を計画してください。同じことは、`ClientRequestToken` を使用して独自のコードでトランザクションを再試行しようとする場合に当てはまります。
## トランザクションのベストプラクティス
DynamoDB トランザクションの使用時に推奨される以下の手法を検討してください。
+ テーブルで自動スケーリングを有効にするか、トランザクションの項目ごとに 2 つの読み取りまたは書き込みオペレーションを実行するのに十分なスループット容量をプロビジョニングしたことを確認します。
+ AWS によって提供された SDK を使用していない場合、`TransactWriteItems` 呼び出しを行うときに `ClientRequestToken` 属性を含め、リクエストがべき等となるようにします。
+ 必要でない場合は、トランザクションにオペレーションをまとめてグループ化しないでください。たとえば、10 個のオペレーションを持つ 1 つのトランザクションを、アプリケーションの正確性を低下させずに複数のトランザクションに分割できる場合、トランザクションを分割することをお勧めします。トランザクションをシンプルにするとスループットが向上し、成功する可能性が高まります。
+ 同じ項目を同時に更新する複数のトランザクションによって、トランザクションをキャンセルする競合が発生する可能性があります。そのような競合を最小限に抑えるため、データモデリングには以下の DynamoDB のベストプラクティスをお勧めします。
+ 属性のセットが 1 つのトランザクションの一部として複数の項目間で頻繁に更新される場合、属性を 1 つの項目にグループ化し、トランザクションのスコープを減らすことを検討してください。
+ データを大量に取り込むためにトランザクションを使用しないでください。一括書き込みには、`BatchWriteItem` の使用をお勧めします。
## グローバルテーブルでのトランザクション API の使用
トランザクションオペレーションは、書き込み API が最初に呼び出された AWS リージョン内でのみ、不可分性、一貫性、分離性、および耐久性 (ACID) を保証します。グローバルテーブルのリージョン間では、トランザクションはサポートされていません。たとえば、米国東部 (オハイオ) リージョンと米国西部 (オレゴン) リージョンにレプリカを含むグローバルテーブルがあり、米国東部 (バージニア北部) リージョンで `TransactWriteItems` オペレーションを実行するとします。変更がレプリケートされると、米国西部 (オレゴン) リージョンで部分的に完了したトランザクションを確認できます。変更は、ソースリージョンでコミットされた後でのみ、他のリージョンにレプリケートされます。
## DynamoDB トランザクションと AWSLabs トランザクションクライアントライブラリ
DynamoDB トランザクションには、[AWSLabs](https://github.com/awslabs) トランザクションクライアントライブラリを置き換えるより費用対効率、堅牢性、パフォーマンスに優れた手段が用意されています。ネイティブのサーバー側トランザクション API を使用するようにアプリケーションを更新することをお勧めします。
# DynamoDB トランザクションでの IAM の使用
AWS Identity and Access Management (IAM) を使用すると、トランザクションオペレーションが Amazon DynamoDB で実行可能なアクションを制限できます。DynamoDB での IAM ポリシーの詳細な使用については、[DynamoDB のアイデンティティベースのポリシー](security_iam_service-with-iam.md#security_iam_service-with-iam-id-based-policies) を参照してください。
`Put`、`Update`、`Delete`、および `Get` アクションの権限は、基になる `PutItem`、`UpdateItem`、`DeleteItem`、および `GetItem` オペレーションに使用される権限により決定されます。`ConditionCheck` アクションの場合、IAM ポリシーで `dynamodb:ConditionCheckItem` 許可を使用できます。
以下に、DynamoDB トランザクションの設定に使用できる IAM ポリシーの例を示します。
## 例 1: トランザクションオペレーションを許可する
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:ConditionCheckItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem"
],
"Resource": [
"arn:aws:dynamodb:*:*:table/table04"
]
}
]
}
```
------
## 例 2: トランザクションオペレーションのみを許可する
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:ConditionCheckItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem"
],
"Resource": [
"arn:aws:dynamodb:*:*:table/table04"
],
"Condition": {
"ForAnyValue:StringEquals": {
"dynamodb:EnclosingOperation": [
"TransactWriteItems",
"TransactGetItems"
]
}
}
}
]
}
```
------
## 例 3: トランザクションを使用しない読み込み/書き込みを許可し、トランザクションを使用する読み込み/書き込みをブロックする
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": [
"dynamodb:ConditionCheckItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem"
],
"Resource": [
"arn:aws:dynamodb:*:*:table/table04"
],
"Condition": {
"ForAnyValue:StringEquals": {
"dynamodb:EnclosingOperation": [
"TransactWriteItems",
"TransactGetItems"
]
}
}
},
{
"Effect": "Allow",
"Action": [
"dynamodb:PutItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem",
"dynamodb:UpdateItem"
],
"Resource": [
"arn:aws:dynamodb:*:*:table/table04"
]
}
]
}
```
------
## 例 4: ConditionCheck の失敗時に情報が返されないようにする
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:ConditionCheckItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem"
],
"Resource": "arn:aws:dynamodb:*:*:table/table01",
"Condition": {
"StringEqualsIfExists": {
"dynamodb:ReturnValues": "NONE"
}
}
}
]
}
```
------
# DynamoDB トランザクションの例
Amazon DynamoDB Transactions が役に立つ状況の例として、このサンプルの Java アプリケーションをオンラインマーケットプレイスで検討してください。
アプリケーションには、バックエンドに 3 つの DynamoDB テーブルがあります。
+ `Customers` — このテーブルには、マーケットプレイスの顧客に関する詳細が保存されます。プライマリキーは `CustomerId` 一意の識別子です。
+ `ProductCatalog` — このテーブルには、マーケットプレイスで販売されている製品の価格や在庫状況などの詳細が保存されます。プライマリキーは `ProductId` 一意の識別子です。
+ `Orders` — このテーブルには、マーケットプレイスからの注文に関する詳細が保存されます。プライマリキーは `OrderId` 一意の識別子です。
## 注文を作成する
次のコードスニペットは、DynamoDB トランザクションを使用して、注文の作成と処理に必要な複数のステップを調整する方法を示しています。単一のオールオアナッシングオペレーションを使用すると、トランザクションのいずれかの部分が失敗しても、トランザクション内のアクションは実行されず、変更も行われません。
この例では、`customerId` が `09e8e9c8-ec48` である顧客からの注文を設定します。次に、次の単純な注文処理ワークフローを使用して、単一のトランザクションとして実行します。
1. 顧客 ID が有効であることを確認します。
1. 製品が `IN_STOCK` であることを確認し、製品のステータスを `SOLD` に更新します。
1. 注文がまだ存在していないことを確認し、注文を作成します。
### 顧客を検証する
まず、`customerId` が `09e8e9c8-ec48` に等しい顧客が顧客テーブルに存在することを確認するアクションを定義します。
```
final String CUSTOMER_TABLE_NAME = "Customers";
final String CUSTOMER_PARTITION_KEY = "CustomerId";
final String customerId = "09e8e9c8-ec48";
final HashMap customerItemKey = new HashMap<>();
customerItemKey.put(CUSTOMER_PARTITION_KEY, new AttributeValue(customerId));
ConditionCheck checkCustomerValid = new ConditionCheck()
.withTableName(CUSTOMER_TABLE_NAME)
.withKey(customerItemKey)
.withConditionExpression("attribute_exists(" + CUSTOMER_PARTITION_KEY + ")");
```
### 製品のステータスを更新する
次に、製品ステータスが現在 `IN_STOCK` に設定されている条件が `true` の場合に、製品ステータスを `SOLD` に更新するアクションを定義します。項目の製品ステータス属性が `IN_STOCK` に等しくなかった場合、`ReturnValuesOnConditionCheckFailure` パラメータを設定すると項目が返されます。
```
final String PRODUCT_TABLE_NAME = "ProductCatalog";
final String PRODUCT_PARTITION_KEY = "ProductId";
HashMap productItemKey = new HashMap<>();
productItemKey.put(PRODUCT_PARTITION_KEY, new AttributeValue(productKey));
Map expressionAttributeValues = new HashMap<>();
expressionAttributeValues.put(":new_status", new AttributeValue("SOLD"));
expressionAttributeValues.put(":expected_status", new AttributeValue("IN_STOCK"));
Update markItemSold = new Update()
.withTableName(PRODUCT_TABLE_NAME)
.withKey(productItemKey)
.withUpdateExpression("SET ProductStatus = :new_status")
.withExpressionAttributeValues(expressionAttributeValues)
.withConditionExpression("ProductStatus = :expected_status")
.withReturnValuesOnConditionCheckFailure(ReturnValuesOnConditionCheckFailure.ALL_OLD);
```
### 注文を作成する
最後に、`OrderId` の注文がまだ存在しない場合に限って、注文を作成します。
```
final String ORDER_PARTITION_KEY = "OrderId";
final String ORDER_TABLE_NAME = "Orders";
HashMap orderItem = new HashMap<>();
orderItem.put(ORDER_PARTITION_KEY, new AttributeValue(orderId));
orderItem.put(PRODUCT_PARTITION_KEY, new AttributeValue(productKey));
orderItem.put(CUSTOMER_PARTITION_KEY, new AttributeValue(customerId));
orderItem.put("OrderStatus", new AttributeValue("CONFIRMED"));
orderItem.put("OrderTotal", new AttributeValue("100"));
Put createOrder = new Put()
.withTableName(ORDER_TABLE_NAME)
.withItem(orderItem)
.withReturnValuesOnConditionCheckFailure(ReturnValuesOnConditionCheckFailure.ALL_OLD)
.withConditionExpression("attribute_not_exists(" + ORDER_PARTITION_KEY + ")");
```
### トランザクションを実行する
次の例は、単一のオールオアナッシングオペレーションとして以前に定義されたアクションを実行する方法を示しています。
```
Collection actions = Arrays.asList(
new TransactWriteItem().withConditionCheck(checkCustomerValid),
new TransactWriteItem().withUpdate(markItemSold),
new TransactWriteItem().withPut(createOrder));
TransactWriteItemsRequest placeOrderTransaction = new TransactWriteItemsRequest()
.withTransactItems(actions)
.withReturnConsumedCapacity(ReturnConsumedCapacity.TOTAL);
// Run the transaction and process the result.
try {
client.transactWriteItems(placeOrderTransaction);
System.out.println("Transaction Successful");
} catch (ResourceNotFoundException rnf) {
System.err.println("One of the table involved in the transaction is not found" + rnf.getMessage());
} catch (InternalServerErrorException ise) {
System.err.println("Internal Server Error" + ise.getMessage());
} catch (TransactionCanceledException tce) {
System.out.println("Transaction Canceled " + tce.getMessage());
}
```
## 注文詳細の読み込み
次の例は、完了した注文を `Orders` テーブルと `ProductCatalog` テーブルでのトランザクションから読み込む方法を示しています。
```
HashMap productItemKey = new HashMap<>();
productItemKey.put(PRODUCT_PARTITION_KEY, new AttributeValue(productKey));
HashMap orderKey = new HashMap<>();
orderKey.put(ORDER_PARTITION_KEY, new AttributeValue(orderId));
Get readProductSold = new Get()
.withTableName(PRODUCT_TABLE_NAME)
.withKey(productItemKey);
Get readCreatedOrder = new Get()
.withTableName(ORDER_TABLE_NAME)
.withKey(orderKey);
Collection getActions = Arrays.asList(
new TransactGetItem().withGet(readProductSold),
new TransactGetItem().withGet(readCreatedOrder));
TransactGetItemsRequest readCompletedOrder = new TransactGetItemsRequest()
.withTransactItems(getActions)
.withReturnConsumedCapacity(ReturnConsumedCapacity.TOTAL);
// Run the transaction and process the result.
try {
TransactGetItemsResult result = client.transactGetItems(readCompletedOrder);
System.out.println(result.getResponses());
} catch (ResourceNotFoundException rnf) {
System.err.println("One of the table involved in the transaction is not found" + rnf.getMessage());
} catch (InternalServerErrorException ise) {
System.err.println("Internal Server Error" + ise.getMessage());
} catch (TransactionCanceledException tce) {
System.err.println("Transaction Canceled" + tce.getMessage());
}
```
# Amazon DynamoDB の変更データキャプチャ
多くのアプリケーションでは、DynamoDB テーブルに保存された項目の変更を、変更の発生時にキャプチャすることで利点を利用できます。以下に示しているのは、いくつかのユースケースの例です。
+ 人気のモバイルアプリケーションは、1 秒あたり数千件の更新速度で、DynamoDB テーブルのデータを変更します。別のアプリケーションは、これらの更新に関するデータをキャプチャして保存し、モバイルアプリの使用状況メトリクスをほぼリアルタイムで提供します。
+ 金融アプリケーションは、DynamoDB テーブル内の株式市場データを変更します。並行して実行されるさまざまなアプリケーションは、これらの変化をリアルタイムで追跡し、リスクのある価値を計算し、株価の動きに基づいてポートフォリオを自動的にリバランスします。
+ 輸送車両や産業機器のセンサーは、DynamoDB テーブルにデータを送信します。さまざまなアプリケーションがパフォーマンスをモニタリングし、問題が検出されたときにメッセージングアラートを送信し、機械学習アルゴリズムを適用して潜在的な欠陥を予測し、データを圧縮して Amazon Simple Storage Service (Amazon S3) にアーカイブします。
+ アプリケーションは、友人の 1 人が新しい画像をアップロードするとすぐに、グループ内のすべての友人のモバイルデバイスに通知を自動送信します。
+ 新しいお客様がデータを DynamoDB テーブルに追加します。このイベントにより、新しいお客様にようこそメールを送信する別のアプリケーションが起動されます。
DynamoDB は、項目レベルの変更データキャプチャレコードのストリーミングをほぼリアルタイムでサポートします。これらのストリーミングを使用し、内容に基づいてアクションを実行するアプリケーションを構築できます。
**注記**
DynamoDB Streams へのタグの追加、DynamoDB Streams での[属性ベースのアクセス制御 (ABAC)](access-control-resource-based.md) の使用はサポートされていません。
次の動画では、データキャプチャ変更の概念を紹介します。
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/VVv_-mZ5Ge8)
**Topics**
+ [変更データキャプチャのストリーミングオプション](#streamsmain.choose)
+ [Kinesis Data Streams を使用して DynamoDB への変更をキャプチャする。](kds.md)
+ [DynamoDB Streams の変更データキャプチャ](Streams.md)
## 変更データキャプチャのストリーミングオプション
DynamoDB には、変更データキャプチャ用の 2 つのストリーミングモデルがあります。DynamoDB 用 Kinesis Data Streams と DynamoDB Streams です。
アプリケーションに適したソリューションを選択しやすくするために、次の表に、各ストリーミングモデルの特徴をまとめてあります。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/amazondynamodb/latest/developerguide/streamsmain.html)
同じ DynamoDB テーブルで両方のストリーミングモデルを有効にすることができます。
次の動画では、これら 2 つのオプションの違いを詳しく説明しています。
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/UgG17Wh2y0g)
# Kinesis Data Streams を使用して DynamoDB への変更をキャプチャする。
Amazon Kinesis Data Streams を使用して Amazon DynamoDB への変更をキャプチャできます。
Kinesis Data Streams は、DynamoDB テーブルの項目レベルの変更をキャプチャーし、それらを [Kinesis Data Streams](https://docs.aws.amazon.com/streams/latest/dev/introduction.html) にレプリケートします。アプリケーションは このストリームにアクセスして、項目レベルの変更をほぼリアルタイムで表示できます。1 時間あたりテラバイトのデータを継続的に取り込み保存できます。より長いデータ保持時間を利用し、強化されたファンアウト機能により、2 つ以上のダウンストリームアプリケーションに同時にアクセスできます。その他のメリットには、追加の監査とセキュリティの透明性が含まれます。
Kinesis Data Streams を使用すると、[Amazon Data Firehose](https://docs.aws.amazon.com/firehose/latest/dev/what-is-this-service.html) および [Amazon Managed Service for Apache Flink](https://docs.aws.amazon.com/kinesisanalytics/latest/dev/what-is.html) にもアクセスできます。これらのサービスは、リアルタイムでのダッシュボードの強化、アラートの生成、動的な料金設定、広告の実装、高度なデータ分析および機械学習アルゴリズムを実装するアプリケーションの構築に役立ちます。
**注記**
DynamoDB で Kinesis データストリームを使用すると、データストリームに対する [Kinesis Data Streams 料金](https://aws.amazon.com/kinesis/data-streams/pricing/)とソーステーブルに対する [DynamoDB 料金](https://aws.amazon.com/dynamodb/pricing/)の両方が適用されます。
コンソール、AWS CLI、または Java SDK を使用して DynamoDB テーブルで Kinesis ストリーミングを有効にするには、「[Amazon DynamoDB 用 Kinesis Data Streams の開始方法](kds_gettingstarted.md)」を参照してください。
**Topics**
+ [Kinesis Data Streams の DynamoDB との連携について](#kds_howitworks)
+ [Amazon DynamoDB 用 Kinesis Data Streams の開始方法](kds_gettingstarted.md)
+ [DynamoDB Streams および Kinesis Data Streams でのシャードとメトリクスの使用](kds_using-shards-and-metrics.md)
+ [Amazon Kinesis Data Streams および Amazon DynamoDB の IAM ポリシーを使用する](kds_iam.md)
## Kinesis Data Streams の DynamoDB との連携について
DynamoDB テーブルで Kinesis データストリームが有効になっている場合、そのテーブルは、テーブルのデータに対するすべての変更をキャプチャしたデータレコードを送信します。このデータレコードは以下を含みます。
+ 項目が最後に作成、更新、または削除された特定の時刻
+ その項目のプライマリキー
+ 変更前のレコードのスナップショット
+ 変更後のレコードのスナップショット
これらのデータレコードは、ほぼリアルタイムに取り込まれ、公開されます。これらが Kinesis データストリームに書き込まれた後は、他のレコードと同じように読み込むことができます。Kinesis Client Library の使用、AWS Lambda の使用、Kinesis Data Streams API の呼び出し、およびその他接続サービスの利用が可能です。詳細については、Amazon Kinesis Data Streams デベロッパーガイドの[Amazon Kinesis Data Streams からのデータの読み込み](https://docs.aws.amazon.com/streams/latest/dev/building-consumers.html)を参照してください。
これらのデータへの変更は、非同期的にキャプチャーされます。Kinesis は、ストリーミング元のテーブルに対するパフォーマンスに影響を与えません。Kinesis データストリームに保存されているストリームレコードも、保存時に暗号化されます。詳細については、「[Amazon Kinesis Data Streams のデータ保護](https://docs.aws.amazon.com/streams/latest/dev/server-side-encryption.html)」を参照してください。
Kinesis データストリームレコードは、項目の変更が発生した順序とは異なる順序で表示される場合があります。同じ項目の通知がストリームに複数回表示される場合もあります。`ApproximateCreationDateTime` 属性をチェックして、項目の変更が発生した順序を特定したり、重複するレコードを特定したりできます。
Kinesis データストリームを DynamoDB テーブルのストリーミング先として有効にすると、`ApproximateCreationDateTime` 値の精度をミリ秒またはマイクロ秒単位で設定できます。デフォルトでは、`ApproximateCreationDateTime` は変更の時刻をミリ秒単位で示します。さらに、アクティブなストリーミング先でこの値を変更できます。このような変更後、Kinesis に書き込まれるストリームレコードは、希望する精度の `ApproximateCreationDateTime` 値を持つようになります。
DynamoDB に書き込むバイナリ値は、[base64 エンコード形式](HowItWorks.NamingRulesDataTypes.md)でエンコードする必要があります。ただし、データレコードを Kinesis データストリームに書き込む場合、これらのエンコードされたバイナリ値は、再度 base64 エンコーディングでエンコードされます。これらのレコードを Kinesis データストリームから読み取る場合、未加工のバイナリ値を取得するには、アプリケーションでこれらの値を 2 回デコードする必要があります。
DynamoDB では、Kinesis Data Streams の使用に対して変更データキャプチャ単位で課金されます。単一の項目あたり 1 KB の変更が、1 つの変更データキャプチャ単位としてカウントされます。各項目で変更したキロバイト数は、[書き込み操作のキャパシティーユニット消費量](read-write-operations.md#write-operation-consumption)と同じロジックを使用して、ストリームに書き込まれた項目の「前の」イメージと「後の」イメージの大きい方で計算されます。DynamoDB [オンデマンド](capacity-mode.md#capacity-mode-on-demand)モードの動作と同様に、変更データキャプチャ単位のキャパシティースループットをプロビジョニングする必要はありません。
### DynamoDB テーブルの Kinesis データストリームを有効にする
AWS マネジメントコンソール、AWS SDK、または AWS Command Line Interface (AWS CLI) を使用して、既存の DynamoDB テーブルから Kinesis へのストリーミングを有効または無効にすることができます。
+ テーブルと同じ AWS アカウントと AWS リージョンでのみ、DynamoDB から Kinesis Data Streams にデータをストリーミングできます。
+ DynamoDB テーブルからのデータを 1 つの Kinesis データストリームにだけストリーミングできます。
### DynamoDB テーブルの Kinesis Data Streams 送信先に変更を加える
デフォルトでは、すべての Kinesis データストリームレコードには `ApproximateCreationDateTime` 属性が含まれます。この属性は、各レコードが作成されたおおよその時刻のタイムスタンプをミリ秒単位で表します。この値の精度は、[https://console.aws.amazon.com/kinesis](https://console.aws.amazon.com/kinesis)、SDK、または AWS CLI を使用して変更できます。
# Amazon DynamoDB 用 Kinesis Data Streams の開始方法
このセクションでは、Amazon DynamoDB コンソール、AWS Command Line Interface (AWS CLI)、および API を活用して Amazon DynamoDB 用の Amazon Kinesis Data Streams テーブルを使用する方法について説明します。
## アクティブな Amazon Kinesis Data Streams の作成
これらの例はすべて、[DynamoDB の使用開始](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html)チュートリアルの一部として作成された `Music` DynamoDB テーブルを使用しています。
コンシューマーを構築し、Kinesis データストリームを他の AWS のサービスに接続する詳細方法については、「*Amazon Kinesis Data Streams デベロッパーガイド*」の「[Kinesis Data Streams からのデータの読み込み](https://docs.aws.amazon.com/streams/latest/dev/building-consumers.html)」を参照してください。
**注記**
KDS シャードを初めて使用するときは、使用パターンに合わせてシャードをスケールアップまたはスケールダウンするように設定することをお勧めします。使用パターンに関するデータをさらに蓄積したら、それに合わせてストリーム内のシャードを調整できます。
------
#### [ Console ]
1. AWS マネジメントコンソール にサインインし、Kinesis コンソール ([https://console.aws.amazon.com/kinesis/](https://console.aws.amazon.com/kinesis/)) を開きます。
1. [**Create data stream (データストリーミングの作成)**] を選択し、指示に従って `samplestream` というストリーミングを作成します。
1. DynamoDB コンソール ([https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)) を開きます。
1. コンソールの左側のナビゲーションペインで、[**テーブル**] を選択します。
1. **[Music]** テーブルを選択します。
1. [**エクスポートとストリーム**] タブを選択します。
1. (オプション) **[Amazon Kinesis データストリームの詳細]** で、レコードのタイムスタンプの精度をマイクロ秒 (デフォルト) からミリ秒に変更できます。
1. ドロップダウンリストから **samplestream** を選択します。
1. **[オンにする]** ボタンを選択します。
------
#### [ AWS CLI ]
1. [create-stream コマンド](https://docs.aws.amazon.com/cli/latest/reference/kinesis/create-stream.html)を使用して、`samplestream` という名前の Kinesis データストリームを作成します。
```
aws kinesis create-stream --stream-name samplestream --shard-count 3
```
Kinesis データストリームのシャード数を設定する前に「[Kinesis Data Streams のシャード管理に関する考慮事項](kds_using-shards-and-metrics.md#kds_using-shards-and-metrics.shardmanagment)」を参照してください。
1. Kinesis ストリームがアクティブで、使用できる状態になっていることを確認するには、[describe-stream](https://docs.aws.amazon.com/cli/latest/reference/kinesis/describe-stream.html) コマンドを使用します。
```
aws kinesis describe-stream --stream-name samplestream
```
1. DynamoDB `enable-kinesis-streaming-destination` コマンドを使用して、DynamoDB テーブルで Kinesis ストリーミングを有効にします。`stream-arn` の値を、前のステップの `describe-stream` によって返された値で置き換えます。オプションで、各レコードに返されるタイムスタンプ値の精度をより細かく (マイクロ秒) したストリーミングを有効にします。
マイクロ秒のタイムスタンプ精度でのストリーミングを有効にします。
```
aws dynamodb enable-kinesis-streaming-destination \
--table-name Music \
--stream-arn arn:aws:kinesis:us-west-2:12345678901:stream/samplestream
--enable-kinesis-streaming-configuration ApproximateCreationDateTimePrecision=MICROSECOND
```
または、デフォルトのタイムスタンプ精度 (ミリ秒) でのストリーミングを有効にします。
```
aws dynamodb enable-kinesis-streaming-destination \
--table-name Music \
--stream-arn arn:aws:kinesis:us-west-2:12345678901:stream/samplestream
```
1. DynamoDB `describe-kinesis-streaming-destination` コマンドを使用して、テーブルで Kinesis ストリーミングがアクティブかどうかを確認します。
```
aws dynamodb describe-kinesis-streaming-destination --table-name Music
```
1. 「[DynamoDB デベロッパーガイド](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/getting-started-step-2.html)」の説明通りに、`put-item` コマンドを使用して DynamoDB テーブルにデータを書き込みます。
```
aws dynamodb put-item \
--table-name Music \
--item \
'{"Artist": {"S": "No One You Know"}, "SongTitle": {"S": "Call Me Today"}, "AlbumTitle": {"S": "Somewhat Famous"}, "Awards": {"N": "1"}}'
aws dynamodb put-item \
--table-name Music \
--item \
'{"Artist": {"S": "Acme Band"}, "SongTitle": {"S": "Happy Day"}, "AlbumTitle": {"S": "Songs About Life"}, "Awards": {"N": "10"} }'
```
1. Kinesis [get-records](https://docs.aws.amazon.com/cli/latest/reference/kinesis/get-records.html) CLI コマンドを使用して、Kinesis ストリームコンテンツを取得します。次に、以下のコードスニペットを使用して、ストリーミングコンテンツを逆シリアル化します。
```
/**
* Takes as input a Record fetched from Kinesis and does arbitrary processing as an example.
*/
public void processRecord(Record kinesisRecord) throws IOException {
ByteBuffer kdsRecordByteBuffer = kinesisRecord.getData();
JsonNode rootNode = OBJECT_MAPPER.readTree(kdsRecordByteBuffer.array());
JsonNode dynamoDBRecord = rootNode.get("dynamodb");
JsonNode oldItemImage = dynamoDBRecord.get("OldImage");
JsonNode newItemImage = dynamoDBRecord.get("NewImage");
Instant recordTimestamp = fetchTimestamp(dynamoDBRecord);
/**
* Say for example our record contains a String attribute named "stringName" and we want to fetch the value
* of this attribute from the new item image. The following code fetches this value.
*/
JsonNode attributeNode = newItemImage.get("stringName");
JsonNode attributeValueNode = attributeNode.get("S"); // Using DynamoDB "S" type attribute
String attributeValue = attributeValueNode.textValue();
System.out.println(attributeValue);
}
private Instant fetchTimestamp(JsonNode dynamoDBRecord) {
JsonNode timestampJson = dynamoDBRecord.get("ApproximateCreationDateTime");
JsonNode timestampPrecisionJson = dynamoDBRecord.get("ApproximateCreationDateTimePrecision");
if (timestampPrecisionJson != null && timestampPrecisionJson.equals("MICROSECOND")) {
return Instant.EPOCH.plus(timestampJson.longValue(), ChronoUnit.MICROS);
}
return Instant.ofEpochMilli(timestampJson.longValue());
}
```
------
#### [ Java ]
1. 「Kinesis Data Streams デベロッパーガイド」の指示に従って、Java を使用し `samplestream` という名前の Kinesis データストリームを[作成](https://docs.aws.amazon.com/streams/latest/dev/kinesis-using-sdk-java-create-stream.html)します。
Kinesis Data Streams のシャード数を設定する前に [Kinesis Data Streams のシャード管理に関する考慮事項](kds_using-shards-and-metrics.md#kds_using-shards-and-metrics.shardmanagment) を参照してください。
1. 次のコードスニペットを使用して、DynamoDB テーブルで Kinesis ストリーミングを有効にします。オプションで、各レコードに返されるタイムスタンプ値の精度をより細かく (マイクロ秒) したストリーミングを有効にします。
マイクロ秒のタイムスタンプ精度でのストリーミングを有効にします。
```
EnableKinesisStreamingConfiguration enableKdsConfig = EnableKinesisStreamingConfiguration.builder()
.approximateCreationDateTimePrecision(ApproximateCreationDateTimePrecision.MICROSECOND)
.build();
EnableKinesisStreamingDestinationRequest enableKdsRequest = EnableKinesisStreamingDestinationRequest.builder()
.tableName(tableName)
.streamArn(kdsArn)
.enableKinesisStreamingConfiguration(enableKdsConfig)
.build();
EnableKinesisStreamingDestinationResponse enableKdsResponse = ddbClient.enableKinesisStreamingDestination(enableKdsRequest);
```
または、デフォルトのタイムスタンプ精度 (ミリ秒) でのストリーミングを有効にします。
```
EnableKinesisStreamingDestinationRequest enableKdsRequest = EnableKinesisStreamingDestinationRequest.builder()
.tableName(tableName)
.streamArn(kdsArn)
.build();
EnableKinesisStreamingDestinationResponse enableKdsResponse = ddbClient.enableKinesisStreamingDestination(enableKdsRequest);
```
1. 「*Kinesis Data Streams デベロッパーガイド*」の指示に従って、作成したデータストリームから[読み込み](https://docs.aws.amazon.com/streams/latest/dev/building-consumers.html)ます。
1. 次のコードスニペットを使用して、ストリームコンテンツを逆シリアル化します。
```
/**
* Takes as input a Record fetched from Kinesis and does arbitrary processing as an example.
*/
public void processRecord(Record kinesisRecord) throws IOException {
ByteBuffer kdsRecordByteBuffer = kinesisRecord.getData();
JsonNode rootNode = OBJECT_MAPPER.readTree(kdsRecordByteBuffer.array());
JsonNode dynamoDBRecord = rootNode.get("dynamodb");
JsonNode oldItemImage = dynamoDBRecord.get("OldImage");
JsonNode newItemImage = dynamoDBRecord.get("NewImage");
Instant recordTimestamp = fetchTimestamp(dynamoDBRecord);
/**
* Say for example our record contains a String attribute named "stringName" and we wanted to fetch the value
* of this attribute from the new item image, the below code would fetch this.
*/
JsonNode attributeNode = newItemImage.get("stringName");
JsonNode attributeValueNode = attributeNode.get("S"); // Using DynamoDB "S" type attribute
String attributeValue = attributeValueNode.textValue();
System.out.println(attributeValue);
}
private Instant fetchTimestamp(JsonNode dynamoDBRecord) {
JsonNode timestampJson = dynamoDBRecord.get("ApproximateCreationDateTime");
JsonNode timestampPrecisionJson = dynamoDBRecord.get("ApproximateCreationDateTimePrecision");
if (timestampPrecisionJson != null && timestampPrecisionJson.equals("MICROSECOND")) {
return Instant.EPOCH.plus(timestampJson.longValue(), ChronoUnit.MICROS);
}
return Instant.ofEpochMilli(timestampJson.longValue());
}
```
------
## アクティブな Amazon Kinesis データストリームに変更を加える
このセクションでは、コンソール、AWS CLI、API を使用して DynamoDB 用 Kinesis Data Streams のセットアップを変更する方法について説明します。
**AWS マネジメントコンソール**
1. DynamoDB コンソール ([https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)) を開きます。
1. テーブルに移動します。
1. **[エクスポートおよびストリーム]** タブを選択します。
**AWS CLI**
1. `describe-kinesis-streaming-destination` を呼び出して、ストリームが `ACTIVE` であることを確認します。
1. 次の例のように、`UpdateKinesisStreamingDestination` を呼び出します。
```
aws dynamodb update-kinesis-streaming-destination --table-name enable_test_table --stream-arn arn:aws:kinesis:us-east-1:12345678901:stream/enable_test_stream --update-kinesis-streaming-configuration ApproximateCreationDateTimePrecision=MICROSECOND
```
1. `describe-kinesis-streaming-destination` を呼び出して、ストリームが `UPDATING` であることを確認します。
1. ストリーミングステータスが再び `ACTIVE` になるまで `describe-kinesis-streaming-destination` を定期的に呼び出します。タイムスタンプの精度の更新が有効になるまで、最大 5 分かかることがあります。このステータスが更新されると、更新が完了したことを表し、新しい精度値が今後のレコードに適用されます。
1. `putItem` を使用してテーブルに書き込みます。
1. Kinesis `get-records` コマンドを使用して、Kinesis ストリームコンテンツを取得します。
1. 書き込みの `ApproximateCreationDateTime` の精度が希望どおりであることを確認します。
**Java API**
1. `UpdateKinesisStreamingDestination` リクエストと `UpdateKinesisStreamingDestination` レスポンスを構成するコードスニペットを提供します。
1. `DescribeKinesisStreamingDestination` リクエストと `DescribeKinesisStreamingDestination response` を構成するコードスニペットを提供します。
1. ストリーミングのステータスが、更新が完了し、将来のレコードに新しい精度値が適用されることを示す `ACTIVE` に戻るまで、`describe-kinesis-streaming-destination` を定期的に呼び出します。
1. テーブルへの書き込みを実行します。
1. ストリームから読み取り、ストリームコンテンツを逆シリアル化します。
1. 書き込みの `ApproximateCreationDateTime` の精度が希望どおりであることを確認します。
# DynamoDB Streams および Kinesis Data Streams でのシャードとメトリクスの使用
## Kinesis Data Streams のシャード管理に関する考慮事項
Kinesis データストリームは、[シャード](https://docs.aws.amazon.com/streams/latest/dev/key-concepts.html)でスループットをカウントします。Amazon Kinesis Data Streams では、データストリームに**オンデマンド**モードと**プロビジョンド**モードのどちらかを選択できます。
DynamoDB の書き込みワークロードが大きく変動しやすく予測不可能な場合は、Kinesis データストリームにオンデマンドモードを使用することをお勧めします。オンデマンドモードでは、Kinesis Data Streams が必要なスループットを提供するためにシャードを自動的に管理するため、キャパシティプランニングは必要ありません。
予測可能なワークロードの場合は、Kinesis データストリームにプロビジョニングモードを使用できます。プロビジョンドモードでは、DynamoDB からの変更データ取得レコードを格納するためのデータストリームのシャード数を指定する必要があります。Kinesis データストリームが DynamoDB テーブルをサポートするために必要なシャードの数を決定するには、次の入力値が必要です。
+ DynamoDB テーブルのレコードの平均サイズ (バイト単位、`average_record_size_in_bytes`)。
+ DynamoDB テーブルで実行される 1 秒あたりの書き込み操作の最大数。これには、アプリケーションで実行される作成、削除、更新操作のほか、Time to Live で生成された削除操作 (`write_throughput`) などの自動生成された操作も含まれます。
+ テーブルに対して実行する作成操作や削除操作と比較した、更新操作と上書き操作の割合 (`percentage_of_updates`)。更新操作と上書き操作では、変更された項目の古いイメージと新しいイメージの両方がストリームにレプリケートされることに留意してください。これにより、DynamoDB 項目のサイズが 2 倍になります。
Kinesis データストリームに必要なシャードの数 (`number_of_shards`) を計算するには、入力値を以下の式にあてはめます。
```
number_of_shards = ceiling( max( ((write_throughput * (4+percentage_of_updates) * average_record_size_in_bytes) / 1024 / 1024), (write_throughput/1000)), 1)
```
例えば、書き込み操作の最大スループットが 1,040 回/秒で (`write_throughput`)、平均レコードサイズが 800 バイト (`average_record_size_in_bytes)` であるとします。 この書き込み操作の 25% が更新操作 (`percentage_of_updates`) である場合、DynamoDB ストリーミングスループットに対応するために 2 つのシャード (`number_of_shards`) が必要になります。
```
ceiling( max( ((1040 * (4+25/100) * 800)/ 1024 / 1024), (1040/1000)), 1).
```
式を使用して Kinesis データストリームのプロビジョニングモードで必要なシャード数を計算する前に、次の点を考慮してください。
+ この式では、DynamoDB 変更データレコードを格納するのに必要なシャードの数を見積もることができます。これは、追加の Kinesis データストリームのコンシューマーをサポートするために必要なシャードの数など、Kinesis データストリームで必要なシャードの総数を表すものではありません。
+ ピークスループットを処理するようにデータストリームを設定しないと、プロビジョンドモードで読み取りおよび書き込みのスループットの例外が発生する可能性があります。この場合、データトラフィックに対応するようにデータストリームを手動でスケーリングする必要があります。
+ この式では、変更ログデータレコードを Kinesis Data Stream にストリーミングする前に DynamoDB によって生成される追加の肥大化を考慮に入れています。
Kinesis データストリームのキャパシティモードの詳細については、「[データストリームのキャパシティモードの選択](https://docs.aws.amazon.com/streams/latest/dev/how-do-i-size-a-stream.html)」を参照してください。さまざまなキャパシティモード間の料金の違いについて詳しくは、「[Amazon Kinesis Data Streams の料金](https://aws.amazon.com/kinesis/data-streams/pricing/)」を参照してください。
## Kinesis Data Streams を使用した変更データキャプチャのモニタリング
DynamoDB には、Kinesis への変更データキャプチャのレプリケーションをモニタリングするのに役立つ複数の Amazon CloudWatch メトリクスが用意されています。CloudWatch メトリクスの詳細な一覧については、「[DynamoDB のメトリクスとディメンション](metrics-dimensions.md)」を参照してください。
ストリームに十分な容量があるかどうかを判断する場合は、ストリームの有効化時と実稼働時の両方で次の項目をモニタリングすることをお勧めします。
+ `ThrottledPutRecordCount`: Kinesis データストリームのキャパシティが不足しているために、Kinesis データストリームによってスロットリングされたレコードの数。例外的な使用量のピーク時にスロットリングが発生する可能性がありますが、`ThrottledPutRecordCount` は可能な限り低く保つ必要があります。DynamoDB は、スロットリングされたレコードを Kinesis データストリームに再送信しますが、これによりレプリケーションのレイテンシーが高くなる可能性があります。
過剰で定期的なスロットリングが発生した場合は、テーブルで観測された書き込みスループットに比例して Kinesis ストリーミングシャードの数を増やす必要があります。Kinesis Data Streams のサイズ決定の詳細については、「[Kinesis Data Streams の初期サイズの決定](https://docs.aws.amazon.com/streams/latest/dev/amazon-kinesis-streams.html#how-do-i-size-a-stream)」を参照してください。
+ `AgeOfOldestUnreplicatedRecord`: Kinesis Data Streams にまだレプリケートされていない最も古い項目レベルの変更からの経過時間が DynamoDB テーブルに表示されました。通常のオペレーションでは、`AgeOfOldestUnreplicatedRecord` はミリ秒単位で順序を指定しなければなりません。この数字は、カスタマー管理設定上の選択が原因で失敗したレプリケーションの試行回数に基づいて増加します。
`AgeOfOldestUnreplicatedRecord` メトリクスが 168 時間を超えると、DynamoDB テーブルから Kinesis データストリームへの項目レベルの変更のレプリケーションは自動的に無効になります。
カスタマー管理設定でレプリケーション試行の失敗の原因になる例として、Kinesis データストリームキャパシティーのプロビジョニングが不足していたために過剰なスロットリングにつながった場合や、Kinesis データストリームのアクセスポリシーを手動で更新したために DynamoDB がデータストリームにデータを追加できなくなった場合が挙げられます。このメトリクスを可能な限り低く保つために、Kinesis データストリームキャパシティーを十分にプロビジョニングし、DynamoDB のアクセス許可が変更されていないことを確認する必要があります。
+ `FailedToReplicateRecordCount`: DynamoDB が Kinesis データストリームにレプリケートできなかったレコードの数。34 KB を超える特定の項目はサイズが拡張されて、Kinesis Data Streams の項目サイズ制限 1MB を超えるデータレコードが変更される場合があります。このサイズの拡張は、34 KB を超えるこれらの項目に多数のブール値や空の属性値が含まれる場合に発生します。ブール値と空の属性値は、DynamoDB に 1 バイトで格納されますが、Kinesis Data Streams レプリケーションで標準 JSON を使用してシリアル化すると、最大 5 バイトまで拡張されます。DynamoDB は、このような変更レコードを Kinesis データストリームにレプリケートできません。DynamoDB は、これらの変更データレコードをスキップし、後続のレコードを自動的にレプリケートします。
前述のメトリクスのいずれかが特定のしきい値を超えた場合に通知するために、Amazon Simple Notification Service (Amazon SNS) メッセージを送信する Amazon CloudWatch アラームを作成できます。
# Amazon Kinesis Data Streams および Amazon DynamoDB の IAM ポリシーを使用する
Amazon DynamoDB 用 Amazon Kinesis Data Streams を初めて有効にすると、DynamoDB は AWS Identity and Access Management (IAM) サービスにリンクされたロールを自動的に作成します。このロール `AWSServiceRoleForDynamoDBKinesisDataStreamsReplication` を使用すると、DynamoDB はユーザーに代わって Kinesis Data Streams への項目レベルの変更のレプリケーションを管理できます。このサービスにリンクされたロールは削除しないでください。
サービスリンクロールの詳細については、「*IAM ユーザーガイド*」の「[サービスリンクロールの使用](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html)」を参照してください。
**注記**
DynamoDB は、IAM ポリシーのタグベースの条件をサポートしていません。
Amazon DynamoDB 用 Amazon Kinesis Data Streams を有効にするには、テーブルに対する以下の許可が必要です。
+ `dynamodb:EnableKinesisStreamingDestination`
+ `kinesis:ListStreams`
+ `kinesis:PutRecords`
+ `kinesis:DescribeStream`
特定の DynamoDB テーブルに対する Amazon DynamoDB 用 Amazon Kinesis Data Streams を記述するには、テーブルに対する以下の許可が必要です。
+ `dynamodb:DescribeKinesisStreamingDestination`
+ `kinesis:DescribeStreamSummary`
+ `kinesis:DescribeStream`
Amazon DynamoDB 用 Amazon Kinesis Data Streams を無効にするには、テーブルに対する以下の許可が必要です。
+ `dynamodb:DisableKinesisStreamingDestination`
Amazon DynamoDB 用 Amazon Kinesis Data Streams を更新にするには、テーブルに対する以下の許可が必要です。
+ `dynamodb:UpdateKinesisStreamingDestination`
以下の例は、IAM ポリシーを使用して Amazon DynamoDB 用 Amazon Kinesis Data Streams の許可を付与する方法を示しています。
## 例: Amazon DynamoDB 用 Amazon Kinesis Data Streams を有効にする
以下の IAM ポリシーは、`Music` テーブルに対して Amazon DynamoDB 用 Amazon Kinesis Data Streams を有効にする権限を付与します。`Music` テーブルに対して DynamoDB 用 Kinesis Data Streams を無効化、更新、記述する権限は付与されません。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:CreateServiceLinkedRole",
"Resource": "arn:aws:iam::*:role/aws-service-role/kinesisreplication.dynamodb.amazonaws.com/AWSServiceRoleForDynamoDBKinesisDataStreamsReplication",
"Condition": {
"StringLike": {
"iam:AWSServiceName": "kinesisreplication.dynamodb.amazonaws.com"
}
}
},
{
"Effect": "Allow",
"Action": [
"dynamodb:EnableKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Music"
}
]
}
```
------
## 例: Amazon DynamoDB 用 Amazon Kinesis Data Streams を更新する
以下の IAM ポリシーは、`Music` テーブルに対して Amazon DynamoDB 用 Amazon Kinesis Data Streams を更新する権限を付与します。`Music` テーブルに対して DynamoDB 用 Kinesis Data Streams を有効化、無効化、記述する権限は付与されません。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:UpdateKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Music"
}
]
}
```
------
## 例: Amazon DynamoDB 用 Amazon Kinesis Data Streams を無効にする
以下の IAM ポリシーは、`Music` テーブルに対して Amazon DynamoDB 用 Amazon Kinesis Data Streams を無効にする権限を付与します。`Music` テーブルに対して Amazon DynamoDB 用 Amazon Kinesis Data Streams を有効化、更新、記述する権限は付与されません。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:DisableKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Music"
}
]
}
```
------
## 例: リソースに基づいて、選択的に Amazon DynamoDB 用 Amazon Kinesis Data Streams に許可を適用する
以下の IAM ポリシーは、`Music` テーブルの Amazon DynamoDB 用 Amazon Kinesis Data Streams を有効にするか、記述する許可を付与しますが、`Orders` テーブルの Amazon DynamoDB 用 Amazon Kinesis Data Streams を無効にする許可は拒否します。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:EnableKinesisStreamingDestination",
"dynamodb:DescribeKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Music"
},
{
"Effect": "Deny",
"Action": [
"dynamodb:DisableKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Orders"
}
]
}
```
------
## DynamoDB 用 Kinesis Data Streams に対するサービスにリンクされたロールの使用
Amazon DynamoDB 用 Amazon Kinesis Data Streams は、AWS Identity and Access Management (IAM) の[サービスにリンクされたロール](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-linked-role)を使用します。サービスにリンクされたロールは、一意のタイプの IAM ロールで、DynamoDB 用 Kinesis Data Streams に直接リンクされます。サービスにリンクされたロールは、DynamoDB 用 Kinesis Data Streams によって事前定義されており、お客様の代わりにサービスから他の AWS のサービスを呼び出す必要のあるアクセス許可がすべて含まれています。
サービスにリンクされたロールを使用することで、必要なアクセス権限を手動で追加する必要がなくなるため、DynamoDB 用 Kinesis Data Streams の設定が簡単になります。DynamoDB 用 Kinesis Data Streams は、サービスにリンクされたロールの許可を定義します。特に定義されている場合を除き、DynamoDB 用 Kinesis Data Streams のみがそのロールを引き受けることができます。定義される許可は、信頼ポリシーと許可ポリシーに含まれており、その許可ポリシーを他の IAM エンティティにアタッチすることはできません。
サービスリンクロールをサポートする他のサービスについては、「[IAM と連携する AWS のサービス](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html)」を参照して、**[サービスリンクロール]** 列が **[はい]** になっているサービスを見つけてください。サービスにリンクされたロールに関するドキュメントをサービスで表示するには、[**はい**] リンクを選択します。
### DynamoDB 用 Kinesis Data Streams に対するサービスにリンクされたロールの許可
DynamoDB 用 Kinesis Data Streams では、**AWSServiceRoleForDynamoDBKinesisDataStreamsReplication** という名前の、サービスにリンクされたロールを使用します。サービスにリンクされたロールの目的は、Amazon DynamoDB がお客様に代わって Kinesis Data Streams に対する項目レベルの変更のレプリケーションを管理できるように許可することです。
`AWSServiceRoleForDynamoDBKinesisDataStreamsReplication` サービスリンクロールは、ロールの引き受けについて以下のサービスを信頼します。
+ `kinesisreplication.dynamodb.amazonaws.com`
ロールのアクセス許可ポリシーは、指定したリソースに対して以下のアクションを完了することを DynamoDB 用 Kinesis Data Streams に許可します。
+ アクション: `Kinesis stream` での `Put records and describe`
+ アクション: `AWS KMS` で `Generate data keys`、ユーザーが生成した AWS KMS キーを使用して暗号化された Kinesis ストリームにデータを格納します。
ポリシードキュメントの正確な内容については、「[DynamoDBKinesisReplicationServiceRolePolicy](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/aws-service-role/DynamoDBKinesisReplicationServiceRolePolicy)」を参照してください。
サービスリンクロールの作成、編集、削除を IAM エンティティ (ユーザー、グループ、ロールなど) に許可するにはアクセス許可を設定する必要があります。詳細については、*IAM ユーザーガイド*の「[サービスにリンクされたロールの許可](https://docs.aws.amazon.com/IAM/latest/UserGuide/contributorinsights-service-linked-roles.html#service-linked-role-permissions)」を参照してください。
### DynamoDB 用 Kinesis Data Streams のサービスにリンクされたロールの作成
サービスにリンクされたロールを手動で作成する必要はありません。AWS マネジメントコンソール、AWS CLI または AWS API で DynamoDB 用 Kinesis Data Streams を有効にすると、DynamoDB 用 Kinesis Data Streams がサービスにリンクされたロールを作成します。
このサービスにリンクされたロールを削除した後で再度作成する必要が生じた場合は、同じ方法でアカウントにロールを再作成できます。DynamoDB 用 Kinesis Data Streams を有効にすると、DynamoDB 用 Kinesis Data Streams がサービスにリンクされたロールを再作成します。
### DynamoDB 用 Kinesis Data Streams のサービスにリンクされたロールの編集
DynamoDB 用 Kinesis Data Streams では、`AWSServiceRoleForDynamoDBKinesisDataStreamsReplication` サービスにリンクされたロールを編集することはできません。サービスにリンクされたロールを作成すると、多くのエンティティによってロールが参照される可能性があるため、ロール名を変更することはできません。ただし、IAM を使用してロールの説明を編集することはできます。詳細については、*IAM ユーザーガイド*の「[サービスにリンクされたロールの編集](https://docs.aws.amazon.com/IAM/latest/UserGuide/contributorinsights-service-linked-roles.html#edit-service-linked-role)」を参照してください。
### DynamoDB 用 Kinesis Data Streams のサービスにリンクされたロールの削除
サービスにリンクされたロールは、IAM コンソール、AWS CLI 、または AWS API を使用して手動で削除することもできます。そのためにはまず、サービスにリンクされたロールのリソースをクリーンアップする必要があります。その後で、手動で削除できます。
**注記**
リソースを削除する際に、DynamoDB 用 Kinesis Data Streams サービスでロールが使用されている場合、削除は失敗することがあります。失敗した場合は、数分待ってから再度オペレーションを実行してください。
**IAM を使用してサービスリンクロールを手動で削除するには**
IAM コンソール、AWS CLI、または AWS API を使用して、`AWSServiceRoleForDynamoDBKinesisDataStreamsReplication` サービスリンクロールを削除します。詳細については、*IAM ユーザーガイド*の「[サービスにリンクされたロールの削除](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html)」を参照してください。
# DynamoDB Streams の変更データキャプチャ
DynamoDB Streams は、DynamoDB テーブル内の項目レベルの変更に関するシーケンスを時間順にキャプチャし、その情報を最大 24 時間ログに保存します。アプリケーションは、このログにアクセスし、データ項目の変更前および変更後の内容をほぼリアルタイムで参照できます。
保管時の暗号化では、DynamoDB Streams のデータが暗号化されます。詳細については、「[保管時の DynamoDB 暗号化](EncryptionAtRest.md)」を参照してください。
*DynamoDB Streams* は、DynamoDB テーブル内の項目に加えられた変更に関する情報の順序付けされた情報です。テーブルでストリーミングを有効にすると、DynamoDB はテーブル内のデータ項目に加えられた各変更に関する情報をキャプチャします。
アプリケーションがテーブル内の項目を作成、更新、または削除するたびに、DynamoDB Streams は変更された項目のプライマリキー属性を付けてストリーミングレコードを書き込みます。*ストリーミングレコード*には、DynamoDB テーブル内の単一の項目に加えられたデータ変更についての情報が含まれています。ストリームレコードが追加情報（変更された項目の前後のイメージ）をキャプチャするようにストリームを設定できます。
DynamoDB Streams を使用すれば、以下のことを確認できます。
+ 各ストリームレコードは、ストリームに 1 回だけ出現します。
+ DynamoDB テーブルで変更された各項目について、ストリーミングレコードは項目に対する実際の変更と同じ順序で出現します。
DynamoDB Streams は、ストリーミングレコードをほぼリアルタイムで書き込むため、これらのストリーミングを使用し、内容に基づいてアクションを実行するアプリケーションを構築できます。
**Topics**
+ [DynamoDB Streams のエンドポイント](#Streams.Endpoints)
+ [ストリームの有効化](#Streams.Enabling)
+ [ストリームの読み込みと処理](#Streams.Processing)
+ [DynamoDB Streams と有効期限 (TTL)](time-to-live-ttl-streams.md)
+ [DynamoDB Streams Kinesis Adapter を使用したストリームレコードの処理](Streams.KCLAdapter.md)
+ [DynamoDB Streams 低レベル API: Java の例](Streams.LowLevel.Walkthrough.md)
+ [DynamoDB Streams と AWS Lambda のトリガー](Streams.Lambda.md)
+ [DynamoDB Streams と Apache Flink](StreamsApacheFlink.xml.md)
## DynamoDB Streams のエンドポイント
AWS では、DynamoDB と DynamoDB Streams 用に個別のエンドポイントを維持しています。データベースのテーブルとインデックスを使用するには、アプリケーションが DynamoDB エンドポイントにアクセスする必要があります。DynamoDB Streams レコードを読み込んで処理するには、アプリケーションが同じリージョンの DynamoDB Streams エンドポイントにアクセスする必要があります。
DynamoDB Streams には 2 つのエンドポイントセットが用意されています。具体的には次の 2 つです。
+ **IPv4 専用エンドポイント**: `streams.dynamodb..amazonaws.com` 命名規則を持つエンドポイント。
+ **デュアルスタックエンドポイント**: IPv4 と IPv6 の両方と互換性があり、`streams-dynamodb..api.aws` 命名規則に従う新しいエンドポイント。
**注記**
DynamoDB および DynamoDB Streams のリージョンとエンドポイントの完全なリストについては、「*AWS 全般のリファレンス*」の「[リージョンとエンドポイント](https://docs.aws.amazon.com/general/latest/gr/rande.html)」を参照してください。
AWS SDK は、DynamoDB と DynamoDB Streams 用に個別のクライアントを提供します。要件によっては、アプリケーションは、DynamoDB エンドポイント、DynamoDB Streams エンドポイント、または両方に同時にアクセスできます。両方のエンドポイントに接続するには、アプリケーションで 2 つのクライアントをインスタンス化する必要があります。1 つは DynamoDB 用、もう 1 つは DynamoDB Streams 用です。
## ストリームの有効化
新しいテーブルでは、AWS CLI または AWS SDK 経由でそのテーブルの作成時にストリームを有効にできます。また、既存のテーブルでストリーミングを有効または無効にすることや、ストリーミングの設定を変更することができます。DynamoDB Streams は非同期的に動作するため、ストリーミングを有効にしてもテーブルのパフォーマンスに影響はありません。
DynamoDB Streams を管理する最も簡単な方法は、AWS マネジメントコンソール を使用することです。
1. AWS マネジメントコンソール にサインインして DynamoDB コンソール ([https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)) を開きます。
1. DynamoDB コンソールのダッシュボードで、[**Tables (テーブル)**] を選択して既存テーブルを選びます。
1. [**エクスポートとストリーム**] タブを選択します。
1. **[DynamoDB ストリームの詳細]** セクションで、**[オンにする]** を選択します。
1. **[DynamoDB ストリームをオンにする]** ウィンドウで、テーブルのデータが変更されるたびにストリーミングに書き込まれる情報を選択します。
+ [**キー属性のみ**] - 変更された項目のキー属性のみ。
+ **[New image]** (新規イメージ) — 変更後に表示される項目全体。
+ **[Old image]** (古いイメージ) — 変更前に表示されていた項目全体。
+ **[New and old images]** (新規イメージおよび古いイメージ) — 項目の新しいイメージと古いイメージの両方。
すべての設定が正しいことを確認したら、**[ストリームをオンにする]** を選択します。
1. (オプション) 既存のストリーミングを無効にするには、**[DynamoDB ストリームの詳細]** で **[オフにする]** を選択します。
`CreateTable` または `UpdateTable` API オペレーションを使用して、ストリームを有効にするか、変更することもできます。ストリームの設定内容は、`StreamSpecification` パラメータにより決まります。
+ `StreamEnabled` — テーブルでストリーミングが有効 (`true`) か無効 (`false`) かを指定します。
+ `StreamViewType` — テーブル内のデータが変更されるたびにストリーミングに書き込まれる情報を指定します。
+ `KEYS_ONLY` — 変更された項目のキー属性のみ。
+ `NEW_IMAGE` — 変更後に表示される項目全体。
+ `OLD_IMAGE` — 変更前に表示されていた項目全体。
+ `NEW_AND_OLD_IMAGES` — 項目の新しいイメージと古いイメージの両方。
ストリームはいつでも有効または無効にできます。ただし、既にストリームがあるテーブルでストリームを有効にしようとした場合、`ValidationException` を受け取ります。また、ストリームのないテーブルでストリームを無効にしようとすると、`ValidationException` が発生します。
`StreamEnabled` を `true` に設定すると、一意のストリーミング記述子が割り当てられた新しいストリーミングが DynamoDB で作成されます。テーブルでストリームを無効にして再度有効にすると、新しいストリームは異なるストリーム記述子で作成されます。
各ストリームは、Amazon リソースネーム（ARN）により一意に識別されます。次に、`TestTable` という名前の DynamoDB テーブルにあるストリーミングのサンプル ARN を示します。
```
arn:aws:dynamodb:us-west-2:111122223333:table/TestTable/stream/2015-05-11T21:21:33.291
```
テーブルの最新のストリーミング記述子を調べるには、DynamoDB `DescribeTable` リクエストを発行し、レスポンスで `LatestStreamArn` 要素を探します。
**注記**
ストリームのセットアップ後は `StreamViewType` を編集できません。セットアップ後にストリームを変更する必要がある場合は、現在のストリームを無効にして新しいストリームを作成する必要があります。
## ストリームの読み込みと処理
ストリームを読み取って処理するには、アプリケーションから DynamoDB Streams エンドポイントに接続して API リクエストを発行する必要があります。
ストリームは、*ストリームレコード*で構成されています。各ストリーミングレコードは、ストリーミングが属する DynamoDB テーブル内の 1 件のデータ変更を表しています。各ストリームレコードには、レコードがストリームに発行された順序を反映したシーケンス番号が割り当てられます。
ストリームレコードは、グループ (つまり、*シャード*) に整理されます。各シャードは、複数のストリームレコードのコンテナとして機能し、これらのレコードへのアクセスと反復処理に必要な情報が含まれています。シャード内のストリームレコードは 24 時間後に自動的に削除されます。
シャードはエフェメラルであり、必要に応じて自動的に作成および削除されます。また、任意のシャードは複数の新しいシャードに分割できます。これもまた自動的に行われます (親シャードが 1 つの子シャードのみを持つ場合もあります)。アプリケーションが複数のシャードからレコードを並列処理できるように、シャードは親テーブルで高レベルな書き込みアクティビティに応じて分割される場合があります。
ストリームを無効にすると、開かれているシャードは閉じられます。ストリーミング内のデータは 24 時間読み込み可能な状態になります。
シャードには系列 (親と子) があるため、アプリケーションは子シャードを処理する前に、必ず親シャードを処理する必要があります。これにより、ストリームレコードも正しい順序で処理されるようになります。(DynamoDB Streams Kinesis Adapter を使用している場合、これは自動的に処理されます。アプリケーションは、シャードとストリーミングレコードを正しい順序で処理します。アプリケーションの実行中に分割されたシャードに加えて、新しいシャードまたは有効期限切れのシャードは自動的に処理されます。詳細については、「[DynamoDB Streams Kinesis Adapter を使用したストリームレコードの処理](Streams.KCLAdapter.md)」を参照してください。)
次の図は、ストリーム、ストリーム内のシャード、シャード内のストリームレコードの関係を示しています。
![\[DynamoDB Streams 構造。データ変更を表すストリームレコードは、シャードに編成されます。\]](http://docs.aws.amazon.com/ja_jp/amazondynamodb/latest/developerguide/images/streams-terminology.png)
**注記**
項目内のデータを何も変更しない `PutItem` または `UpdateItem` オペレーションを実行した場合、そのオペレーションのストリーミングレコードは DynamoDB Streams によって書き込まれ*ません*。
ストリームにアクセスしてその中のストリームレコードを処理するには、以下の操作を実行する必要があります。
+ アクセスするストリームの一意の ARN を調べます。
+ 目的のストリームレコードがストリーム内のどのシャードに含まれているかを調べます。
+ シャードにアクセスし、目的のストリームレコードを取得します。
**注記**
最大でも 2 つを超えるプロセスが、同時に同じストリームシャードから読み込みを行うことはできません。シャードごとに 2 つを超えるリーダーがあると、スロットリングが発生する場合があります。
DynamoDB Streams API は、アプリケーションプログラム用の以下のアクションを提供します。
+ `[ListStreams](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_ListStreams.html)` — 現在のアカウントおよびエンドポイントのストリーミング記述子のリストを返します。必要に応じて、特定のテーブル名のストリーム記述子だけをリクエストできます。
+ `[DescribeStream](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_DescribeStream.html)` — ストリームに関する情報 (例: ストリームの最新ステータス、Amazon リソースネーム (ARN)、シャードの構成、対応する DynamoDB テーブル) を返します。オプションで `ShardFilter` フィールドを使用して、親シャードに関連付けられた既存の子シャードを取得できます。
+ `[GetShardIterator](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_GetShardIterator.html)` — シャード内の場所を表す*シャードイテレーター*を返します。イテレータがストリーム内の最も古いポイント、最も新しいポイント、特定のポイントへのアクセスを提供することをリクエストできます。
+ `[GetRecords](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_GetRecords.html)` — 特定のシャード内からストリーミングレコードを返します。`GetShardIterator` リクエストから返されたシャードイテレーターを指定する必要があります。
リクエストやレスポンスの例など、これらの API オペレーションの詳細な説明については、「[Amazon DynamoDB Streams API リファレンス](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Operations_Amazon_DynamoDB_Streams.html)」を参照してください。
### シャード検出
2 つの強力な方法で、DynamoDB ストリーム内の新しいシャードを検出します。Amazon DynamoDB Streams ユーザーには、新しいシャードを追跡して識別するための 2 つの効果的な方法があります。
**ストリームトポロジ全体のポーリング**
`DescribeStream` API を使用して、ストリームを定期的にポーリングします。これにより、作成された新しいシャードを含む、ストリーム内のすべてのシャードが返されます。時間経過に伴う結果を比較することで、新しく追加されたシャードを検出できます。
**子シャードの検出**
`DescribeStream` API を `ShardFilter` パラメータとともに使用して、シャードのサブセットを見つけます。リクエストで親シャードを指定することで、DynamoDB Streams は直下の子シャードを返します。このアプローチは、ストリーム全体をスキャンせずにシャード系統のみを追跡する必要がある場合に役立ちます。
DynamoDB Streams からデータを使用するアプリケーションは、この `ShardFilter` パラメータを使用して閉じたシャードの読み取りから子シャードに効率的に移行でき、`DescribeStream` API への繰り返しの呼び出しを回避して、すべての閉じたシャードと開いているシャードのシャードマップを取得してトラバースできます。これにより、親シャードが閉じられた後に子シャードをすばやく検出できるため、ストリーム処理アプリケーションの応答性とコスト効率が向上します。
どちらの方法でも、DynamoDB Streams の進化する構造を常に把握できるため、重要なデータの更新やシャードの変更を見逃すことはありません。
### DynamoDB Streams のデータ保持期限
DynamoDB Streams 内のすべてのデータは、24 時間保持されます。特定のテーブルの直近 24 時間のアクティビティを取得して分析できます。ただし、24 時間を超えたデータはすぐにトリミング (削除) される可能性があります。
テーブルのストリームを無効にした場合、ストリーム内のデータは 24 時間読み込み可能な状態になります。この時間が経過すると、データは期限切れになり、ストリームレコードは自動的に削除されます。既存のストリームを手動で削除するためのメカニズムはありません。保持期限 (24 時間) が切れ、すべてのストリームレコードが削除されるまで待つ必要があります。
# DynamoDB Streams と有効期限 (TTL)
テーブルに対して Amazon DynamoDB Streams を有効にし、期限切れの項目のストリーミングレコードを処理することで、[有効期限](TTL.md) (TTL) によって削除された項目をバックアップ (または処理) できます。詳細については、「[ストリームの読み込みと処理](Streams.md#Streams.Processing)」を参照してください。
ストリームレコードにはユーザー ID フィールド `Records[].userIdentity` が含まれます。
有効期限切れの後に有効期限 (TTL) プロセスによって削除された項目には、次のフィールドが含まれています。
+ `Records[].userIdentity.type`
`"Service"`
+ `Records[