인덱스 키 위반 검색 및 수정 - Amazon DynamoDB
위반 감지기 다운로드 및 실행위반 감지기 구성 파일감지수정

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

인덱스 키 위반 검색 및 수정

Amazon DynamoDB는 글로벌 보조 인덱스 생성의 채우기 단계 중 테이블의 각 항목을 검사하여 인덱스에 포함하기에 적합한지 여부를 결정합니다. 일부 항목은 인덱스 키 위반을 유발하여 적합하지 않을 수도 있습니다. 이러한 경우에는 항목이 테이블에서는 유지되지만 인덱스에 해당 항목에 상응하는 키가 없습니다.

인덱스 키 위반은 다음 상황에서 발생합니다.

  • 속성 값과 인덱스 키 스키마 데이터 형식 간에 데이터 형식이 일치하지 않습니다. 예를 들어 GameScores 테이블의 항목 중 하나가 형식이 String인 TopScore 값을 하나 가지고 있었다고 가정해 보겠습니다. 파티션 키 TopScore이고 형식이 Number인 글로벌 보조 인덱스를 추가했다면 테이블의 해당 항목이 인덱스 키를 위반하게 됩니다.

  • 테이블의 속성 값이 인덱스 키 속성의 최대 길이를 초과합니다. 파티션 키의 최대 길이는 2,048바이트이고 정렬 키의 최대 길이는 1,024바이트입니다. 테이블에서 해당 속성 값 중 하나가 이러한 제한을 초과하는 경우 테이블에서 이 항목은 인덱스 키를 위반합니다.

참고

인덱스 키로 사용되는 속성에 대해 문자열 또는 이진 속성 값이 설정된 경우 속성 값의 길이는 0보다 커야 합니다. 그렇지 않으면 테이블의 항목이 인덱스 키를 위반하게 됩니다.

이 도구는 현재 이 인덱스 키 위반에 플래그를 지정하지 않습니다.

인덱스 키 위반이 발생하면 중단 없이 채우기 단계가 계속되지만, 위반 항목이 인덱스에 포함되지 않습니다. 채우기 단계가 끝나면 새 인덱스의 키 스키마를 위반하는 모든 항목 쓰기 작업은 거부됩니다.

테이블에서 인덱스 키를 위반하는 속성 값을 식별하여 수정하려면 위반 감지기 도구를 사용합니다. 위반 감지기를 실행하려면 스캔할 테이블의 이름, 글로벌 보조 인덱스 파티션 키 및 정렬 키의 이름과 데이터 형식, 인덱스 키 위반이 발생하는 경우 취할 조치를 지정하는 구성 파일을 생성합니다. 위반 감지기는 다음 두 가지 모드 중 하나로 실행할 수 있습니다.

  • 감지 모드 - 인덱스 키 위반을 감지합니다. 감지 모드를 사용하여 테이블에서 글로벌 보조 인덱스의 키 위반을 초래하는 항목을 보고합니다. 원할 경우 이러한 위반 테이블 항목을 발견되는 즉시 삭제하도록 요청할 수도 있습니다. 검색 모드의 출력이 파일에 작성되어 추후 분석용으로 사용할 수 있습니다.

  • 수정 모드 - 인덱스 키 위반을 수정합니다. 수정 모드에서는 위반 감지기가 감지 모드의 출력 파일과 동일한 형식의 입력 파일을 읽습니다. 수정 모드에서는 입력 파일의 레코드를 읽고 각 레코드마다 테이블에서 해당 항목을 삭제하거나 업데이트합니다. 항목을 업데이트하도록 선택하는 경우 입력 파일을 편집하여 이러한 업데이트에 대한 알맞은 값을 설정해야 합니다.

위반 감지기 다운로드 및 실행

위반 감지기는 실행 가능한 Java 아카이브(.jar 파일)로 제공되며 Windows, macOS 또는 Linux 컴퓨터에서 실행됩니다. 위반 감지기를 사용하려면 Java 1.7 이상 및 Apache Maven이 필요합니다.

README.md 파일의 지침에 따라 Mavn을 사용하여 위반 감지기를 다운로드 및 설치합니다.

위반 감지기를 시작하려면 ViolationDetector.java를 작성했던 디렉터리로 이동하여 다음 명령을 입력합니다.

java -jar ViolationDetector.jar [options]

위반 감지기 명령줄에서는 다음 옵션을 사용할 수 있습니다.

  • -h | --help - 위반 감지기의 사용법 요약 및 옵션을 출력합니다.

  • -p | --configFilePath value - 위반 감지기 구성 파일의 정규화된 이름입니다. 자세한 정보는 위반 감지기 구성 파일을 참조하십시오.

  • -t | --detect value - 테이블에서 인덱스 키 위반을 감지하고 위반 감지기 출력 파일에 기록합니다. 이 파라미터의 값이 keep으로 설정되면 키 위반 항목이 수정되지 않습니다. 값이 delete로 설정되면 키 위반 항목이 테이블에서 삭제됩니다.

  • -c | --correct value - 입력 파일에서 인덱스 키 위반을 읽고 테이블에서 이러한 항목에 대한 수정 작업을 수행합니다. 이 파라미터의 값이 update로 설정되면 키 위반 항목이 위반하지 않는 새 값으로 업데이트됩니다. 값이 delete로 설정되면 키 위반 항목이 테이블에서 삭제됩니다.

위반 감지기 구성 파일

런타임 시, 위반 감지기 도구에는 구성 파일이 필요합니다. 이 파일의 파라미터는 위반 감지기에서 액세스할 수 있는 DynamoDB 리소스와 이 도구에서 사용할 수 있는 프로비저닝된 처리량을 결정합니다. 다음 표는 이러한 파라미터에 대해 설명합니다.

파라미터 이름 설명 필수?

awsCredentialsFile

AWS 자격 증명을 포함하는 파일의 정규화된 이름입니다. 자격 증명 파일은 다음 형식이어야 합니다.

accessKey = access_key_id_goes_here
secretKey = secret_key_goes_here

예

dynamoDBRegion

테이블이 상주하는 AWS 리전입니다. 예: us-west-2.

예

tableName

 스캔할 DynamoDB 테이블의 이름입니다.

예

gsiHashKeyName

인덱스 파티션 키의 이름입니다.

예

gsiHashKeyType

인덱스 파티션 키의 데이터 형식(String, Number 또는 Binary).

S | N | B

예

gsiRangeKeyName

인덱스 정렬 키의 이름입니다. 인덱스에 단순 기본 키(파티션 키)만 있는 경우 이 파라미터를 지정하지 마세요.

아니요

gsiRangeKeyType

인덱스 정렬 키의 데이터 형식입니다(String, Number 또는 Binary).

S | N | B

인덱스에 단순 기본 키(파티션 키)만 있는 경우 이 파라미터를 지정하지 마세요.

아니요

recordDetails

인덱스 키 위반에 대한 자세한 정보를 출력 파일에 작성할지 여부를 나타냅니다. true(기본값)로 설정하면 위반 항목에 대한 전체 정보가 보고됩니다. false로 설정하면 위반 수만 보고됩니다.

아니요

recordGsiValueInViolationRecord

위반 인덱스 키의 값을 출력 파일에 작성할지 여부를 나타냅니다. true(기본값)로 설정하면 키 값이 보고됩니다. false로 설정하면 키 값이 보고되지 않습니다.

아니요

detectionOutputPath

위반 감지기 출력 파일의 전체 경로입니다. 이 파라미터는 로컬 디렉터리 또는 Amazon Simple Storage Service(Amazon S3)에 쓰기를 지원합니다. 예를 들면 다음과 같습니다.

detectionOutputPath = //local/path/filename.csv

detectionOutputPath = s3://bucket/filename.csv

출력 파일의 정보가 CSV 형식(쉼표로 구분된 값)으로 표시됩니다. detectionOutputPath를 설정하지 않는 경우 출력 파일의 이름은 violation_detection.csv이고 현재 작업 디렉터리에 작성됩니다.

아니요

numOfSegments

위반 감지기에서 테이블을 스캔할 때 사용할 병렬 스캔 세그먼트 수입니다. 기본값은 1이며, 이는 테이블이 순차적으로 스캔됨을 뜻합니다. 값이 2 이상이면 위반 감지기가 테이블을 여러 논리 세그먼트, 그리고 이와 동일한 스캔 스레드 수로 나눕니다.

numOfSegments의 최대 설정은 4096입니다.

대형 테이블의 경우 병렬 스캔이 일반적으로 순차 스캔보다 빠릅니다. 또한, 테이블이 매우 커서 여러 파티션에 걸쳐 있는 경우 병렬 스캔을 수행하면 읽기 작업이 여러 파티션에 고르게 분산됩니다.

DynamoDB의 병렬 스캔에 대한 자세한 내용은 병렬 스캔 단원을 참조하세요.

아니요

numOfViolations

출력 파일에 작성할 인덱스 키 위반의 상한 값입니다. -1(기본값)로 설정하면 전체 테이블이 스캔됩니다. 양의 정수로 설정하면 위반 감지기가 해당 위반 수에 도달한 후 중지됩니다.

아니요

numOfRecords

테이블에서 스캔할 항목 수입니다. -1(기본값)로 설정하면 전체 테이블이 스캔됩니다. 양의 정수로 설정하면 위반 감지기가 테이블에서 해당 개수의 항목을 스캔한 후 중지됩니다.

아니요

readWriteIOPSPercent

테이블 스캔 중에 사용되는 프로비저닝된 읽기 용량 단위의 백분율을 조정합니다. 사용할 수 있는 값은 1 ~ 100입니다. 기본값(25)을 사용하면 위반 감지기가 테이블의 프로비저닝된 읽기 처리량 중 25% 이하만 사용합니다.

아니요

correctionInputPath

위반 감지기 수정 입력 파일의 전체 경로입니다. 위반 감지기를 수정 모드로 실행하면 이 파일의 내용이 테이블에서 글로벌 보조 인덱스를 위반하는 데이터 항목을 수정하거나 삭제하는 데 사용됩니다.

correctionInputPath 파일의 형식은 detectionOutputPath 파일의 형식과 동일합니다. 따라서 검색 모드의 출력을 수정 모드의 입력으로 처리할 수 있습니다.

아니요

correctionOutputPath

위반 감지기 수정 출력 파일의 전체 경로입니다. 이 파일은 업데이트 오류가 있는 경우에만 생성됩니다.

이 파라미터는 로컬 디렉터리 또는 Amazon S3에 쓰기를 지원합니다. 예를 들면 다음과 같습니다.

correctionOutputPath = //local/path/filename.csv

correctionOutputPath = s3://bucket/filename.csv

출력 파일의 정보가 CSV 형식으로 표시됩니다. correctionOutputPath를 설정하지 않는 경우 출력 파일의 이름은 violation_update_errors.csv이고 현재 작업 디렉터리에 작성됩니다.

아니요

감지

인덱스 키 위반을 감지하려면 위반 감지기를 --detect 명령줄 옵션과 함께 사용합니다. 이 옵션의 작동 방식을 알아보기 위해 DynamoDB에서 테이블 생성 및 코드 예시에 대한 데이터 로드에 표시된 ProductCatalog을 살펴보겠습니다. 다음은 테이블의 항목 목록입니다. 기본 키(Id)와 Price 속성만 표시됩니다.

Id(프라이머리 키) 가격
101 5
102 20
103 200
201 100
202 200
203 300
204 400
205 500

Price의 모든 값은 Number 형식입니다. 하지만 DynamoDB에는 스키마가 없으므로 숫자가 아닌 Price 값이 지정된 항목을 추가할 수 있습니다. 예를 들어 또 하나의 항목을 ProductCatalog 테이블에 추가한다고 가정해 보겠습니다.

Id(프라이머리 키) 가격
999 "Hello"

이제 테이블에는 총 9개 항목이 있습니다.

이제 테이블에 새 글로벌 보조 인덱스 PriceIndex를 추가합니다. 이 인덱스의 기본 키는 Number 형식의 파티션 키 Price입니다. 인덱스가 빌드되면 인덱스에 8개 항목이 포함되지만 ProductCatalog 테이블에는 9개 항목이 있습니다. 이러한 불일치가 발생한 이유는 "Hello" 값은 String 형식이지만, PriceIndex의 기본 키는 Number 형식이기 때문입니다. String 값은 글로벌 보조 인덱스 키를 위반하므로 인덱스에 없습니다.

이 시나리오에서 위반 감지기를 사용하려면 먼저 다음과 같은 구성 파일을 만듭니다.


# 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

그 다음으로, 다음 예제와 같이 위반 감지기를 실행합니다.

$  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로 설정하면 다음 예에서처럼 위반 감지기에서 각 위반에 대한 자세한 정보를 출력 파일에 기록합니다.

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 형식입니다. 이 파일의 첫 번째 줄은 헤더이며, 그 뒤에는 인덱스 키를 위반하는 항목당 한 개 레코드가 이어집니다. 이러한 위반 레코드의 필드는 다음과 같습니다.

  • 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)이 적용되지 않습니다.

참고

출력 형식은 구성 파일 및 명령줄 옵션에 따라 다를 수 있습니다. 예를 들어 테이블이 단순 기본 키(정렬 키 없음)를 가질 경우 출력에 정렬 키 필드가 없습니다.

파일의 위반 레코드는 순서가 정렬되어 있지 않을 수도 있습니다.

수정

인덱스 키 위반을 수정하려면 위반 감지기를 --correct 명령줄 옵션과 함께 사용합니다. 수정 모드에서는 위반 감지기가 correctionInputPath 파라미터에 지정된 입력 파일을 읽습니다. 이 파일의 형식은 detectionOutputPath 파일과 동일하므로 검색의 출력을 수정의 입력으로 사용할 수 있습니다.

위반 감지기에서는 인덱스 키 위반을 수정할 수 있는 두 가지 방법을 제공합니다.

  • 위반 삭제 - 위반하는 속성 값이 있는 테이블 항목을 삭제합니다.

  • 위반 업데이트 - 위반하는 속성 값을 위반하지 않는 값으로 바꾸어 테이블 항목을 업데이트합니다.

어느 경우든, 검색 모드의 출력 파일을 수정 모드의 입력으로 사용할 수 있습니다.

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

이제는 ProductCatalog와 PriceIndex의 항목 수가 동일합니다.