Détection et correction des violations de clé d'index

Durant la phase de remplissage du processus de création d'index secondaire global, Amazon DynamoDB examine chaque élément de la table pour déterminer s'il peut être inclus dans l'index. Il se peut que certains éléments ne soient pas être éligibles parce qu'ils provoqueraient des violations de clé d'index. Dans ce cas, ces éléments restent dans la table, mais l'index ne contient pas d'entrée correspondante.

Une violation de clé d'index se produit dans les situations suivantes :

• Il existe une discordance de type de données entre une valeur d'attribut et le type de données du schéma de clé d'index. Par exemple, supposons que l'un des éléments de la table GameScores a une valeur TopScore de type String. Si vous ajoutiez un index secondaire global avec une clé de partition TopScore de type Number, l'élément de la table violerait la clé d'index.

• Une valeur d'attribut de la table dépasse la longueur maximum pour un attribut de clé d'index. La longueur maximum d'une clé de partition est de 2 048 octets, et la longueur maximum d'une clé de tri est de 1 024 octets. Si l'une des valeurs d'attribut correspondantes dans la table dépasse ces limites, l'élément de la table viole la clé d'index.

Note

Si une valeur de String ou de Binary attribute est définie pour un attribut utilisé comme clé d'index, la valeur d'attribut doit avoir une longueur supérieure à zéro ; sinon, l'élément de la table viole la clé d'index.

Cet outil ne signale pas cette violation de clé d'index, pour le moment.

Si une violation de clé d'index se produit, la phase de remplissage se poursuit sans interruption. Toutefois, les éléments violant le schéma de clé ne sont pas inclus dans l'index. Une fois la phase de remplissage terminée, toutes les écritures dans des éléments, qui violent le schéma de clé du nouvel index sont rejetées.

Pour identifier et corriger les valeurs d'attribut dans une table, qui violent une clé d'index, utilisez l'outil de détection des violations. Pour exécuter l'outil de détection des violations, vous créez un fichier de configuration qui spécifie le nom d'une table à analyser, les noms et les types de données des clés de partition et de tri d'index secondaire global, ainsi que les actions à entreprendre en cas détection de violations de clé d'index. L'outil de détection des violations peut opérer dans l'un des deux modes suivants :

• Mode détection – Détecter les violations de clé d'index. Utilisez le mode de détection pour signaler les éléments de la table qui provoqueraient des violations de clé dans un index secondaire global (vous pouvez éventuellement demander que ces éléments de table violant le schéma de clé soient supprimés immédiatement quand ils sont détectés). La sortie du mode détection est écrite dans un fichier que vous pouvez utiliser pour une analyse plus approfondie.

• Mode correction – Corriger les violations de clé d'index. En mode correction, l'outil de détection des violations lit un fichier d'entrée du même format que le fichier de sortie du mode détection. Le mode correction lit les enregistrements du fichier d'entrée et, pour chacun d'eux, supprime ou met à jour les éléments correspondants dans la table (notez que, si vous choisissez de mettre à jour les éléments, vous devez modifier le fichier d'entrée et définir des valeurs appropriées pour ces mises à jour).

Téléchargement et exécution de l'outil de détection des violations

L'outil de détection des violations est disponible en tant qu'archive Java exécutable (fichier .jar), et s'exécute sur les ordinateurs Windows, macOS ou Linux. L'outil de détection des violations requiert Java 1.7 (ou version ultérieure) et Apache Maven.

• Télécharger l'outil de détection des violations à partir de GitHub

Suivez les instructions figurant dans le fichier README.md pour télécharger et installer l'outil de détection des violations à l'aide de Maven.

Pour démarrer l'outil de détection des violations, accédez au répertoire dans lequel vous avez généré le fichier ViolationDetector.java, puis entrez la commande suivante.

java -jar ViolationDetector.jar [options]

La ligne de commande de l'outil de détection des violations accepte les options suivantes :

• -h | --help – Affiche un résumé et des options d'utilisation pour l'outil de détection des violations.

• -p | --configFilePath value – Nom complet d'un fichier de configuration de l'outil de détection des violations. Pour plus d'informations, consultez Fichier de configuration de l'outil de détection des violations.

• -t | --detect value – Détecte les violations de clé d'index dans la table, et les écris dans le fichier de sortie de l'outil de détection des violations. Si la valeur de ce paramètre est définie sur keep, les éléments comportant des violations de clé ne sont pas modifiés. Si la valeur est définie sur delete, les éléments comportant des violations de clé sont supprimés de la table.

• -c | --correct value – Lit les violations de clé d'index à partir d'un fichier d'entrée, et prend des mesures correctives sur les éléments de la table. Si la valeur de ce paramètre est définie sur update, les éléments comportant des violations de clé sont mis à jour avec de nouvelles valeurs ne violant pas le schéma de clé. Si la valeur est définie sur delete, les éléments comportant des violations de clé sont supprimés de la table.

Fichier de configuration de l'outil de détection des violations

Lors de l'exécution, l'outil de détection des violations nécessite un fichier de configuration. Les paramètres de ce fichier déterminent les ressources DynamoDB auxquelles l'outil de détection des violations peut accéder, ainsi que le débit approvisionné qu'il peut consommer. Le tableau suivant décrit ces paramètres.

Nom du paramètre	Description	Obligatoire ?
awsCredentialsFile	Le nom complet d'un fichier contenant vos informations d'identification AWS. Le format du fichier contenant les informations d'identification doit être le suivant : accessKey = access_key_id_goes_here secretKey = secret_key_goes_here	Oui
dynamoDBRegion	La région AWS dans laquelle la table réside. Par exemple: us-west-2.	Oui
tableName	Le nom de la table DynamoDB à analyser.	Oui
gsiHashKeyName	Le nom de la clé de partition d'index.	Oui
gsiHashKeyType	Le type de données de la clé de partition d'index, à savoir String, Number ou Binary : S | N | B	Oui
gsiRangeKeyName	Le nom de la clé de tri d'index. Ne spécifiez pas ce paramètre si l'index n'a qu'une clé primaire simple (clé de partition).	Non
gsiRangeKeyType	Le type de données de la clé de tri d'index, à savoir String, Number ou Binary : S | N | B Ne spécifiez pas ce paramètre si l'index n'a qu'une clé primaire simple (clé de partition).	Non
recordDetails	Indication relative à l'écriture des détails des violations de clé d'index dans le fichier de sortie. Si la valeur est définie sur true (par défaut), les informations complètes sur les éléments violant le schéma de clé sont rapportées. Si la valeur est définie sur false, seul le nombre de violations est rapporté.	Non
recordGsiValueInViolationRecord	Indication relative à l'écriture des valeurs des violations de clé d'index dans le fichier de sortie. Si la valeur est définie sur true (par défaut), les valeurs de clés sont rapportées. Si la valeur est définie sur false, les valeurs de clés sont rapportées.	Non
detectionOutputPath	Le chemin d'accès complet du fichier de sortie de l'outil de détection des violations. Ce paramètre prend en charge l'écriture dans un répertoire local ou sur Amazon Simple Storage Service (Amazon S3). Voici quelques exemples : detectionOutputPath = //local/path/filename.csv detectionOutputPath = s3://bucket/filename.csv Les informations figurant dans le fichier de sortie s'affichent au format CSV (valeurs séparées par des virgules). Si vous ne définissez pas detectionOutputPath, le fichier de sortie est nommé violation_detection.csv et écrit dans votre répertoire de travail actuel.	Non
numOfSegments	Le nombre de segments d'analyse parallèle à utiliser quand l'outil de détection des violations analyse la table. La valeur par défaut est 1, ce qui signifie que la table est analysée de manière séquentielle. Si la valeur est égale ou supérieure à 2, l'outil de détection des violations divise la table en plusieurs segments logiques et un nombre égal d'unités d'exécution d'analyse. La valeur maximum de numOfSegments est 4 096. Pour les tables plus volumineuses, une analyse parallèle est généralement plus rapide qu'une analyse séquentielle. En outre, si la table est suffisamment grande pour couvrir plusieurs partitions, une analyse parallèle répartit uniformément son activité de lecture sur plusieurs partitions. Pour plus d'informations sur les analyses parallèles dans DynamoDB, consultez Analyse parallèle.	Non
numOfViolations	La limite supérieure des violations de clé d'index à écrire dans le fichier de sortie. Si la valeur est définie sur -1 (par défaut), la table entière est analysée. Si la valeur est définie sur un nombre entier positif, l'outil de détection des violations s'arrête après avoir rencontré ce nombre de violations.	Non
numOfRecords	Le nombre d'éléments de la table à analyser. Si la valeur est définie sur (par défaut), la table entière est analysée. Si la valeur est définie sur un nombre entier positif, l'outil de détection des violations s'arrête après avoir analysé ce nombre d'éléments de la table.	Non
readWriteIOPSPercent	Régule le pourcentage d'unités de capacité de lecture approvisionnée qui sont consommées pendant l'analyse de la table. La plage des valeurs valides s'étend de 1 à 100. La valeur par défaut (25) signifie que l'outil de détection des violations ne consommera pas plus de 25 % du débit de lecture approvisionné de la table.	Non
correctionInputPath	Chemin d'accès complet du fichier d'entrée de correction de l'outil de détection des violations. Si vous exécutez l'outil de détection des violations en mode correction, le contenu de ce fichier est utilisé pour modifier ou supprimer les éléments de données dans la table, qui violent l'index secondaire global. Le format du fichier correctionInputPath est identique à celui du fichier detectionOutputPath. Cela vous permet de traiter la sortie du mode détection comme entrée en mode correction.	Non
correctionOutputPath	Chemin d'accès complet du fichier de sortie de correction de l'outil de détection des violations. Ce fichier n'est créé que s'il y a des erreurs de mise à jour. Ce paramètre prend en charge l'écriture dans un répertoire local ou sur Amazon S3. Voici quelques exemples : correctionOutputPath = //local/path/filename.csv correctionOutputPath = s3://bucket/filename.csv Les informations figurant dans le fichier de sortie s'affichent au format CSV. Si vous ne définissez pas correctionOutputPath, le fichier de sortie est nommé violation_update_errors.csv et écrit dans votre répertoire de travail actuel.	Non

Détection

Pour détecter les violations de clé d'index, utilisez l'outil de détection des violations avec l'option de ligne de commande --detect. Pour voir le fonctionnement de cette option, considérez le tableau ProductCatalog présenté dans Création de tables et chargement de données pour des exemples de code dans DynamoDB. Voici la liste des éléments de la table. Seule la clé primaire (Id) et l'attribut Price sont affichés.

Id (clé primaire)	Prix
101	5
102	20
103	200
201	100
202	200
203	300
204	400
205	500

Toutes les valeurs pour Price sont de type Number. Cependant, DynamoDB étant sans schéma, il est possible d'ajouter un élément avec une valeur Price non numérique. Par exemple, supposons que vous ajoutez un autre élément à la table ProductCatalog.

Id (clé primaire)	Prix
999	"Hello"

La table totalise maintenant neuf éléments.

Vous ajoutez à présent un nouvel index secondaire global à la table : PriceIndex. La clé primaire pour cet index est une clé de partition, Price, de type Number. Une fois l'index généré, il contient huit éléments, tandis que la table ProductCatalog en contient neuf. La raison de cette différence est que la valeur "Hello" est de type String, alors que PriceIndex a une clé primaire de type Number. La valeur String violant la clé d'index secondaire globale, elle n'est pas présente dans l'index.

Pour utiliser l'outil de détection des violations dans ce scénario, vous devez d'abord créer un fichier de configuration tel que le suivant.

# 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

Ensuite, vous exécutez l'outil de détection des violations comme dans l'exemple suivant.

$  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

Si le paramètre de configuration recordDetails est défini sur true, l'outil de détection des violations écrit les détails de chaque violation dans le fichier de sortie, comme dans l'exemple suivant.

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

Le fichier de sortie est au format CSV. La première ligne du fichier est un en-tête. Elle est suivie d'un registre par élément qui viole la clé d'index. Les champs de ces registres de violation sont les suivants :

• Table hash key (Clé de hachage de table) – Valeur de clé de partition de l'élément dans la table.

• Table range key (Clé de plage de table) – Valeur de clé de tri de l'élément dans la table.

• GSI hash key value (Valeur de clé de hachage GSI) – Valeur de clé de partition de l'index secondaire global.

• GSI hash key violation type (Type de violation de clé de hachage GSI) – Type Violation ou Size Violation.

• GSI hash key violation description (Description de violation de clé de hachage GSI) – Cause de la violation.

• GSI hash key update value (FOR USER) (Valeur de mise à jour de clé de hachage GSI (POUR UTILISATEUR)) – En mode correction, nouvelle valeur fournie par l'utilisateur pour l'attribut.

• GSI range key value (Valeur de clé de plage GSI) – Valeur de clé de tri de l'index secondaire global.

• GSI range key violation type (Type de violation de clé de plage GSI) – Type Violation ou Size Violation.

• GSI range key violation description (Description de violation de clé de plage GSI) – Cause de la violation.

• GSI range key update value (FOR USER) (Valeur de mise à jour de clé de plage GSI (POUR UTILISATEUR)) – En mode correction, nouvelle valeur fournie par l'utilisateur pour l'attribut.

• Delete blank attribute when updating (Y/N) (Supprimer un attribut vide lors de la mise à jour (O/N)) – En mode correction, détermine s'il faut supprimer (Y) ou conserver (N) l'élément violant le schéma de clé dans la table, mais uniquement si l'un des champs suivants est vide :

  • GSI Hash Key Update Value(FOR USER)

  • GSI Range Key Update Value(FOR USER)

  Si l'un de ces champs n'est pas vide, Delete Blank Attribute When Updating(Y/N) n'a aucun effet.

Note

Le format de sortie peut varier en fonction du fichier de configuration et des options de ligne de commande. Par exemple, si la table possède une clé primaire simple (sans clé de tri), aucun champ de clé de tri ne figure dans la sortie.

Il se peut que les registres de violation dans le fichier ne soient pas dans un ordre trié.

Correction

Pour corriger les violations de clé d'indexation, utilisez l'outil de détection des violations avec l'option de ligne de commande --correct. En mode correction, l'outil de détection des violations lit le fichier d'entrée spécifié par le paramètre correctionInputPath. Le format de ce fichier étant le même que celui du fichier detectionOutputPath, vous pouvez utiliser la sortie de la détection comme entrée pour la correction.

L'outil de détection des violations offre deux options pour corriger les violations de clé d'index :

• Delete violations (Supprimer les violations) – Supprimer les éléments de table qui ont des valeurs d'attribut violant le schéma de clé.

• Update violations (Mettre à jour les violations) – Mettre à jour les éléments de table en remplaçant les attributs violant le schéma de clé par des valeurs ne les violant pas.

Dans les deux cas, vous pouvez utiliser le fichier de sortie du mode détection comme entrée pour le mode correction.

En poursuivant avec l'exemple ProductCatalog, supposons que vous voulez supprimer de la table l'élément violant le schéma de clé. Pour ce faire, vous utilisez la ligne de commande suivante.

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

À ce stade, vous êtes invité à confirmer si vous souhaitez supprimer les éléments violant le schéma de clé.

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

A présent, ProductCatalog et PriceIndex ont le même nombre d'éléments.