Rilevamento e correzione delle violazioni delle chiavi di indice in DynamoDB

Durante la fase di backfill della creazione dell'indice secondario globale, Amazon DynamoDB esamina ogni elemento nella tabella per determinare se è idoneo all'inclusione nell'indice. Alcuni elementi potrebbero non essere idonei perché causerebbero violazioni della chiave dell'indice. In questi casi, gli elementi rimangono nella tabella, ma l'indice non ha una voce corrispondente per tale elemento.

Una violazione della chiave di indice si verifica nelle seguenti situazioni:

• È presente una mancata corrispondenza del tipo di dati tra un valore di attributo e il tipo di dati dello schema della chiave dell'indice. Si supponga, ad esempio, che uno degli elementi nella tabella GameScores aveva un valore TopScore di tipo String. Se è stato aggiunto un indice secondario globale con una chiave di partizione di TopScore, di tipo Number, l'elemento della tabella violerebbe la chiave di indice.

• Il valore di un attributo supera la lunghezza massima di un attributo della chiave dell'indice. La lunghezza massima di una chiave di partizione è 2048 byte e la lunghezza massima di una chiave di ordinamento è 1024 byte. Se uno qualsiasi dei valori di attributo corrispondenti nella tabella supera questi limiti, l'elemento della tabella violerebbe la chiave di indice.

Nota

Se un valore di attributo String o Binary è impostato per un attributo utilizzato come chiave di indice, il valore dell'attributo deve avere una lunghezza maggiore di zero; in caso contrario, l'elemento della tabella violerebbe la chiave di indice.

Questo strumento non contrassegna questa violazione della chiave di indice, al momento.

Se si verifica una violazione della chiave di indice, la fase di backfill continua senza interruzioni. Tuttavia, gli elementi che violano non saranno inclusi nell'indice. Una volta completata la fase di backfill, tutte le scritture sugli elementi che violano lo schema delle chiavi del nuovo indice saranno rifiutate.

Per identificare e correggere i valori degli attributi in una tabella che violano una chiave di indice, utilizza lo strumento Rilevatore di violazioni. Per eseguire Rilevatore di violazioni, è necessario creare un file di configurazione che specifica il nome di una tabella da sottoporre a scansione, i nomi e i tipi di dati della chiave di partizione dell'indice secondario globale e della chiave di ordinamento e quali azioni intraprendere se vengono rilevate violazioni della chiave di indice. Rilevatore di violazioni può essere eseguito in una delle due diverse modalità:

• Modalità di rilevamento: rileva le violazioni della chiave dell'indice. Utilizza la modalità di rilevamento per segnalare gli elementi della tabella che causerebbero violazioni chiave in un indice secondario globale. Facoltativamente, è possibile richiedere che questi elementi di tabella che violano vengano eliminati immediatamente quando vengono rilevati. L'output dalla modalità di rilevamento viene scritto in un file, che è possibile utilizzare per ulteriori analisi.

• Modalità di correzione: correggere le violazioni della chiave di indice. In modalità di correzione, Rilevatore violazioni legge un file di input con lo stesso formato del file di output dalla modalità di rilevamento. La modalità di correzione legge i record dal file di input e, per ogni record, elimina o aggiorna gli elementi corrispondenti nella tabella. Se si sceglie di aggiornare gli elementi, è necessario modificare il file di input e impostare i valori appropriati per questi aggiornamenti.

Download ed esecuzione di Rilevatore violazioni

Rilevatore violazioni è disponibile come file eseguibile Java Archive (.jar) e viene eseguito su computer Windows, macOS o Linux. Rilevatore violazioni richiede Java 1.7 (o versioni successive) e Apache Maven.

• Scarica il rilevatore di violazioni da GitHub

Seguire le istruzioni riportate nel file README.md per scaricare e installare Rilevatore violazioni tramite Maven.

Per avviare Rilevatore violazioni, passare alla directory dove è stato creato ViolationDetector.java ed immettere il comando seguente.

java -jar ViolationDetector.jar [options]

La riga di comando di Rilevatore violazioni accetta le seguenti opzioni:

• -h | --help: stampa un riepilogo di utilizzo e le opzioni per Rilevatore violazioni.

• -p | --configFilePath value: il nome completo di un file di configurazione di Rilevatore violazioni. Per ulteriori informazioni, consulta File di configurazione di Rilevatore violazioni.

• -t | --detect value: rileva le violazioni della chiave di indice nella tabella e le scrive nel file di output di Rilevatore violazioni. Se il valore di questo parametro è impostato su keep, gli elementi con violazioni della chiave non vengono modificati. Se il valore è impostato su delete, gli elementi con violazioni della chiave vengono eliminati dalla tabella.

• -c | --correct value: legge le violazioni della chiave di indice da un file di input ed esegue azioni correttive sugli elementi della tabella. Se il valore di questo parametro è impostato su update, gli elementi con violazioni della chiave vengono aggiornati con valori nuovi e che non violano. Se il valore è impostato su delete, gli elementi con violazioni della chiave vengono eliminati dalla tabella.

File di configurazione di Rilevatore violazioni

Durante il runtime, lo strumento Rilevatore violazioni richiede un file di configurazione. I parametri di questo file determinano a quali risorse DynamoDB può accedere Rilevatore violazioni e la velocità effettiva assegnata che può utilizzare. Nella tabella seguente vengono descritti questi parametri.

Nome del parametro	Descrizione	Obbligatorio?
awsCredentialsFile	Il nome completo di un file contenente le credenziali AWS . Il file delle credenziali deve avere il seguente formato: accessKey = access_key_id_goes_here secretKey = secret_key_goes_here	Sì
dynamoDBRegion	La AWS regione in cui risiede la tabella. Ad esempio: us-west-2.	Sì
tableName	Il nome della tabella DynamoDB da sottoporre a scansione.	Sì
gsiHashKeyName	Il nome della chiave della partizione dell'indice.	Sì
gsiHashKeyType	Il tipo di dati della chiave di partizione dell'indice, String, Number o Binary: S | N | B	Sì
gsiRangeKeyName	Il nome della chiave di ordinamento dell'indice. Non specificare questo parametro se l'indice dispone solo di una chiave primaria semplice (chiave di partizione).	No
gsiRangeKeyType	Il tipo di dati della chiave di ordinamento dell'indice, String, Number o Binary: S | N | B Non specificare questo parametro se l'indice dispone solo di una chiave primaria semplice (chiave di partizione).	No
recordDetails	Indica se scrivere i dettagli completi delle violazioni della chiave di indice nel file di output. Se impostato su true (impostazione predefinita), vengono riportate tutte le informazioni sugli elementi che violano. Se impostato su false, viene riportato solo il numero di violazioni.	No
recordGsiValueInViolationRecord	Indica se scrivere i valori delle chiavi di indice che violano nel file di output. Se impostato su true (impostazione predefinita), vengono riportati i valori chiave. Se impostato su false (impostazione predefinita), i valori chiave non vengono riportati.	No
detectionOutputPath	Il percorso completo del file di output di Rilevatore violazioni. Questo parametro supporta la scrittura in una directory locale o in Amazon Simple Storage Service (Amazon S3). Di seguito vengono mostrati gli esempi: detectionOutputPath = //local/path/filename.csv detectionOutputPath = s3://bucket/filename.csv Le informazioni nel file di output vengono visualizzate in formato valori separati da virgole (). CSV Se non si imposta detectionOutputPath, il file di output è denominato violation_detection.csve viene scritto nella directory di lavoro corrente.	No
numOfSegments	Il numero di segmenti di scansione parallela da utilizzare quando Rilevatore violazioni esegue la scansione della tabella. Il valore predefinito è 1, che indica che la tabella viene scansionata in modo sequenziale. Se il valore è 2 o superiore, Rilevatore violazioni divide la tabella in tanti segmenti logici e un numero uguale di thread di scansione. L'impostazione massima per numOfSegments è 4.096. Per le tabelle più grandi, una scansione parallela è generalmente più veloce di una scansione sequenziale. Inoltre, se la tabella è abbastanza grande da estendersi su più partizioni, una scansione parallela distribuisce l'attività di lettura in modo uniforme su più partizioni. Per ulteriori informazioni sulle scansioni parallele in DynamoDB, consulta Scansione parallela.	No
numOfViolations	Il limite superiore delle violazioni della chiave di indice da scrivere nel file di output. Se impostato su -1 (impostazione predefinita), viene scansionata l'intera tabella. Se impostato su un numero intero positivo, Rilevatore violazioni si interrompe dopo il rilevamento di tale numero di violazioni.	No
numOfRecords	Il numero di elementi nella tabella da sottoporre a scansione. Se impostato su -1 (impostazione predefinita), viene scansionata l'intera tabella. Se impostato su un numero intero positivo, Rilevatore violazioni si interrompe dopo la scansione di molti elementi nella tabella.	No
readWriteIOPSPercent	Regola la percentuale di unità di capacità di lettura assegnata utilizzate durante la scansione della tabella. I valori validi sono compresi tra 1 e 100. Il valore predefinito (25) significa che Rilevatore violazioni non consumerà più del 25% della velocità effettiva di lettura assegnata della tabella.	No
correctionInputPath	Il percorso completo del file di output di correzione di Rilevatore violazioni. Se si esegue Rilevatore violazioni in modalità di correzione, il contenuto di questo file viene utilizzato per modificare o eliminare elementi di dati nella tabella che violano l'indice secondario globale. Il formato del file correctionInputPath è uguale a quello del file detectionOutputPath. Ciò consente di elaborare l'output dalla modalità di rilevamento come input in modalità di correzione.	No
correctionOutputPath	Il percorso completo del file di output di correzione di Rilevatore violazioni. Questo file viene creato solo se ci sono errori di aggiornamento. Questo parametro supporta la scrittura in una directory locale o su Amazon S3. Di seguito vengono mostrati gli esempi: correctionOutputPath = //local/path/filename.csv correctionOutputPath = s3://bucket/filename.csv Le informazioni nel file di output vengono visualizzate nel formato. CSV Se non si imposta correctionOutputPath, il file di output è denominato violation_update_errors.csve viene scritto nella directory di lavoro corrente.	No

Rilevamento

Per rilevare le violazioni della chiave di indice, utilizza Rilevatore violazioni con l'opzione --detect della riga di comando. Per mostrare come funziona questa opzione, considera la ProductCatalog tabella. Di seguito è riportato un elenco di elementi nella tabella. Sono visualizzati solo la chiave primaria (Id) e l'attributo Price.

ID (chiave primaria)	Prezzo
101	5
102	20
103	200
201	100
202	200
203	300
204	400
205	500

Tutti i valori per Price sono di tipo Number. Tuttavia, poiché DynamoDB è senza schemi, è possibile aggiungere un elemento con un Price non numerico. Ad esempio, si supponga di aggiungere un altro elemento alla tabella ProductCatalog.

ID (chiave primaria)	Prezzo
999	"Hello"

La tabella ha ora un totale di nove elementi.

A questo punto aggiungere un nuovo indice secondario globale alla tabella: PriceIndex. La chiave primaria di questo indice è una chiave di partizione, Price, che è di tipo Number. Dopo che l'indice è stato creato, conterrà otto elementi, ma la tabella ProductCatalog ne ha nove. La ragione di questa discrepanza è che il valore "Hello" è di tipo String, ma PriceIndex ha una chiave primaria di tipo Number. Il valore String viola la chiave dell'indice secondario globale, quindi non è presente nell'indice.

Per utilizzare Rilevatore violazioni in questo scenario, è innanzitutto necessario creare un file di configurazione come il seguente.

# 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

Quindi, è possibile eseguire Rilevatore violazioni come nell'esempio seguente.

$  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

Se il parametro di configurazione recordDetails è impostato su true, Rilevatore violazioni scrive i dettagli di ogni violazione nel file di output, come nell'esempio seguente.

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

Il file di output è in CSV formato. La prima riga del file è un'intestazione, seguita da un record per elemento che viola la chiave di indice. I campi di questi record di violazione sono i seguenti:

• Chiave hash tabella: il valore della chiave di partizione dell'elemento nella tabella.

• Chiave di intervallo tabella: il valore della chiave di ordinamento dell'elemento nella tabella.

• GSIhash key value: il valore della chiave di partizione dell'indice secondario globale.

• GSItipo di violazione della chiave hash: o. Type Violation Size Violation

• GSIdescrizione della violazione della chiave hash: la causa della violazione.

• GSIhash key update Value (FORUSER) - In modalità di correzione, un nuovo valore fornito dall'utente per l'attributo.

• GSIrange key value — Il valore della chiave di ordinamento dell'indice secondario globale.

• GSItipo di violazione della chiave di intervallo: Type Violation oSize Violation.

• GSIdescrizione della violazione della chiave range: la causa della violazione.

• GSIrange key update Value (FORUSER) — In modalità di correzione, un nuovo valore fornito dall'utente per l'attributo.

• Elimina attributo vuoto durante l'aggiornamento (S/N): in modalità di correzione, determina se eliminare (S) o mantenere (N) l'elemento di violazione nella tabella, ma solo se uno dei seguenti campi è vuoto:

  • GSI Hash Key Update Value(FOR USER)

  • GSI Range Key Update Value(FOR USER)

  Se uno di questi campi non è vuoto, allora Delete Blank Attribute When Updating(Y/N) non ha effetto.

Nota

Il formato dell'output può variare a seconda del file di configurazione e delle opzioni della riga di comando. Ad esempio, se la tabella ha una chiave primaria semplice (senza una chiave di ordinamento), nell'output non saranno presenti campi della chiave di ordinamento.

I record di violazione nel file potrebbero non essere ordinati.

Correzione

Per correggere le violazioni della chiave di indice, utilizza Rilevatore violazioni con l'opzione --correct della riga di comando. In modalità di correzione, Rilevatore violazioni legge il file di input specificato dal parametro correctionInputPath. Il file ha lo stesso formato del file detectionOutputPath, in modo da poter utilizzare l'output del rilevamento come input per la correzione.

Rilevatore violazioni fornisce due modi diversi per correggere le violazioni della chiave di indice:

• Elimina le violazioni: eliminare gli elementi della tabella che hanno valori di attributi che violano.

• Aggiorna violazioni: aggiornare gli elementi della tabella, sostituendo gli attributi che violano con valori che non violano.

In entrambi i casi, è possibile utilizzare il file di output dalla modalità di rilevamento come input per la modalità di correzione.

Continuando con l'esempio ProductCatalog, si supponga di voler eliminare l'elemento che viola dalla tabella. A tale scopo, utilizza la seguente riga di comando.

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

A questo punto, verrà richiesto di confermare se desideri eliminare gli elementi che violano.

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

Ora sia ProductCatalog che PriceIndex hanno lo stesso numero di elementi.