Erkennen und Korrigieren von Indexschlüsselverstößen

Während der Abgleichphase der globalen sekundären Index-Erstellung untersucht Amazon DynamoDB jedes Element in der Tabelle, um zu ermitteln, ob es in den Index aufgenommen werden kann. Einige Elemente können möglicherweise nicht in den Index aufgenommen werden, da sie zu Indexschlüsselverstößen führen würden. In diesem Fall verbleiben die Elemente in der Tabelle, der Index verfügt dann jedoch über keinen entsprechenden Eintrag für dieses Element.

Verstoß des Indexschlüssels tritt in folgenden Situationen auf:

• Die Datentypen zwischen einem Attributwert und dem Indexschlüsselschema stimmen nicht überein. Angenommen, eines der Elemente in der Tabelle GameScores verfügt über den Wert TopScore des Typs String. Wenn Sie dann einen globalen sekundären Index mit dem Partitionsschlüssel TopScore vom Typ Number hinzufügen, verstößt das Element aus der Tabelle gegen den Index.

• Ein Attributwert aus der Tabelle überschreitet die maximale Länge für ein Indexschlüsselattribut. Die maximale Länge des Partitionsschlüssels beträgt 2048 bytes und die maximale Länge des Sortierschlüssels 1024 bytes. Wenn einer der entsprechenden Attributwerte in der Tabelle diese Grenzwerte überschreitet, würde das Element aus der Tabelle gegen den Index verstoßen.

Anmerkung

Wenn ein Zeichenfolgen- oder Binär-Attributwert für ein Attribut festgelegt ist, das als Indexschlüssel verwendet wird, muss der Attributwert eine Länge größer als Null haben. Andernfalls würde das Element aus der Tabelle gegen den Indexschlüssel verstoßen.

Dieses Tool kennzeichnet diesen Indexschlüsselverstoß derzeit nicht.

Wenn ein Indexschlüsselverstoß auftritt, wird die Auffüllphase ohne Unterbrechung fortgesetzt. Verstoßende Elemente sind jedoch nicht im Index enthalten. Nach Abschluss der Abgleichphase werden alle Schreibvorgänge für Elemente, die gegen das neue Schlüsselschema des Indexes verstoßen, abgelehnt.

Um die Attributwerte in einer Tabelle, die gegen einen Indexschlüssel verstoßen, zu identifizieren und zu korrigieren, verwenden Sie das Tool Violation Detector. Um Violation Detector auszuführen, erstellen Sie eine Konfigurationsdatei, die den Namen einer zu scannenden Tabelle sowie die Datentypen des Partitions- und Sortierschlüssels des globalen sekundären Indizes enthält und angibt, welche Aktionen unternommen werden, sollten Verstöße gegen den Indexschlüssel gefunden werden. Violation Detector kann in einem der beiden folgenden Modi ausgeführt werden:

• Erkennungsmodus — Erkennt Indexschlüsselverstöße. Verwenden Sie den Erkennungsmodus, um die Elemente in der Tabelle zu ermitteln, die in einem globalen sekundären Index zu Schlüsselverstößen führen. (Sie können optional angeben, dass die den Verstoß verursachenden Tabellenelemente sofort gelöscht werden, nachdem sie gefunden wurden.) Die Ausgabe des Erkennungsmodus wird eine Datei geschrieben, die Sie für weitere Analysen verwenden können.

• Korrekturmodus — Korrigiert Indexschlüsselverstöße. Im Korrekturmodus liest Violation Detector eine Eingabedatei im gleichen Format wie die Ausgabedatei des Erkennungsmodus. Der Korrekturmodus liest die Datensätze aus der Eingabedatei und löscht zu jedem Datensatz die entsprechenden Elemente in der Tabelle bzw. aktualisiert diese. (Wenn Sie beschließen, die Elemente zu aktualisieren, müssen Sie die Eingabedatei bearbeiten und für diese Aktualisierungen entsprechende Werte festlegen.)

Herunterladen und Ausführen von Violation Detector

Violation Detector steht als ausführbares Java-Archiv (.jar-Datei) zur Verfügung und kann auf Windows-, MacOS- oder Linux-Computern ausgeführt werden. Der Violation Detector erfordert Java 1.7 (oder höher) und Apache Maven.

• Violation Detector von GitHub herunterladen

Um Violation Detector mit Maven herunterzuladen und zu installieren, befolgen Sie die Anweisungen in der README.md-Datei.

Um Violation Detector zu starten, gehen Sie zu dem Verzeichnis, in dem Sie ViolationDetector.java erstellt haben, und geben Sie den folgenden Befehl ein:

java -jar ViolationDetector.jar [options]

Die Violation-Detector-Befehlszeile akzeptiert die folgenden Optionen:

• -h | --help – Druckt eine Nutzungszusammenfassung und die Optionen für Violation Detector.

• -p | --configFilePath value – Der vollständig qualifizierte Namen einer Violation Detector Konfigurationsdatei. Weitere Informationen finden Sie unter Die Konfigurationsdatei für den Violation Detector.

• -t | --detect  value– Erkennt Indexschlüsselverstöße in der Tabelle und schreibt sie in die Ausgabedatei von Violation Detector. Wenn der Wert für diesen Parameter auf keep festgelegt ist, werden Elemente mit Schlüsselverstößen nicht geändert. Wenn der Wert auf delete festgelegt ist, werden Elemente mit Schlüsselverstößen aus der Tabelle gelöscht.

• -c | --correct value — Liest Indexschlüsselverstöße aus einer Eingabedatei und nimmt entsprechende Korrekturen an den Elementen in der Tabelle vor. Wenn der Wert für diesen Parameter auf update festgelegt ist, werden Elemente mit Schlüsselverstößen mit neuen, konformen Werten aktualisiert. Wenn der Wert auf delete festgelegt ist, werden Elemente mit Schlüsselverstößen aus der Tabelle gelöscht.

Die Konfigurationsdatei für den Violation Detector

Zur Laufzeit erfordert das Tool Violation Detector eine Konfigurationsdatei. Die Parameter in dieser Datei bestimmen, auf welche DynamoDB-Ressourcen Violation Detector zugreifen kann und wie viel bereitgestellten Durchsatz es verbrauchen darf. In der Tabelle unten werden diese Parameter beschrieben.

Parametername	Beschreibung	Erforderlich?
awsCredentialsFile	Der vollständig qualifizierte Namen einer Datei, die Ihre AWS-Anmeldeinformationen enthält. Die Datei mit den Anmeldeinformationen muss das folgende Format aufweisen: accessKey = access_key_id_goes_here secretKey = secret_key_goes_here	Ja
dynamoDBRegion	Die AWS-Region, in der die Tabelle gespeichert ist. Beispiel: us-west-2.	Ja
tableName	Der Name der zu scannenden DynamoDB-Tabelle.	Ja
gsiHashKeyName	Der Name des Partitionsschlüssels des Index.	Ja
gsiHashKeyType	Der Datentyp des Partitionsschlüssels des Index – String, Number oder Binary: S | N | B	Ja
gsiRangeKeyName	Der Name des Sortierschlüssels des Index. Geben Sie diesen Parameter nicht an, wenn der Index nur über einen einfachen Primärschlüssel (Partitionsschlüssel) verfügt.	Nein
gsiRangeKeyType	Der Datentyp des Sortierschlüssels–String,Number, oderBinary: S | N | B Geben Sie diesen Parameter nicht an, wenn der Index nur über einen einfachen Primärschlüssel (Partitionsschlüssel) verfügt.	Nein
recordDetails	Gibt an, ob alle Details der Indexschlüsselverstöße in die Ausgabedatei geschrieben werden sollen. Ist dieser Parameter auf true (Standardwert) gesetzt, werden alle Informationen zu den Verstoß-Elementen aufgezeichnet. Wenn er auf false festgelegt ist, wird nur die Anzahl der Verstöße erfasst.	Nein
recordGsiValueInViolationRecord	Gibt an, ob die Werte der verursachenden Indexschlüssel in die Ausgabedatei geschrieben werden sollen. Ist dieser Parameter auf true (Standardwert) gesetzt, werden die Schlüsselwerte aufgezeichnet. Ist dieser Parameter auf false festgelegt, werden die Schlüsselwerte nicht aufgezeichnet.	Nein
detectionOutputPath	Der vollständige Pfad der Violation-Detector-Ausgabedatei. Dieser Parameter unterstützt das Schreiben in ein lokales Verzeichnis oder in Amazon Simple Storage Service (Amazon S3). Im Folgenden sind einige Beispiele aufgeführt: detectionOutputPath = //local/path/filename.csv detectionOutputPath = s3://bucket/filename.csv Die Informationen in der Ausgabedatei werden im komma-separierten Werte (CSV)-Format angezeigt. Wenn Sie detectionOutputPath nicht festlegen, wird die Ausgabedatei violation_detection.csv genannt und in das aktuelle Arbeitsverzeichnis geschrieben.	Nein
numOfSegments	Die Anzahl der Segmente des parallelen Scans, die verwendet werden sollen, wenn Violation Detector die Tabelle scannt. Der Standardwert ist 1. Dies bedeutet, dass die Tabelle sequenziell gescannt wird. Wenn der Wert 2 oder höher lautet, unterteilt Violation Detector die Tabelle in diese Anzahl logischer Segmente und eine gleichmäßigen Anzahl von Scan-Threads. Die maximale Einstellung für numOfSegments lautet 4.096 Tage. Bei größeren Tabellen ist ein paralleler Scan in der Regel schneller als ein sequenzieller Scan. Wenn die Tabelle außerdem groß genug ist, um sich über mehrere Partitionen zu erstrecken, verteilt ein paralleler Scan die Lesevorgänge gleichmäßig auf mehrere Partitionen. Weitere Informationen zu parallelen Scans in DynamoDB finden Sie im Abschnitt Parallele Scans.	Nein
numOfViolations	Der obere Grenzwert für Indexschlüsselverstöße, die in die Ausgabedatei geschrieben werden sollen. Ist dieser Parameter auf -1 (Standardwert) gesetzt, wird die gesamte Tabelle gescannt. Ist eine positive Ganzzahl festgelegt, beendet Violation Detector den Vorgang nach Erreichen dieser Anzahl von Verstößen.	Nein
numOfRecords	Die Anzahl der Elemente in der Tabelle, die gescannt werden sollen. Ist dieser Parameter auf -1 (Standardwert) gesetzt, wird die gesamte Tabelle gescannt. Ist eine positive Ganzzahl festgelegt, beendet Violation Detector den Vorgang, nachdem es diese Anzahl von Elementen in der Tabelle gescannt hat.	Nein
readWriteIOPSPercent	Regelt den Prozentsatz der bereitgestellten Lesekapazitätseinheiten, die während des Tabellen-Scans verbraucht werden. Der Bereich gültiger Werte lautet 1 bis 100. Der Standardwert (25) bedeutet, dass Violation Detector nicht mehr als 25 % des bereitgestellten Lesedurchsatzes der Tabelle verbraucht.	Nein
correctionInputPath	Der vollständige Pfad der Violation-Detector-Korrektureingabedatei. Wenn Sie Violation Detector im Korrekturmodus ausführen, wird der Inhalt dieser Datei herangezogen, um die Datenelemente in der Tabelle, die gegen den verstoßen, zu ändern oder zu löschen. Das Format der correctionInputPath-Datei ist identisch mit der detectionOutputPath-Datei. So können Sie die Ausgabe des Erkennungsmodus als Eingabe für den Korrekturmodus verarbeiten.	Nein
correctionOutputPath	Der vollständige Pfad der Violation-Detector-Korrekturausgabedatei. Diese Datei wird nur erstellt, wenn bei der Aktualisierung Fehler aufgetreten sind. Dieser Parameter unterstützt das Schreiben in ein lokales Verzeichnis oder in Amazon S3. Im Folgenden sind einige Beispiele aufgeführt: correctionOutputPath = //local/path/filename.csv correctionOutputPath = s3://bucket/filename.csv Die Informationen in der Ausgabedatei werden im CSV-Format angezeigt. Wenn Sie correctionOutputPath nicht festlegen, wird die Ausgabedatei violation_update_errors.csv genannt und in das aktuelle Arbeitsverzeichnis geschrieben.	Nein

Erkennung

Um Verstöße gegen den Indexschlüssel zu erkennen, verwenden Sie Violation Detector mit der Befehlszeilenoption --detect. Um zu zeigen, wie diese Option funktioniert, sollten Sie sich die Tabelle ProductCatalog unter Erstellen von Tabellen und Laden von Daten für Codebeispiele in DynamoDB anschauen. Im Folgenden finden Sie eine Liste der Elemente in der Tabelle. Nur der Primärschlüssel (Id) und das Price-Attribut werden angezeigt.

ID (Primärschlüssel)	Preis
101	5
102	20
103	200
201	100
202	200
203	300
204	400
205	500

Alle Werte für Price sind vom Typ Number. Da DynamoDB jedoch schemalos ist, können Sie ein Element mit einem nicht numerischen Price hinzufügen. Angenommen, wir fügen ein anderes Element zur Tabelle ProductCatalog hinzu.

ID (Primärschlüssel)	Preis
999	"Hello"

Die Tabelle verfügt jetzt über insgesamt neun Elemente.

Nun fügen Sie der Tabelle einen neuen globalen sekundären Index hinzu: PriceIndex. Der Primärschlüssel für diesen Index ist ein Partitionsschlüssel, Price, vom Typ Number. Nachdem der Index erstellt wurde, enthält er acht Elemente—aber die ProductCatalog-Tabelle verfügt aber über neun Elemente. Der Grund für diese Abweichung ist, dass der Wert "Hello" vom Typ String ist, PriceIndex aber über einen Primärschlüssel vom Typ Number verfügt. Der String-Wert verstößt gegen den Schlüssel des globalen sekundären Indizes, also ist er im Index nicht vorhanden.

Um Violation Detector in diesem Szenario zu verwenden, erstellen Sie zuerst eine Konfigurationsdatei, wie z. B. folgende:

# 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

Als Nächstes führen Sie den Violation Detector aus, wie im folgenden Beispiel gezeigt.

$  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

Wenn der Konfigurationsparameter recordDetails auf true gesetzt ist, schreibt Violation Detector die Details jedes Verstoßes in die Ausgabedatei, wie im folgenden Beispiel:

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

Die Ausgabedatei ist im CSV-Format. Die erste Zeile in der Datei ist eine Überschrift, gefolgt von einem Datensatz für jedes Element, das gegen den Indexschlüssel verstößt. Die Felder dieser die Verletzung verursachenden Datensätze sind folgende:

• Hash-Schlüssel der Tabelle — Der Partitionsschlüsselwert des Elements in der Tabelle.

• Tabellenbereichsschlüssel — Der Sortierschlüsselwert des Elements in der Tabelle.

• GSI-Hash-Schlüsselwert – Partitionsschlüsselwert des globalen sekundären Indizes.

• Art des GSI-Hash-Schlüsselverstoßes — Entweder Type Violation oder Size Violation.

• Beschreibung des GSI-Hash-Schlüsselverstoßes — Die Ursache des Verstoßes.

• Aktualisierungswert des GSI-Hash-Schlüssels (FÜR BENUTZER) — Im Korrekturmodus ein neuer, vom Benutzer angegebener Wert für das Attribut.

• Schlüsselwert des GSI-Bereichs – Der Sortierschlüsselwert des globalen sekundären Indexes.

• Art des GSI-Bereichsschlüsselverstoßes — Entweder Type Violation oder Size Violation.

• Beschreibung des GSI-Bereichsschlüsselverstoßes — Die Ursache des Verstoßes.

• Aktualisierungswert des GSI-Bereichsschlüssels (FÜR BENUTZER) — Im Korrekturmodus ein neuer, vom Benutzer angegebener Wert für das Attribut.

• Leeres Attribut bei Aktualisierung löschen (J/N) — Bestimmt im Korrekturmodus, ob das den Verstoß verursachende Element in der Tabelle gelöscht (J) oder beibehalten (N) werden soll; jedoch nur, wenn eines der folgenden Felder leer ist:

  • GSI Hash Key Update Value(FOR USER)

  • GSI Range Key Update Value(FOR USER)

  Wenn eines dieser Felder nicht leer ist, hat Delete Blank Attribute When Updating(Y/N) keine Auswirkungen.

Anmerkung

Das Ausgabeformat kann abhängig von der Konfigurationsdatei und den Befehlszeilenoptionen variieren. Wenn die Tabelle z. B. über einen einfachen Primärschlüssel (ohne Sortierschlüssel) verfügt, sind in der Ausgabe keine Sortierschlüsselfelder vorhanden.

Die den Verstoß verursachenden Datensätze in der Datei sind möglicherweise nicht sortiert.

Korrektur

Um Verstöße gegen den Indexschlüssel zu korrigieren, verwenden Sie Violation Detector mit der Befehlszeilenoption --correct. Im Korrekturmodus liest Violation Detector die Eingabedatei, die im Parameter correctionInputPath angegeben ist. Diese Datei hat das gleiche Format wie die Datei detectionOutputPath. Sie können also die Ausgabe der Erkennung als Eingabe für die Korrektur verwenden.

Violation Detector bietet zwei verschiedene Möglichkeiten zur Korrektur von Indexschlüsselverstößen:

• Verstöße löschen – Löscht die Tabellenelemente, die über Verstoß-Attributwerte verfügen.

• Verstöße aktualisieren – Aktualisiert die Tabellenelemente durch Ersetzen der Verstoß-Attribute durch konforme Werte.

In beiden Fällen können Sie die Ausgabedatei aus dem Erkennungsmodus als Eingabe für den Korrekturmodus verwenden.

Setzen wir unser Beispiel ProductCatalog fort: Angenommen, wir möchten das Verstoß-Element aus der Tabelle löschen. Zu diesem Zweck verwenden Sie die folgenden Befehlszeile:

$  java -jar ViolationDetector.jar --configFilePath config.txt --correct delete

An diesem Punkt werden Sie gebeten zu bestätigen, ob die verletzenden Elemente gelöscht werden sollen.

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

Nun verfügen ProductCatalog und PriceIndex über dieselbe Anzahl Elemente.