Detección y corrección de infracciones de la clave del índice en DynamoDB - Amazon DynamoDB
Descargar y ejecutar Violation DetectorEl archivo de configuración de Violation DetectorDetecciónCorrección

Detección y corrección de infracciones de la clave del índice en DynamoDB

Durante la fase de reposición de la creación de un índice secundario global, Amazon DynamoDB examina cada elemento de la tabla para determinar si es apto para incluirlo en el índice. Algunos elementos podrían no ser aptos por la posibilidad de que causen infracciones de claves de índice. En estos casos, el elemento en cuestión permanecen en la tabla, pero el índice no incluye la entrada correspondiente a dicho elemento.

Un registro infracción de clave de índice se produce en las siguientes situaciones:

  • Los tipos de datos del valor de un atributo y del esquema de claves del índice no coinciden. Por ejemplo, supongamos que uno de los elementos de la tabla GameScores tiene un atributo TopScore cuyo valor es de tipo String. Si agrega un índice secundario global con una clave de partición de TopScore de tipo Number, el elemento de la tabla infringiría la clave de índice.

  • El valor de atributo de la tabla supera la longitud máxima de un atributo de clave del índice. La longitud máxima de una clave de partición es de 2048 bytes y la longitud máxima de una clave de ordenación es de 1024 bytes. Si cualquiera de los valores de atributos correspondientes de la tabla supera estos límites, el elemento de la tabla infringiría la clave de índice.

nota

Si se establece un valor binario o de cadena en un atributo que se utiliza como clave de índice, este valor debe tener una longitud mayor que cero; de lo contrario, el elemento de la tabla podría infringir la clave del índice.

En la actualidad, esta herramienta no indica esta infracción de clave de índice de ninguna forma.

Si se produce una infracción de índice, la fase de reposición continúa sin interrupción. Sin embargo, los elementos infractores no se incluyen en el índice. Una vez que haya finalizado la fase de reposición, se rechazarán todas las escrituras en elementos que infringen el esquema de claves del nuevo índice.

Para identificar y corregir los valores de los atributos de una tabla que infringen una clave de índice, se utiliza la herramienta Violation Detector. Para ejecutar Violation Detector, debe crear un archivo de configuración que especifique el nombre de la tabla que se va a examinar, los nombres y los tipos de datos de las claves de partición y de ordenación del índice secundario global y qué medidas deben adoptarse si se detecta cualquier infracción de clave de índice. Violation Detector puede ejecutarse en dos modos diferentes:

  • Modo de detección: detecta las infracciones de claves de índice. El modo de detección se utiliza para registrar los elementos de la tabla que causarían infracciones de claves en un índice secundario global. (Si lo desea, puede solicitar que estos elementos infractores de la tabla se eliminen de inmediato en cuanto se encuentren). El resultado del modo de detección se escribe en un archivo, que se puede utilizar para analizar los datos posteriormente.

  • Modo de corrección: corrige las infracciones de claves de índice. En el modo de corrección, Violation Detector lee un archivo de información de entrada con el mismo formato que el archivo de resultados del modo de detección. En el modo de corrección se leen los registros del archivo de información de entrada y, para cada registro, se elimina o actualiza el elemento correspondiente de la tabla. Tenga en cuenta que si decide actualizar los elementos, deberá editar el archivo de información de entrada y establecer valores adecuados para estas actualizaciones.

Descargar y ejecutar Violation Detector

Violation Detector está disponible como archivo Java ejecutable (.jar) y se ejecuta en ordenadores Windows, Mac o Linux. Violation Detector requiere Java 1.7 (o posterior) y Apache Maven.

Siga las instrucciones del archivo README.md para descargar e instalar Violation Detector mediante Maven.

Para iniciar Violation Detector, vaya al directorio donde ha construido ViolationDetector.java e ingrese el siguiente comando.

java -jar ViolationDetector.jar [options]

La línea de comandos de Violation Detector acepta las siguientes opciones:

  • -h | --help: imprime un resumen de uso y las opciones posibles de Violation Detector.

  • -p | --configFilePath value: nombre completo de un archivo de configuración de Violation Detector. Para obtener más información, consulte El archivo de configuración de Violation Detector.

  • -t | --detect value: detecta las infracciones de claves de índice de la tabla y las escribe en el archivo de resultados de Violation Detector. Si el valor de este parámetro se establece en keep, los elementos con infracciones de claves no se modifican. Si el valor se establece en delete, los elementos con infracciones de claves se eliminan de la tabla.

  • -c | --correct value: lee las infracciones de claves de índice en un archivo de información de entrada y adopta medidas para corregir los elementos de la tabla. Si el valor de este parámetro se establece en update, los elementos con infracciones de claves se actualizan a otros valores sin infracciones. Si el valor se establece en delete, los elementos con infracciones de claves se eliminan de la tabla.

El archivo de configuración de Violation Detector

En tiempo de ejecución, la herramienta Violation Detector requiere un archivo de configuración. Los parámetros de este archivo determinan a qué recursos de DynamoDB puede obtener acceso Violation Detector y cuánto rendimiento aprovisionado puede consumir. En la siguiente tabla se describen estos parámetros.

Nombre del parámetro Descripción ¿Obligatorio?

awsCredentialsFile

Nombre completo de un archivo que contiene las credenciales de AWS. El archivo de credenciales debe tener el siguiente formato:

accessKey = access_key_id_goes_here
secretKey = secret_key_goes_here

Sí

dynamoDBRegion

Región de AWS en la que la reside la tabla. Por ejemplo: us-west-2.

Sí

tableName

 Nombre de la tabla de DynamoDB que se va a examinar.

Sí

gsiHashKeyName

Nombre de la clave de partición del índice.

Sí

gsiHashKeyType

Tipo de datos de la clave de partición del índice: String, Number o Binary:

S | N | B

Sí

gsiRangeKeyName

Nombre de la clave de ordenación del índice. No especifique este parámetro si el índice solo tiene una clave principal simple (clave de partición).

No

gsiRangeKeyType

Tipo de datos de la clave de ordenación del índice: String, Number o Binary:

S | N | B

No especifique este parámetro si el índice solo tiene una clave principal simple (clave de partición).

No

recordDetails

Indica si se deben escribir todos los detalles de las infracciones de claves de índice en el archivo de resultados. Si se establece en true (valor predeterminado), se registra toda la información sobre los elementos infractores. Si se establece en false, solo se registra el número de infracciones.

No

recordGsiValueInViolationRecord

Indica si se deben escribir los valores de las claves de índice infractoras en el archivo de resultados. Si se establece en true (predeterminado), se registran los valores de las claves. Si se establece en false, los valores de las claves no se registran.

No

detectionOutputPath

Ruta completa del archivo de resultados de Violation Detector;. Este parámetro es compatible con la escritura en un directorio local o en Amazon Simple Storage Service (Amazon S3). A continuación se muestran algunos ejemplos:

detectionOutputPath = //local/path/filename.csv

detectionOutputPath = s3://bucket/filename.csv

La información del archivo de resultados aparece en formato CSV (valores separados por comas). Si no se establece detectionOutputPath, el archivo de resultados se denomina violation_detection.csv y se escribe en el directorio de trabajo actual.

No

numOfSegments

El número de segmentos de examen en paralelo que se utilizarán cuando Violation Detector analice la tabla. El valor predeterminado es 1, lo que significa que la tabla se examina de forma secuencial. Si el valor es 2 o superior, entonces Violation Detector dividirá la tabla en esa cantidad de segmentos lógicos y un número igual de subprocesos de examen.

El ajuste máximo de numOfSegments es 4096.

En el caso de las tablas de mayor tamaño, un examen en paralelo suele resultar más rápido que un examen secuencial. Además, si la tabla es lo bastante grande para abarcar varias particiones, un examen en paralelo distribuye su actividad de lectura de manera uniforme entre varias particiones.

Para obtener más información sobre los análisis en paralelo en DynamoDB, consulte Análisis paralelo.

No

numOfViolations

Límite superior de infracciones de claves de índice que se escribirán en el archivo de resultados. Si se establece en -1 (valor predeterminado), se examina toda la tabla. Si se establece en un número entero positivo, entonces Violation Detector se detendrá después de haber detectado esa cantidad de infracciones.

No

numOfRecords

Número de elementos de la tabla que se va a examinar. Si se establece en -1 (valor predeterminado), se examinará toda la tabla. Si se establece en un número entero positivo, entonces Violation Detector se detendrá después de haber examinado esa cantidad de elementos en la tabla.

No

readWriteIOPSPercent

Regula el porcentaje de unidades de capacidad de lectura provisionadas que se consumen durante un examen de la tabla. Los valores válidos van de 1 a 100. El valor predeterminado (25) significa que Violation Detector consumirá no más del 25 % del rendimiento de lectura aprovisionado de la tabla.

No

correctionInputPath

Ruta completa del archivo de información de entrada de corrección de Violation Detector. Si ejecuta Violation Detector en modo de corrección, el contenido de este archivo se usa para modificar o eliminar los elementos de datos de la tabla que infringen el índice secundario global.

El formato del archivo correctionInputPath es el mismo que el del archivo detectionOutputPath. Esto permite procesar el resultado del modo de detección como información de entrada en el modo de corrección.

No

correctionOutputPath

Ruta completa del archivo de resultados de corrección de Violation Detector. Este archivo se crea solo si existen errores de actualización.

Este parámetro es compatible con la escritura en un directorio local o en Amazon S3. A continuación se muestran algunos ejemplos:

correctionOutputPath = //local/path/filename.csv

correctionOutputPath = s3://bucket/filename.csv

La información del archivo de resultados aparece en formato CSV. Si no se establece correctionOutputPath, el archivo de resultados se denomina violation_update_errors.csv y se escribe en el directorio de trabajo actual.

No

Detección

Para detectar infracciones de claves de índice, use Violation Detector con la opción de línea de comandos --detect. Para ver cómo funciona esta opción, tomemos la tabla ProductCatalog. A continuación se muestra una lista de elementos de la tabla. Solo se muestran la clave principal (Id) y el atributo Price.

Id (clave principal) Precio
101 5
102 20
103 200
201 100
202 200
203 300
204 400
205 500

Todos los valores de Price son de tipo Number. No obstante, dado que en DynamoDB no se usan esquemas, es posible agregar un elemento con un valor de Price no numérico. Por ejemplo, supongamos que agrega otro elemento a la tabla ProductCatalog.

Id (clave principal) Precio
999 "Hello"

Ahora, la tabla contiene un total de nueve elementos.

Ahora agrega un nuevo índice secundario global a la tabla: PriceIndex. La clave principal de este índice es una clave de partición, Price, que es de tipo Number. Después de crearlo, el índice contendrá ocho elementos. Sin embargo, la tabla ProductCatalog tiene nueve elementos. El motivo de esta discrepancia es que, aunque el valor "Hello" es de tipo String, la clave principal de PriceIndex es de tipo Number. El valor String infringe la clave del índice secundario global, por lo que no está presente en el índice.

Para usar Violation Detector en esta situación, primero se crea un archivo de configuración, como el siguiente.


# 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

A continuación, se ejecuta el Violation Detector como en el siguiente ejemplo.

$  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 el parámetro de configuración recordDetails se establece en true, entonces Violation Detector escribe los detalles de cada infracción en el archivo de resultados, como en el siguiente ejemplo.

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

El archivo de salida está en formato CSV. La primera línea del archivo es un encabezado, seguido de un registro por cada elemento que infringe la clave del índice. Los campos de estos registros de infracción son los siguientes:

  • Table hash key: valor de la clave de partición del elemento de la tabla.

  • Table range key: valor de la clave de clasificación del elemento de la tabla.

  • GSI hash key value: valor de la clave de partición del índice secundario global.

  • GSI hash key violation type: puede ser Type Violation o Size Violation.

  • GSI hash key violation description: causa de la infracción.

  • GSI hash key update value (FOR USER): en el modo de corrección, nuevo valor suministrado por el usuario para el atributo.

  • GSI range key values: el valor de la clave de clasificación del índice secundario global.

  • GSI range key violation type: puede ser Type Violation o Size Violation.

  • GSI range key violation description: causa de la infracción.

  • GSI range key update value (FOR USER): en el modo de corrección, nuevo valor suministrado por el usuario para el atributo.

  • Delete blank attribute when updating (Y/N): en el modo de corrección, determina si el elemento infractor se eliminará (Y) o se conservará (N) en la tabla, pero solamente si cualquiera de los campos siguientes está en blanco:

    • GSI Hash Key Update Value(FOR USER)

    • GSI Range Key Update Value(FOR USER)

    Si alguno de estos campos no está en blanco, entonces Delete Blank Attribute When Updating(Y/N) no surte ningún efecto.

nota

El formato de los resultados puede variar, en función del archivo de configuración y de las opciones de la línea de comandos. Por ejemplo, si la tabla tiene una clave principal simple (sin clave de ordenación), no habrá ningún campo de clave de ordenación en el resultado.

Los registros de infracción del archivo podrían no estar ordenados.

Corrección

Para corregir infracciones de claves de índice, use Violation Detector con la opción de línea de comandos --correct. En el modo de corrección, Violation Detector lee el archivo de información de entrada especificado por el parámetro correctionInputPath. Este archivo tiene el mismo formato que el archivo detectionOutputPath, lo que permite utilizar el resultado de la detección como información de entrada para la corrección.

Violation Detector ofrece dos maneras distintas de corregir las infracciones de claves de índice:

  • Eliminar las infracciones: se eliminan los elementos de la tabla cuyos valores de atributos infringen alguna clave.

  • Actualizar las infracciones: se actualizan los elementos de la tabla, para lo cual se sustituyen los atributos infractores por otros que no causan ninguna infracción.

En ambos casos, puede utilizar el archivo de resultados del modo de detección como información de entrada para el modo de corrección.

Si continuamos con el ejemplo anterior de ProductCatalog, supongamos que desea eliminar el elemento infractor de la tabla. Para ello, utilizamos la línea de comandos siguiente.

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

En este momento, le pedirá que confirme si desea eliminar los elementos infractores.

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

Ahora, tanto ProductCatalog como PriceIndex tienen el mismo número de elementos.