# DynamoDB의 항목 및 속성 작업 Amazon DynamoDB에서 *항목*은 속성 모음입니다. 각 속성마다 이름과 값이 있습니다. 속성 값은 스칼라, 세트 또는 문서 유형일 수 있습니다. 자세한 내용은 [Amazon DynamoDB: 작동 방식](HowItWorks.md) 섹션을 참조하세요. DynamoDB는 기본 CRUD(생성/읽기/업데이트/삭제) 기능을 위한 다음 네 가지 작업을 제공합니다. 이 모든 작업은 원자성입니다. + `PutItem` - 항목을 생성합니다. + `GetItem` - 항목을 읽습니다. + `UpdateItem` - 항목을 업데이트합니다. + `DeleteItem` - 항목을 삭제합니다. 이러한 각 작업에서는 작업할 항목의 기본 키를 지정해야 합니다. 예를 들어, `GetItem`을 사용하여 항목을 읽으려면 해당 항목에 대한 파티션 키와 정렬 키(적용 가능한 경우)를 지정해야 합니다. 네 개의 기본 CRUD 작업에 추가하여 DynamoDB는 다음과 같은 작업도 제공합니다. + `BatchGetItem` - 하나 이상의 테이블에서 최대 100개의 항목을 읽습니다. + `BatchWriteItem` - 하나 이상의 테이블에서 최대 25개의 항목을 생성하거나 삭제합니다. 이러한 배치 작업은 여러 CRUD 작업을 단일 요청으로 결합니다. 또한 배치 작업은 항목 읽기 및 쓰기를 병렬로 실행하여 응답 지연 시간을 최소화합니다. 이 섹션에서는 이 작업을 사용하는 방법을 설명하며 조건부 업데이트 및 원자성 카운터와 같은 관련 주제도 다룹니다. 이 섹션에는 AWS SDK를 사용하는 예제 코드도 포함되어 있습니다. **Topics** + [DynamoDB 항목 크기 및 형식](CapacityUnitCalculations.md) + [항목 읽기](#WorkingWithItems.ReadingData) + [항목 쓰기](#WorkingWithItems.WritingData) + [반환 값](#WorkingWithItems.ReturnValues) + [배치 작업](#WorkingWithItems.BatchOperations) + [원자성 카운터](#WorkingWithItems.AtomicCounters) + [조건부 쓰기](#WorkingWithItems.ConditionalUpdate) + [DynamoDB에서 표현식 사용](Expressions.md) + [DynamoDB에서 TTL(Time To Live) 사용](TTL.md) + [DynamoDB에서 테이블 쿼리](Query.md) + [DynamoDB에서 테이블 스캔](Scan.md) + [PartiQL - Amazon DynamoDB용 SQL 호환 쿼리 언어](ql-reference.md) + [항목 작업: Java](JavaDocumentAPIItemCRUD.md) + [항목 작업: .NET](LowLevelDotNetItemCRUD.md) ## 항목 읽기 DynamoDB 테이블에서 항목을 읽으려면 `GetItem` 작업을 사용합니다. 원하는 항목의 기본 키와 함께 테이블 이름을 제공해야 합니다. **Example** 다음은 AWS CLI 테이블에서 항목을 읽는 방법을 보여주는 `ProductCatalog` 예제입니다. ``` aws dynamodb get-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}' ``` **참고** `GetItem`에는 부분만이 아닌 *전체* 기본 키를 지정해야 합니다. 예를 들어 테이블에 복합 기본 키(파티션 키 및 정렬 키)가 있는 경우 파티션 키 값과 정렬 키 값을 공급해야 합니다. 기본적으로 `GetItem` 요청은 최종적으로 일관된 읽기를 수행합니다. 그 대신 `ConsistentRead` 파라미터를 사용하여 강력한 일관된 읽기를 요청할 수 있습니다. (이 방법은 추가 읽기 용량 단위를 사용하지만 가장 최신 버전의 항목을 반환합니다.) `GetItem`은 모든 항목의 속성을 반환합니다. *프로젝션 표현식*을 사용하여 속성의 일부만 반환할 수 있습니다. 자세한 내용은 [DynamoDB에서 프로젝션 표현식 사용](Expressions.ProjectionExpressions.md) 섹션을 참조하세요. `GetItem`에서 사용된 읽기 용량 단위 수를 반환하려면 `ReturnConsumedCapacity` 파라미터를 `TOTAL`로 설정합니다. **Example** 다음 AWS Command Line Interface(AWS CLI) 예제에는 몇 가지 `GetItem` 파라미터 옵션이 나와 있습니다. ``` aws dynamodb get-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}' \ --consistent-read \ --projection-expression "Description, Price, RelatedItems" \ --return-consumed-capacity TOTAL ``` ## 항목 쓰기 DynamoDB 테이블에서 항목을 생성, 업데이트 또는 삭제하려면 다음 작업 중 하나를 사용합니다. + `PutItem` + `UpdateItem` + `DeleteItem` 이러한 각각의 작업마다 일부가 아닌 전체 기본 키를 지정해야 합니다. 예를 들어 테이블에 복합 기본 키(파티션 키 및 정렬 키)가 있는 경우 파티션 키 값과 정렬 키 값을 제공해야 합니다. 이러한 작업 중 하나에서 사용된 쓰기 용량 단위 수를 반환하려면 `ReturnConsumedCapacity` 파라미터를 다음 중 하나로 설정합니다. + `TOTAL` - 사용된 총 쓰기 용량 단위 수를 반환합니다. + `INDEXES` - 사용된 총 쓰기 용량 단위 수와 작업의 영향을 받은 테이블 및 보조 인덱스의 소계를 반환합니다. + `NONE` - 쓰기 용량 세부 정보를 반환하지 않습니다. (이 값이 기본값입니다.) ### PutItem `PutItem` 새 항목을 만듭니다. 동일 키의 항목이 테이블이 이미 존재하는 경우 해당 항목이 새 항목으로 대체됩니다. **Example** `Thread` 테이블에 새 항목을 씁니다. `Thread`에 대한 기본 키는 `ForumName`(파티션 키)와 `Subject`(정렬 키)로 구성됩니다. ``` aws dynamodb put-item \ --table-name Thread \ --item file://item.json ``` `--item`의 인수는 `item.json` 파일에 저장됩니다. ``` { "ForumName": {"S": "Amazon DynamoDB"}, "Subject": {"S": "New discussion thread"}, "Message": {"S": "First post in this thread"}, "LastPostedBy": {"S": "fred@example.com"}, "LastPostDateTime": {"S": "201603190422"} } ``` ### UpdateItem 지정된 키가 있는 항목이 존재하지 않으면 `UpdateItem`은 새 항목을 생성합니다. 그렇지 않으면 기존 항목의 속성을 수정합니다. *업데이트 표현식*을 사용하여 수정하려는 속성과 새 값을 지정합니다. 자세한 내용은 [DynamoDB에서 업데이트 표현식 사용](Expressions.UpdateExpressions.md) 섹션을 참조하세요. 업데이트 표현식 내에서는 표현식 속성 값을 실제 값에 대한 자리 표시자로 사용합니다. 자세한 내용은 [DynamoDB에서 표현식 속성 값 사용](Expressions.ExpressionAttributeValues.md) 섹션을 참조하세요. **Example** `Thread` 항목에서 다양한 속성을 수정합니다. 선택적 `ReturnValues` 파라미터는 업데이트 후 나타나는 항목을 표시합니다. 자세한 내용은 [반환 값](#WorkingWithItems.ReturnValues) 섹션을 참조하세요. ``` aws dynamodb update-item \ --table-name Thread \ --key file://key.json \ --update-expression "SET Answered = :zero, Replies = :zero, LastPostedBy = :lastpostedby" \ --expression-attribute-values file://expression-attribute-values.json \ --return-values ALL_NEW ``` `--key`의 인수는 `key.json` 파일에 저장됩니다. ``` { "ForumName": {"S": "Amazon DynamoDB"}, "Subject": {"S": "New discussion thread"} } ``` `--expression-attribute-values`의 인수는 `expression-attribute-values.json` 파일에 저장됩니다. ``` { ":zero": {"N":"0"}, ":lastpostedby": {"S":"barney@example.com"} } ``` ### DeleteItem `DeleteItem`는 지정된 키가 있는 항목을 삭제합니다. **Example** 다음 AWS CLI 예제는 `Thread` 항목을 삭제하는 방법을 보여줍니다. ``` aws dynamodb delete-item \ --table-name Thread \ --key file://key.json ``` ## 반환 값 경우에 따라서는 DynamoDB에서 수정 전 또는 후에 나타난 특정 속성 값을 반환하도록 할 수 있습니다. `PutItem`, `UpdateItem` 및 `DeleteItem` 작업에는 수정 전 또는 후의 속성 값을 반환하기 위해 사용할 수 있는 `ReturnValues` 파라미터가 있습니다. `ReturnValues`의 기본값은 DynamoDB에서 수정된 속성에 대한 정보를 반환하지 않는 `NONE`입니다. 다음은 DynamoDB API 작업에서 구성되는 `ReturnValues`에 대한 기타 유효한 설정입니다. ### PutItem + `ReturnValues`: `ALL_OLD` + 기존 항목을 덮어쓰면 `ALL_OLD`는 덮어쓰기 전에 나타난 전체 항목을 반환합니다. + 존재하지 않는 항목을 쓰면 `ALL_OLD`는 효과를 나타내지 않습니다. ### UpdateItem `UpdateItem`의 가장 일반적인 용도는 기존 항목을 업데이트하는 것입니다. 하지만 실제로 `UpdateItem`은 항목이 아직 없는 경우 항목을 자동으로 생성하는 *upsert*를 수행합니다. + `ReturnValues`: `ALL_OLD` + 기존 항목을 업데이트하면 `ALL_OLD`는 업데이트 전에 나타난 전체 항목을 반환합니다. + 존재하지 않는 항목을 업데이트하면(upsert) `ALL_OLD`는 효과를 나타내지 않습니다. + `ReturnValues`: `ALL_NEW` + 기존 항목을 업데이트하면 `ALL_NEW`는 업데이트 후에 나타난 전체 항목을 반환합니다. + 존재하지 않는 항목을 업데이트하면(upsert) `ALL_NEW`는 전체 항목을 반환합니다. + `ReturnValues`: `UPDATED_OLD` + 기존 항목을 업데이트하면 `UPDATED_OLD`는 업데이트 전에 나타난 업데이트된 속성만 반환합니다. + 존재하지 않는 항목을 업데이트하면(upsert) `UPDATED_OLD`는 효과를 나타내지 않습니다. + `ReturnValues`: `UPDATED_NEW` + 기존 항목을 업데이트하면 `UPDATED_NEW`는 업데이트 후에 나타난 영향을 받은 속성만 반환합니다. + 존재하지 않는 항목을 업데이트하면(upsert) `UPDATED_NEW`는 업데이트 후에 나타나는 업데이트된 속성만 반환합니다. ### DeleteItem + `ReturnValues`: `ALL_OLD` + 기존 항목을 삭제하면 `ALL_OLD`는 삭제하기 전에 나타난 전체 항목을 반환합니다. + 존재하지 않는 항목을 삭제하면 `ALL_OLD`는 데이터를 반환하지 않습니다. ## 배치 작업 여러 항목을 읽거나 써야 하는 애플리케이션의 경우 DynamoDB는 `BatchGetItem` 및 `BatchWriteItem` 작업을 제공합니다. 이러한 작업을 사용하면 애플리케이션과 DynamoDB 간의 네트워크 왕복 수가 감소될 수 있습니다. 또한 DynamoDB는 개별 읽기 또는 쓰기 작업을 병렬로 수행합니다. 애플리케이션은 동시성 또는 스레딩을 관리할 필요 없이 이 병렬 실행에서 이익을 얻을 수 있습니다. 배치 작업은 본질적으로 다중 읽기 또는 쓰기 요청에 대한 래퍼입니다. 예를 들어, `BatchGetItem` 요청에 5개 항목이 포함되어 있으면 DynamoDB는 사용자를 대신하여 5개의 `GetItem` 작업을 수행합니다. 마찬가지로, `BatchWriteItem` 요청에 추가 요청 두 개와 삭제 요청 네 개가 포함되어 있으면 DynamoDB는 `PutItem` 요청 두 개와 `DeleteItem` 요청 네 개를 수행합니다. 일반적으로 배치에 있는 *모든* 요청이 실패하지 않는 한 배치 작업은 실패하지 않습니다. 예를 들어 `BatchGetItem` 작업을 수행하지만 배치에 있는 개별 `GetItem` 요청 중 하나가 실패한다고 가정합니다. 이 경우 `BatchGetItem`은 실패한 `GetItem` 요청에서 키와 데이터를 반환합니다. 배치에 있는 기타 `GetItem` 요청은 영향을 받지 않습니다. ### BatchGetItem 단일 `BatchGetItem` 작업은 최대 100개의 개별 `GetItem` 요청을 포함할 수 있으며, 최대 16MB의 데이터를 검색할 수 있습니다. 또한 `BatchGetItem` 작업은 여러 테이블에서 항목을 검색할 수 있습니다. **Example** 일부 속성만 반환하는 프로젝션 표현식을 사용하여 `Thread` 테이블에서 두 개의 항목을 검색합니다. ``` aws dynamodb batch-get-item \ --request-items file://request-items.json ``` `--request-items`의 인수는 `request-items.json` 파일에 저장됩니다. ``` { "Thread": { "Keys": [ { "ForumName":{"S": "Amazon DynamoDB"}, "Subject":{"S": "DynamoDB Thread 1"} }, { "ForumName":{"S": "Amazon S3"}, "Subject":{"S": "S3 Thread 1"} } ], "ProjectionExpression":"ForumName, Subject, LastPostedDateTime, Replies" } } ``` ### BatchWriteItem `BatchWriteItem` 작업은 최대 25개의 개별 `PutItem` 및 `DeleteItem` 요청을 포함할 수 있으며, 최대 16MB의 데이터를 쓸 수 있습니다. (개별 항목의 최대 크기는 400KB입니다.) 또한 `BatchWriteItem` 작업은 여러 테이블에서 항목을 추가하거나 삭제할 수 있습니다. **참고** `BatchWriteItem`은 `UpdateItem` 요청을 지원하지 않습니다. **Example** `ProductCatalog` 테이블에 두 개의 항목을 추가합니다. ``` aws dynamodb batch-write-item \ --request-items file://request-items.json ``` `--request-items`의 인수는 `request-items.json` 파일에 저장됩니다. ``` { "ProductCatalog": [ { "PutRequest": { "Item": { "Id": { "N": "601" }, "Description": { "S": "Snowboard" }, "QuantityOnHand": { "N": "5" }, "Price": { "N": "100" } } } }, { "PutRequest": { "Item": { "Id": { "N": "602" }, "Description": { "S": "Snow shovel" } } } } ] } ``` ## 원자성 카운터 `UpdateItem` 작업을 사용하여 *원자성 카운터*를 구현할 수 있습니다. 이는 다른 쓰기 요청과 충돌하지 않고 조건 없이 증감되는 숫자 속성입니다. 모든 쓰기 요청은 수신된 순서대로 적용됩니다. 원자성 카운터가 있으면 업데이트는 idempotent 방식이 아닙니다. 다시 말해서, `UpdateItem`을 호출할 때마다 숫자 값이 증가하거나 감소합니다. 원자성 카운터를 업데이트하는 데 사용되는 증분 값이 양수이면 수가 많게 계산될 수 있습니다. 증분 값이 음수이면 수가 적게 계산될 수 있습니다. 원자성 카운터를 사용하여 웹 사이트의 방문객 수를 계속 추적할 수 있습니다. 이 경우 애플리케이션은 현재 값과 상관없이 숫자 값을 계속 증가시킵니다. `UpdateItem` 작업이 실패할 경우 애플리케이션은 작업을 단순히 재시도할 수 있습니다. 이렇게 하면 카운터를 두 번 업데이트할 위험이 있지만, 웹 사이트 방문객 수를 약간 많게 또는 적게 계산하는 것을 허용할 수 있습니다. 수를 많게 또는 적게 계산하는 것을 허용할 수 없는 경우에는(예: 은행 애플리케이션) 원자성 카운터가 적합하지 않습니다. 이러한 경우 원자성 카운터 대신 조건부 업데이트를 사용하는 것이 더 안전합니다. 자세한 내용은 [수치 속성 증가 및 감소](Expressions.UpdateExpressions.md#Expressions.UpdateExpressions.SET.IncrementAndDecrement) 섹션을 참조하세요. **Example** 다음은 제품의 AWS CLI가 5씩 증가하는 `Price` 예입니다. 이 예에서는 카운터가 업데이트되기 전에 항목이 존재하는 것으로 알려져 있습니다. `UpdateItem`은 멱등성이 없으므로 이 코드를 실행할 때마다 `Price`가 증가합니다. ``` aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id": { "N": "601" }}' \ --update-expression "SET Price = Price + :incr" \ --expression-attribute-values '{":incr":{"N":"5"}}' \ --return-values UPDATED_NEW ``` ## 조건부 쓰기 기본적으로 DynamoDB 쓰기 작업(`PutItem`, `DeleteItem`)은 *무조건적*입니다. 즉, 이러한 각 작업은 지정된 프라이머리 키가 있는 기존 항목을 덮어씁니다. DynamoDB는 선택적으로 이러한 작업의 조건부 쓰기를 지원합니다. 조건부 쓰기는 항목 속성이 하나 이상의 예상 조건과 일치하는 경우에만 성공합니다. 그렇지 않으면 오류를 반환합니다. 조건부 쓰기는 가장 최근에 업데이트된 항목 버전과 비교하여 조건을 확인합니다. 항목이 이전에 존재하지 않았거나 해당 항목에 대해 가장 최근에 성공한 작업이 삭제인 경우 조건부 쓰기는 이전 항목을 찾지 못한다는 점에 유의하시기 바랍니다. 조건부 쓰기는 많은 상황에서 유용합니다. 예를 들면 동일한 기본 키가 있는 항목이 아직 없는 경우에만 `PutItem` 작업이 성공하도록 하려고 합니다. 또는 속성 중 하나에 특정 값이 있으면 `UpdateItem` 작업을 통해 항목을 수정할 수 없도록 할 수 있습니다. 조건부 쓰기는 여러 사용자가 동일한 항목을 수정하려고 시도하는 경우에 유용합니다. 두 명의 사용자(Alice와 Bob)가 DynamoDB 테이블에서 동일한 항목을 작업하고 있는 다음 다이어그램을 생각해 봅니다. ![사용자 Alice와 Bob은 Id 1을 사용하여 항목을 수정하려고 시도하는데, 이는 조건부 쓰기가 필요함을 보여줍니다.](http://docs.aws.amazon.com/ko_kr/amazondynamodb/latest/developerguide/images/update-no-condition.png) Alice가 AWS CLI를 사용하여 `Price` 속성을 8로 업데이트한다고 가정합니다. ``` aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}' \ --update-expression "SET Price = :newval" \ --expression-attribute-values file://expression-attribute-values.json ``` `--expression-attribute-values`의 인수는 `expression-attribute-values.json` 파일에 저장됩니다. ``` { ":newval":{"N":"8"} } ``` 이제 Bob이 비슷한 `UpdateItem` 요청을 나중에 실행하지만, `Price`를 12로 변경한다고 가정합니다. Bob의 경우 `--expression-attribute-values` 파라미터는 다음과 같습니다. ``` { ":newval":{"N":"12"} } ``` Bob의 요청은 성공하지만 Alice의 이전 업데이트는 손실됩니다. 조건부 `PutItem`, `DeleteItem` 또는 `UpdateItem`을 요청하려면 조건 표현식을 지정합니다. *조건 표현식*은 속성 이름, 조건부 연산자 및 기본 제공 함수를 포함하는 문자열입니다. 전체 표현식이 true로 평가되어야 합니다. 그렇지 않으면 작업이 실패합니다. 이제 조건부 쓰기를 사용하여 Alice의 업데이트를 덮어쓰지 못하도록 하는 방법을 보여 주는 다음 다이어그램을 생각해 봅니다. ![조건부 쓰기는 사용자 Bob의 업데이트가 사용자 Alice의 변경 내용을 같은 항목에 덮어쓰지 못하도록 합니다.](http://docs.aws.amazon.com/ko_kr/amazondynamodb/latest/developerguide/images/update-yes-condition.png) 처음에 Alice는 현재 `Price`가 10인 경우에만 `Price`를 8로 업데이트하려고 시도합니다. ``` aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}' \ --update-expression "SET Price = :newval" \ --condition-expression "Price = :currval" \ --expression-attribute-values file://expression-attribute-values.json ``` `--expression-attribute-values`의 인수는 `expression-attribute-values.json` 파일에 저장됩니다. ``` { ":newval":{"N":"8"}, ":currval":{"N":"10"} } ``` 조건이 true로 평가되기 때문에 Alice의 업데이트가 성공합니다. 다음에 Bob은 현재 `Price`가 10인 경우에만 `Price`를 12로 업데이트하려고 시도합니다. Bob의 경우 `--expression-attribute-values` 파라미터는 다음과 같습니다. ``` { ":newval":{"N":"12"}, ":currval":{"N":"10"} } ``` Alice가 이전에 `Price`를 8로 변경했기 때문에 조건 표현식은 false로 평가되고 Bob의 업데이트는 실패합니다. 자세한 내용은 [DynamoDB 조건 표현식 CLI 예제](Expressions.ConditionExpressions.md) 섹션을 참조하세요. ### 조건부 쓰기 멱등성 업데이트 할 동일한 속성에 대한 조건부 검사의 경우 조건부 쓰기는 *idempotent*가 될 수 있습니다. 즉, 항목의 특정 속성 값이 요청 시 원하는 값과 일치하는 경우에만 DynamoDB가 해당 쓰기 요청을 수행합니다. 예를 들어, `UpdateItem`가 현재 20인 경우에만 항목의 `Price`를 3으로 증가시키는 `Price` 요청을 실행한다고 가정합니다. 요청을 보낸 후 결과를 다시 받기 전에 네트워크 오류가 나타나고 요청이 성공적이었는지 여부를 알 수 없습니다. 이 조건부 쓰기는 멱등성 방식이기 때문에 동일한 `UpdateItem` 요청을 재시도할 수 있으며 `Price`가 현재 20인 경우에만 DynamoDB가 항목을 업데이트합니다. ### 조건부 쓰기에서 사용된 용량 단위 조건부 쓰기 중에 `ConditionExpression`이 false로 평가되는 경우에도 DynamoDB는 테이블에서 쓰기 용량을 사용합니다. 사용되는 양은 기존 항목의 크기(또는 최소 1개)에 따라 달라집니다. 예를 들어 기존 항목이 300kb이고 새로 만들거나 업데이트하려는 항목이 310kb인 경우, 사용되는 쓰기 용량 단위는 조건이 충족되지 않으면 300, 조건이 충족되면 310이 됩니다. 새 항목(기존 항목 없음)인 경우, 사용되는 쓰기 용량 단위는 조건이 충족되지 않으면 1, 조건이 충족되면 310이 됩니다. **참고** 쓰기 작업은 *쓰기* 용량 단위만 사용합니다. 이 작업은 *읽기* 용량 단위를 사용하지 않습니다. 조건부 쓰기가 실패하면 `ConditionalCheckFailedException`이 반환됩니다. 이 상황이 발생하면 사용된 쓰기 용량에 대한 정보를 응답에서 받을 수 없습니다. 조건부 쓰기 중에 사용된 쓰기 용량 단위 수를 반환하려면 `ReturnConsumedCapacity` 파라미터를 사용합니다. + `TOTAL` - 사용된 총 쓰기 용량 단위 수를 반환합니다. + `INDEXES` - 사용된 총 쓰기 용량 단위 수와 작업의 영향을 받은 테이블 및 보조 인덱스의 소계를 반환합니다. + `NONE` - 쓰기 용량 세부 정보를 반환하지 않습니다. (이 값이 기본값입니다.) **참고** 글로벌 보조 인덱스와 달리 로컬 보조 인덱스는 프로비저닝된 처리 용량을 해당 테이블과 공유합니다. 로컬 보조 인덱스에서의 읽기 또는 쓰기 작업에는 테이블의 프로비저닝된 처리 용량이 사용됩니다.