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

インデックスキー違反の検出と修正

グローバルセカンダリインデックス作成のバックフィルフェーズの間、DynamoDB はテーブルの各項目を調べ、インデックスに含めるかどうかを判断します。一部の項目は、インデックスキーの違反を引き起こすため、この対象とはならない場合があります。このような場合、項目はテーブルに残りますが、インデックスにはその項目に対応するエントリは作成されません。

次の場合に、インデックスキーの違反が発生します。

  • 属性値とインデックスキースキーマのデータ型の間にデータ型の不一致がある。たとえば、GameScores テーブルのいずれかの項目に、文字列型の値 TopScore があるとします。数値型のパーティションキー TopScore をグローバルセカンダリインデックスに追加すると、テーブルの項目はインデックスキーに違反します。

  • テーブルの属性値が、インデックスキー属性の最大長を超えている。パーティションキーの最大長は 2048 バイト で、ソートキーの最大長は 1024 バイト です。テーブルに対応する属性値のいずれかがこれらの制限を超えた場合は、テーブルの項目がインデックスキーに違反します。

インデックスキーの違反が発生した場合、バックフィルフェーズは中断なく続行しますが、違反のある項目はインデックスには含まれません。バックフィルフェーズが完了すると、新しいインデックスのキースキーマに違反する項目へのすべての書き込みは拒否されます。

インデックスキーに違反したテーブルの属性値を特定し、修正するには、Violation Detector ツールを使用します。Violation Detector を実行するには、スキャンするテーブルの名前、グローバルセカンダリインデックスパーティションキーとソートキーの名前とデータ型、およびインデックスキーの違反が見つかった場合に実行するアクションを指定する設定ファイルを作成します。Violation Detector は、次の 2 つのモードのどちらかで実行できます。

  • 検出モード - インデックスキーの違反を検出します。グローバルセカンダリインデックスでキー違反を発生させるようなテーブル項目を報告するには、検出モードを使用します(オプションで、これらのテーブル項目が見つかったらすぐに削除するようリクエストできます)。検出モードの出力はファイルに書き込まれ、詳細な分析に使用できます。

  • 修正モード - インデックスキーの違反を修正します。修正モードでは、Violation Detector は検出モードからの出力ファイルと同じ形式の入力ファイルを読み取ります。修正モードでは入力ファイルからレコードを読み取り、レコードごとに、テーブルの対応する項目を削除または更新します(項目の更新を選択する場合は、入力ファイルを編集し、更新の適切な値を設定する必要があります)。

Violation Detector のダウンロードと実行

Violation Detector は、実行可能 Java アーカイブ(.jar ファイル)の形で入手でき、Windows、Mac、または Linux コンピュータで動作します。Violation Detector には Java 1.7(またはそれ以降)と Maven が必要です。

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 の設定ファイル」を参照してください。

  • -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

インデックスパーティションキーのデータ型 (文字列、数値、またはバイナリ):

S | N | B

はい

gsiRangeKeyName

インデックスソートキーの名前。インデックスにシンプルなプライマリキー (パーティションキー) のみがある場合は、このパラメーターを指定しないでください。

いいえ

gsiRangeKeyType

インデックスソートキーのデータ型 (文字列、数値、またはバイナリ):

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 形式(カンマ区切り値)で表示されます。detectionOutputPath を設定しない場合、出力ファイルは violation_detection.csv という名前になり、現在の作業ディレクトリに書き込まれます。

いいえ

numOfSegments

Violation Detector がテーブルをスキャンするときに使用する並列スキャンセグメントの数。デフォルト値は 1 です。この場合、テーブルはシーケンシャルにスキャンされます。値が 2 以上の場合、Violation Detector はテーブルを多数の論理セグメントと同数のスキャンスレッドに分割します。

numOfSegments の最大設定は 4096 です。

通常、大きなテーブルの場合、並列スキャンはシーケンシャルスキャンより高速です。また、テーブルが複数のパーティションにまたがるほど大きい場合、並列スキャンでは複数のパーティションにわたって均等に読み取りアクティビティが分散されます。

DynamoDB での並列スキャンの詳細については、「並列スキャン」を参照してください。

いいえ

numOfViolations

出力ファイルに書き込むインデックスキーの違反の上限。-1(デフォルト)に設定された場合、テーブル全体がスキャンされます。正の整数に設定されている場合、Violation Detector はその数の違反が発生すると停止します。

いいえ

numOfRecords

スキャンするテーブルの項目数。-1(デフォルト)に設定された場合、テーブル全体がスキャンされます。正の整数に設定されている場合、Violation Detector はテーブルでその数の項目をスキャンした後に停止します。

いいえ

readWriteIOPSPercent

テーブルのスキャン中に消費された、プロビジョニングされた読み込みキャパシティーユニットの割合を管理します。有効な値の範囲は 1100 です。デフォルト値(25)は、Violation Detector が、プロビジョニングされた読み取りスループットの 25% 以上を消費しないことを意味します。

いいえ

correctionInputPath

Violation Detector の修正入力ファイルの完全なパス。Violation Detector を修正モードで実行すると、このファイルのコンテンツは、テーブルでグローバルセカンダリインデックスに違反するデータ項目を変更または削除するために使用されます。

correctionInputPath ファイルの形式は、detectionOutputPath ファイルの形式と同じです。これにより、検出モードからの出力を修正モードで入力として処理することができます。

いいえ

correctionOutputPath

Violation Detector の修正出力ファイルの完全なパス。このファイルは、更新エラーがある場合にのみ作成されます。

このパラメータは、ローカルディレクトリや Amazon Simple Storage Service (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 のすべての値は数値型です。ただし、DynamoDB はスキーマレスであるため、数値以外の Price を持つ項目を追加することができます。たとえば、別の項目を ProductCatalog テーブルに追加するとします。

Id(プライマリキー) 価格
999 "Hello"

テーブルには、これで合計 9 個の項目があります。

ここで、テーブルに新しいグローバルセカンダリインデックス PriceIndex を追加します。このインデックスのプライマリキーは、数値型のパーティションキー Price です。インデックスの作成後、8 個の項目が含まれますが、ProductCatalog テーブルには 9 個の項目があります。この不一致の理由は、値 "Hello" は文字列型ですが、PriceIndex には数値型のプライマリキーがあることです。文字列値はグローバルセカンダリインデックスキーに違反するので、インデックスには存在しません。

このシナリオで 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)形式です。ファイルの最初の行はヘッダーで、インデックスキーに違反する項目ごとに、1 つのレコードが続きます。これら違反レコードのフィールドは次のとおりです。

  • Table Hash Key - テーブルの項目のパーティションキー値。

  • Table Range Key - テーブルの項目のソートキーの値。

  • GSI Hash Key Value - グローバルセカンダリインデックスのパーティションキー値。

  • GSI Hash Key Violation Type - Type Violation または Size Violation

  • GSI Hash Key Violation Description - 違反の原因。

  • GSI Hash Key Update Value(FOR USER) - 修正モードで、属性に対してユーザーが指定した新しい値。

  • GSI Range Key Value - グローバルセカンダリインデックスのソートキーの値

  • GSI Range Key Violation Type - Type Violation または Size Violation

  • GSI Range Key Violation Description - 違反の原因。

  • GSI Range Key Update Value(FOR USER) - 修正モードで、属性に対してユーザーが指定した新しい値。

  • Delete Blank Attribute When Updating(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

これで、ProductCatalogPriceIndex の両方に同じ数の項目の数が含まれました。