항목 및 속성 작업

Amazon DynamoDB에서 항목은 속성 모음입니다. 각 속성마다 이름과 값이 있습니다. 속성 값은 스칼라, 세트 또는 문서 유형일 수 있습니다. 자세한 정보는 Amazon DynamoDB: 작동 방식을 참조하세요.

DynamoDB는 기본 CRUD(생성/읽기/업데이트/삭제) 기능을 위한 다음 네 가지 작업을 제공합니다. 이 모든 작업은 원자성입니다.

PutItem - 항목을 생성합니다.
GetItem - 항목을 읽습니다.
UpdateItem - 항목을 업데이트합니다.
DeleteItem - 항목을 삭제합니다.

이러한 각 작업에서는 작업할 항목의 기본 키를 지정해야 합니다. 예를 들어, GetItem을 사용하여 항목을 읽으려면 해당 항목에 대한 파티션 키와 정렬 키(적용 가능한 경우)를 지정해야 합니다.

네 개의 기본 CRUD 작업에 추가하여 DynamoDB는 다음과 같은 작업도 제공합니다.

BatchGetItem - 하나 이상의 테이블에서 최대 100개의 항목을 읽습니다.
BatchWriteItem - 하나 이상의 테이블에서 최대 25개의 항목을 생성하거나 삭제합니다.

이러한 배치 작업은 여러 CRUD 작업을 단일 요청으로 결합니다. 또한 배치 작업은 항목 읽기 및 쓰기를 병렬로 실행하여 응답 지연 시간을 최소화합니다.

이 섹션에서는 이 작업을 사용하는 방법을 설명하며 조건부 업데이트 및 원자성 카운터와 같은 관련 주제도 다룹니다. 이 섹션에는 AWS SDK를 사용하는 예제 코드도 포함되어 있습니다.

주제

항목 읽기

DynamoDB 테이블에서 항목을 읽으려면 GetItem 작업을 사용합니다. 원하는 항목의 기본 키와 함께 테이블 이름을 제공해야 합니다.

예

다음 AWS CLI 예제는 ProductCatalog 테이블에서 항목을 읽는 방법을 보여줍니다.


aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}'

참고

GetItem에는 부분만이 아닌 전체 기본 키를 지정해야 합니다. 예를 들어 테이블에 복합 기본 키(파티션 키 및 정렬 키)가 있는 경우 파티션 키 값과 정렬 키 값을 공급해야 합니다.

기본적으로 GetItem 요청은 최종적으로 일관된 읽기를 수행합니다. 그 대신 ConsistentRead 파라미터를 사용하여 강력한 일관된 읽기를 요청할 수 있습니다. (이렇게 하면 읽기 용량 단위를 추가로 소비하지만 항목의 가장 많은 up-to-date 버전을 반환합니다.)

GetItem은 모든 항목의 속성을 반환합니다. 프로젝션 표현식을 사용하여 속성의 일부만 반환할 수 있습니다. 자세한 정보는 프로젝션 표현식을 참조하세요.

GetItem에서 사용된 읽기 용량 단위 수를 반환하려면 ReturnConsumedCapacity 파라미터를 TOTAL로 설정합니다.

예

다음 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 새 항목을 만듭니다. 동일 키의 항목이 테이블이 이미 존재하는 경우 해당 항목이 새 항목으로 대체됩니다.

예

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은 새 항목을 생성합니다. 그렇지 않으면 기존 항목의 속성을 수정합니다.

업데이트 표현식을 사용하여 수정하려는 속성과 새 값을 지정합니다. 자세한 정보는 업데이트 표현식을 참조하세요.

업데이트 표현식 내에서는 표현식 속성 값을 실제 값에 대한 자리 표시자로 사용합니다. 자세한 정보는 표현식 속성 값을 참조하세요.

예

Thread 항목에서 다양한 속성을 수정합니다. 선택적 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는 지정된 키가 있는 항목을 삭제합니다.

예

다음 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 작업은 여러 테이블에서 항목을 검색할 수 있습니다.

예

일부 속성만 반환하는 프로젝션 표현식을 사용하여 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 요청을 지원하지 않습니다.

예

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 작업이 실패할 경우 애플리케이션은 작업을 단순히 재시도할 수 있습니다. 이렇게 하면 카운터를 두 번 업데이트할 위험이 있지만, 웹 사이트 방문객 수를 약간 많게 또는 적게 계산하는 것을 허용할 수 있습니다.

수를 많게 또는 적게 계산하는 것을 허용할 수 없는 경우에는(예: 은행 애플리케이션) 원자성 카운터가 적합하지 않습니다. 이러한 경우 원자성 카운터 대신 조건부 업데이트를 사용하는 것이 더 안전합니다.

자세한 정보는 수치 속성 증가 및 감소을 참조하세요.

예

다음 AWS CLI 예제에서는 제품의 Price x를 5씩 증가시킵니다. 이 예시에서는 카운터가 업데이트되기 전에 해당 항목이 존재하는 것으로 알려져 있습니다. 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, UpdateItem, DeleteItem)은 무조건적입니다. 즉, 이러한 각 작업은 지정된 기본 키가 있는 기존 항목을 덮어씁니다.

DynamoDB는 선택적으로 이러한 작업의 조건부 쓰기를 지원합니다. 조건부 쓰기는 항목 속성이 하나 이상의 예상 조건과 일치하는 경우에만 성공합니다. 그렇지 않으면 오류를 반환합니다.

조건부 쓰기는 가장 최근에 업데이트된 버전의 항목을 기준으로 조건을 확인합니다. 단, 항목이 이전에 존재하지 않았거나 해당 항목에 대해 가장 최근에 성공한 작업이 삭제인 경우 조건부 쓰기는 이전 항목을 찾지 못합니다.

조건부 쓰기는 많은 상황에서 유용합니다. 예를 들면 동일한 기본 키가 있는 항목이 아직 없는 경우에만 PutItem 작업이 성공하도록 하려고 합니다. 또는 속성 중 하나에 특정 값이 있으면 UpdateItem 작업을 통해 항목을 수정할 수 없도록 할 수 있습니다.

조건부 쓰기는 여러 사용자가 동일한 항목을 수정하려고 시도하는 경우에 유용합니다. 두 명의 사용자(Alice와 Bob)가 DynamoDB 테이블에서 동일한 항목을 작업하고 있는 다음 다이어그램을 생각해 봅니다.

Alice가 를 사용하여 Price 속성을 AWS CLI 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의 업데이트를 덮어쓰지 못하도록 하는 방법을 보여 주는 다음 다이어그램을 생각해 봅니다.

처음에 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의 업데이트는 실패합니다.

자세한 정보는 조건 표현식을 참조하세요.

조건부 쓰기 멱등성

업데이트 할 동일한 속성에 대한 조건부 검사의 경우 조건부 쓰기는 idempotent가 될 수 있습니다. 즉, 항목의 특정 속성 값이 요청 시 원하는 값과 일치하는 경우에만 DynamoDB가 해당 쓰기 요청을 수행합니다.

예를 들어, Price가 현재 20인 경우에만 항목의 Price를 3으로 증가시키는 UpdateItem 요청을 실행한다고 가정합니다. 요청을 보낸 후 결과를 다시 받기 전에 네트워크 오류가 나타나고 요청이 성공적이었는지 여부를 알 수 없습니다. 이 조건부 쓰기는 멱등성 방식이기 때문에 동일한 UpdateItem 요청을 재시도할 수 있으며 Price가 현재 20인 경우에만 DynamoDB가 항목을 업데이트합니다.

조건부 쓰기에서 사용된 용량 단위

조건부 쓰기 중에 ConditionExpression이 false로 평가되는 경우에도 DynamoDB는 테이블에서 쓰기 용량을 사용합니다. 사용되는 양은 기존 항목의 크기(또는 최소 1개)에 따라 달라집니다. 예를 들어 기존 항목이 300kb이고 새로 만들거나 업데이트하려는 항목이 310kb인 경우, 사용되는 쓰기 용량 단위는 조건이 충족되지 않으면 300, 조건이 충족되면 310이 됩니다. 새 항목(기존 항목 없음)인 경우, 사용되는 쓰기 용량 단위는 조건이 충족되지 않으면 1, 조건이 충족되면 310이 됩니다.

참고

쓰기 작업은 쓰기 용량 단위만 사용합니다. 이 작업은 읽기 용량 단위를 사용하지 않습니다.

조건부 쓰기가 실패하면 ConditionalCheckFailedException이 반환됩니다. 이 상황이 발생하면 사용된 쓰기 용량에 대한 정보를 응답에서 받을 수 없습니다. 하지만 Amazon에서는 테이블의 ConsumedWriteCapacityUnits 지표를 볼 수 CloudWatch 있습니다. 자세한 설명은 DynamoDB의 로깅 및 모니터링에서 DynamoDB 지표 섹션을 참조하십시오.

조건부 쓰기 중에 사용된 쓰기 용량 단위 수를 반환하려면 ReturnConsumedCapacity 파라미터를 사용합니다.

TOTAL - 사용된 총 쓰기 용량 단위 수를 반환합니다.
INDEXES - 사용된 총 쓰기 용량 단위 수와 작업의 영향을 받은 테이블 및 보조 인덱스의 소계를 반환합니다.
NONE - 쓰기 용량 세부 정보를 반환하지 않습니다. (이 값이 기본값입니다.)

참고

글로벌 보조 인덱스와 달리 로컬 보조 인덱스는 프로비저닝된 처리 용량을 해당 테이블과 공유합니다. 로컬 보조 인덱스에서의 읽기 또는 쓰기 작업에는 테이블의 프로비저닝된 처리 용량이 사용됩니다.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

DynamoDB API

표현식 사용