Azure Cosmos DB의 부분 문서 업데이트
적용 대상: 
NoSQL
Azure Cosmos DB 부분 문서 업데이트 기능(패치 API라고도 함)은 컨테이너에서 문서를 수정하는 편리한 방법을 제공합니다. 현재 클라이언트에서 읽어야 하는 문서를 업데이트하려면 낙관적 동시성 제어 확인을 실행하고(필요한 경우), 문서를 로컬로 업데이트한 다음, 전체 문서 바꾸기 API 호출로 유선으로 보냅니다.
부분 문서 업데이트 기능은 이 환경을 크게 향상시킵니다. 클라이언트는 전체 문서 바꾸기 작업을 수행하지 않고 문서의 수정된 속성/필드만 보낼 수 있습니다. 이 기능의 주요 이점은 다음과 같습니다.
- 개발자 생산성 향상: 사용 편의성과 조건부 문서 업데이트 기능에 대한 편리한 API를 제공합니다.
- 성능 향상: 클라이언트 쪽에서 추가 CPU 주기를 방지하고 엔드투엔드 대기 시간 및 네트워크 대역폭을 줄입니다.
- 다중 지역 쓰기: 동일한 문서 내의 개별 경로에 대한 부분 업데이트를 통해 자동 및 투명한 충돌 해결을 지원합니다.
참고 항목
부분 문서 업데이트 작업은 JSON 패치 RFC를 기반으로 합니다. 경로의 속성 이름은 ~ 및 / 문자를 각각 ~0 및 ~1로 이스케이프해야 합니다.
대상 JSON 문서의 예:
{
"id": "e379aea5-63f5-4623-9a9b-4cd9b33b91d5",
"name": "R-410 Road Bicycle",
"price": 455.95,
"inventory": {
"quantity": 15
},
"used": false,
"categoryId": "road-bikes",
"tags": ["r-series"]
}
JSON 패치 문서:
[
{ "op": "add", "path": "/color", "value": "silver" },
{ "op": "remove", "path": "/used" },
{ "op": "set", "path": "/price", "value": 355.45 }
{ "op": "incr", "path": "/inventory/quantity", "value": 10 },
{ "op": "add", "path": "/tags/-", "value": "featured-bikes" },
{ "op": "move", "from": "/color", "path": "/inventory/color" }
]
결과 JSON 문서:
{
"id": "e379aea5-63f5-4623-9a9b-4cd9b33b91d5",
"name": "R-410 Road Bicycle",
"price": 355.45,
"inventory": {
"quantity": 25,
"color": "silver"
},
"categoryId": "road-bikes",
"tags": ["r-series", "featured-bikes"]
}
지원되는 작업
이 표에는 이 기능이 지원하는 작업이 요약되어 있습니다.
참고 항목
대상 경로는 JSON 문서 내의 위치를 나타냅니다.
| 작업 유형 | 설명 |
|---|---|
| 추가 | Add는 대상 경로에 따라 다음 중 하나를 수행합니다. • 대상 경로에서 없는 요소를 지정하는 경우 추가됩니다. • 대상 경로에서 이미 있는 요소를 지정하는 경우 해당 값이 대체됩니다. • 대상 경로가 유효한 배열 인덱스인 경우 새 요소가 지정된 인덱스의 배열에 삽입됩니다. 그러면 기존 요소가 새 요소 뒤로 이동합니다. • 지정된 인덱스가 배열의 길이와 같은 경우 요소를 배열에 추가합니다. 인덱스를 지정하는 대신 - 문자를 사용할 수도 있습니다. 또한 요소가 배열에 추가됩니다.참고: 배열 길이보다 긴 인덱스를 지정하면 오류가 발생합니다. |
| 설정 | Set 작업은 배열 데이터 형식을 제외하고 Add와 유사합니다. 대상 경로가 유효한 배열 인덱스인 경우 해당 인덱스의 기존 요소가 업데이트됩니다. |
| Replace | Replace 작업은 엄격한 바꾸기 전용 의미 체계를 따른다는 것을 제외하고 Set와 비슷합니다. 대상 경로에서 없는 요소 또는 배열을 지정하는 경우 오류가 발생합니다. |
| 제거 | Remove는 대상 경로에 따라 다음 중 하나를 수행합니다. • 대상 경로에서 없는 요소를 지정하는 경우 오류가 발생합니다. • 대상 경로에서 이미 있는 요소를 지정하는 경우 제거됩니다. • 대상 경로가 배열 인덱스인 경우 삭제되고 지정된 인덱스 위의 모든 요소가 한 위치 뒤로 이동합니다. 참고: 배열 길이보다 길거나 같은 인덱스를 지정하면 오류가 발생합니다. |
| ID 증가값 | 이 연산자는 필드를 지정된 값만큼 증분합니다. 양수 값과 음수 값을 모두 허용할 수 있습니다. 필드가 없는 경우 필드를 만들고 지정된 값으로 설정합니다. |
| 이동 | 이 연산자는 지정된 위치에서 값을 제거하고 대상 위치에 추가합니다. 작업 개체는 값을 이동할 대상 문서의 위치를 참조하는 JSON 포인터 값을 포함하는 문자열인 "from" 멤버를 포함해야 합니다. 작업이 성공하려면 "from" 위치가 있어야 합니다. "path" 위치가 존재하지 않는 개체를 제안하는 경우 개체를 만들고 값을 "from" 위치의 값과 동일하게 설정합니다. •"path" 위치가 이미 존재하는 개체를 제안하는 경우 "path" 위치의 값을 "from" 위치의 값으로 바꿉니다. •"Path" 특성은 "from" JSON 위치의 JSON 자식일 수 없습니다. |
지원되는 모드
부분 문서 업데이트 기능에서 지원하는 작업 모드는 다음과 같습니다. 코드 예제는 시작 문서를 참조하세요.
단일 문서 패치: ID와 파티션 키에 따라 단일 문서를 패치할 수 있습니다. 단일 문서에서 여러 패치 작업을 실행할 수 있습니다. 최대 제한은 10개 작업입니다.
다중 문서 패치: 동일한 파티션 키 내의 여러 문서를 트랜잭션의 일부로 패치할 수 있습니다. 이 다중 문서 트랜잭션은 모든 작업이 설명된 순서대로 성공하는 경우에만 커밋됩니다. 작업이 실패하면 전체 트랜잭션이 롤백됩니다.
조건부 업데이트: 앞에서 언급한 모드의 경우 조건자에 지정된 사전 조건이 충족되지 않으면 작업이 실패하는 것과 같은 SQL 유사 필터 조건자(예:
from c where c.taskNum = 3)를 추가할 수도 있습니다.또한 지원되는 SDK의 대량 API를 사용하여 여러 문서에서 하나 이상의 패치 작업을 실행할 수 있습니다.
유사점 및 차이점
지원되는 모드 간 유사성과 차이점을 비교해 보겠습니다.
추가 및 설정
Set 작업은 Array를 제외한 모든 데이터 형식에 대해 Add와 비슷합니다. 모든 (유효한) 인덱스의 Add 작업을 수행하면 요소가 지정된 인덱스에 추가되고 결국에는 배열의 기존 요소가 기존 요소 뒤로 이동합니다. 이 동작은 지정된 인덱스의 기존 요소를 업데이트하는 Set 작업과는 대조적입니다.
추가 및 바꾸기
속성이 아직 없는 경우 Add 작업은 해당 속성을 추가합니다(Array 데이터 형식 포함). 속성이 없는 경우 Replace 작업이 실패합니다(Array 데이터 형식에도 적용됨).
설정 및 바꾸기
속성이 아직 없는 경우 Set 작업은 해당 속성을 추가합니다(Array가 있는 경우 제외). 속성이 없는 경우 Replace 작업이 실패합니다(Array 데이터 형식에도 적용됨).
참고 항목
Replace는 사용자가 일부 속성이 항상 있는 것으로 예상하고 이를 어설션/적용할 수 있는 좋은 후보입니다.
부분 문서 업데이트에 대한 REST API 참조
Azure Cosmos DB REST API는 Azure Cosmos DB 리소스에 대한 프로그래밍 방식 액세스를 제공하여 데이터베이스, 문서 컬렉션 및 문서를 만들고, 쿼리하고, 삭제합니다. 컬렉션의 JSON 문서에 대한 삽입, 바꾸기, 삭제, 읽기, 열거 및 쿼리 작업을 실행하는 것 외에도 PATCH HTTP 메서드를 부분 문서 업데이트 작업에 사용할 수 있습니다. 자세한 내용은 Azure Cosmos DB REST API 참조를 참조하세요.
예를 들어 부분 문서 업데이트를 사용하는 set 작업에 대한 요청은 다음과 같습니다.
PATCH https://querydemo.documents.azure.com/dbs/FamilyDatabase/colls/FamilyContainer/docs/Andersen.1 HTTP/1.1
x-ms-documentdb-partitionkey: ["Andersen"]
x-ms-date: Tue, 29 Mar 2016 02:28:29 GMT
Authorization: type%3dmaster%26ver%3d1.0%26sig%3d92WMAkQv0Zu35zpKZD%2bcGSH%2b2SXd8HGxHIvJgxhO6%2fs%3d
Content-Type:application/json_patch+json
Cache-Control: no-cache
User-Agent: Microsoft.Azure.DocumentDB/2.16.12
x-ms-version: 2015-12-16
Accept: application/json
Host: querydemo.documents.azure.com
Cookie: x-ms-session-token#0=602; x-ms-session-token=602
Content-Length: calculated when request is sent
Connection: keep-alive
{
"operations": [
{
"op": "set",
"path": "/Parents/0/FamilyName",
"value": "Bob"
}
]
}
문서 수준 및 경로 수준 충돌 해결
Azure Cosmos DB 계정이 여러 쓰기 지역으로 구성된 경우 충돌 및 충돌 해결 정책은 기본 충돌 해결 정책인 마지막으로 성공한 쓰기(LWW)와 함께 문서 수준에서 적용할 수 있습니다. 부분 문서 업데이트의 경우 여러 지역에 걸친 패치 작업이 더 세분화된 경로 수준에서 충돌을 감지하고 해결합니다.
충돌 해결 방법은 예제를 통해 더 잘 이해할 수 있습니다.
다음과 같은 문서가 Azure Cosmos DB에 있다고 가정합니다.
{
"id": 1,
"name": "John Doe",
"email": "jdoe@contoso.com",
"phone": ["12345", "67890"],
"level": "gold"
}
여러 클라이언트가 여러 지역에서 동시에 패치 작업을 실행합니다.
/level특성을 platinum으로 설정합니다(Set)./phone에서 67890을 제거합니다(Remove).
패치 요청이 문서 내에서 충돌하지 않는 경로에 대해 수행되었으므로 이 요청은 자동으로 투명하게 해결되는 충돌입니다(문서 수준의 마지막 기록자 우선과 반대).
충돌 해결 후 클라이언트에 다음 문서가 표시됩니다.
{
"id": 1,
"name": "John Doe",
"email": "jdoe@contoso.com",
"phone": ["12345"],
"level": "platinum"
}
참고 항목
문서의 동일한 속성이 여러 지역에서 동시에 패치되는 경우 일반적인 충돌 해결 정책이 적용됩니다.
변경 피드
Azure Cosmos DB의 변경 피드는 변경 내용에 대한 컨테이너를 수신 대기한 다음 변경된 문서를 출력합니다. 변경 피드를 사용하면 부분 및 전체 문서 업데이트를 포함하여 문서에 대한 모든 업데이트를 볼 수 있습니다. 변경 피드에서 항목을 처리할 때 업데이트가 패치 작업의 결과였던 경우에도 전체 문서가 반환됩니다.
Azure Cosmos DB의 변경 피드에 대한 자세한 내용은 Azure Cosmos DB의 변경 피드를 참조하세요.