문서 삭제 API
문서 삭제 API (Delete Document API)
인덱스에서 문서 하나를 삭제하고 싶으시죠? 문서 삭제 API가 인덱스에서 문서를 제거해요. 인덱스 이름과 문서 ID를 모두 지정해야 해요. 문서가 삭제되면 OpenSearch는 버전 번호를 증가시키고 다음 세그먼트 병합 시 제거하도록 표시해요.
출처: 문서
본문
1.0에서 도입
문서 삭제 API는 인덱스에서 문서를 제거해요. 인덱스 이름과 문서 ID를 모두 지정해야 해요. 문서가 삭제되면 OpenSearch는 버전 번호를 증가시키고 다음 세그먼트 병합 중 제거하도록 표시해요.
엔드포인트
DELETE /{index}/_doc/{id}
경로 파라미터
다음 표는 사용 가능한 경로 파라미터예요.
| Parameter | Required | Data type | Description |
|---|---|---|---|
| id | Required | String | 문서의 고유 식별자예요. |
| index | Required | String | 대상 인덱스의 이름이에요. |
쿼리 파라미터
다음 표는 사용 가능한 쿼리 파라미터예요. 모든 쿼리 파라미터는 선택적이에요.
| Parameter | Data type | Description |
|---|---|---|
| if_seq_no | Integer | 문서가 이 시퀀스 번호를 가질 때만 삭제 연산을 수행해요. Optimistic concurrency control을 참고하세요. |
| if_primary_term | Integer | 문서가 이 primary term을 가질 때만 삭제 연산을 수행해요. Optimistic concurrency control을 참고하세요. |
| refresh | Boolean or String | 삭제 연산으로 인한 변경 사항이 검색에 언제 표시되는지 제어해요. 유효한 값은 true(즉시 refresh), false(기본값, refresh 안 함), wait_for(응답 전에 refresh 대기)예요. Refresh를 참고하세요. |
| routing | String | 연산을 특정 샤드로 라우팅하는 데 사용되는 사용자 정의 값이에요. 문서가 routing 값으로 인덱싱된 경우 필수예요. Routing을 참고하세요. |
| timeout | Time | primary 샤드가 사용 가능해질 때까지 기다리는 시간이에요. 기본값은 1m(1분)이에요. Timeout을 참고하세요. |
| version | Integer | 동시성 제어를 위한 명시적 버전 번호예요. 요청이 성공하려면 지정된 버전이 문서의 현재 버전과 일치해야 해요. Versioning을 참고하세요. |
| version_type | Enum | 버전 유형을 지정해요: internal(기본값), external, external_gte. external에서는 버전 번호가 현재 버전보다 커야 해요. external_gte에서는 크거나 같아야 해요. Versioning을 참고하세요. |
| wait_for_active_shards | String | 연산을 진행하기 전에 활성 상태여야 하는 샤드 복사본 수예요. 기본값은 1(primary 샤드만)이에요. all 또는 인덱스의 총 샤드 수(number_of_replicas+1)까지의 양의 정수로 설정해요. Wait for active shards를 참고하세요. |
예시 요청
다음 예시 요청은 products 인덱스에서 ID가 1인 문서를 삭제해요.
DELETE /products/_doc/1
예시 응답
다음 예시 응답은 성공적인 삭제 연산을 보여줘요.
{
"_index" : "products",
"_id" : "1",
"_version" : 9,
"result" : "deleted",
"_shards" : {
"total" : 2,
"successful" : 1,
"failed" : 0
},
"_seq_no" : 45,
"_primary_term" : 1
}
응답 본문 필드
응답 본문에는 삭제 연산과 영향받은 문서에 대한 정보가 포함돼요.
| Field | Description |
|---|---|
| _index | 문서가 삭제된 인덱스의 이름이에요. |
| _id | 삭제된 문서의 고유 식별자예요. |
| _version | 삭제 후 문서의 새 버전 번호예요. 각 삭제 연산은 버전 번호를 증가시켜요. |
| result | 삭제 연산의 결과예요. 문서가 성공적으로 삭제됐으면 deleted, 문서가 존재하지 않았으면 not_found를 반환해요. |
| _shards | 삭제 연산에 관여한 샤드에 대한 정보를 포함해요. |
| _shards.total | 삭제 연산을 승인했어야 하는 총 샤드 수(primary와 replica)예요. |
| _shards.successful | 삭제 연산을 성공적으로 처리한 샤드 수예요. |
| _shards.failed | 삭제 연산 처리에 실패한 샤드 수예요. 이 값이 0보다 크면 failures 배열에 실패 세부 정보가 포함돼요. |
| _seq_no | 삭제 연산에 할당된 시퀀스 번호예요. 시퀀스 번호는 낙관적 동시성 제어에 사용돼요. |
| _primary_term | 삭제 연산 시점의 primary term이에요. _seq_no와 함께 이 값은 낙관적 동시성 제어에 사용돼요. |
낙관적 동시성 제어 (Optimistic concurrency control)
삭제 연산은 if_seq_no와 if_primary_term 파라미터를 통해 낙관적 동시성 제어를 지원해요. 이 파라미터를 지정하면 문서의 현재 시퀀스 번호와 primary term이 제공된 값과 일치할 때만 OpenSearch가 삭제 연산을 수행해요. 불일치가 있으면 OpenSearch는 version_conflict_engine_exception 오류와 상태 코드 409를 반환해, 문서가 마지막으로 가져온 이후 수정됐음을 나타내요.
다음 예시 요청은 문서의 시퀀스 번호가 43이고 primary term이 1일 때만 문서를 삭제해요.
DELETE /products/_doc/3?if_seq_no=43&if_primary_term=1
문서의 현재 시퀀스 번호 또는 primary term이 지정된 값과 일치하지 않으면 OpenSearch는 상태 코드 409의 버전 충돌 오류를 반환해요.
버전 관리 (Versioning)
삭제를 포함한 문서에 대한 모든 쓰기 연산은 문서의 버전 번호를 증가시켜요. 문서가 삭제된 후에도 동시 연산을 지원하기 위해 버전 번호는 짧은 기간 동안 사용할 수 있어요. 이 버전 정보가 유지되는 기간은 기본값이 60초인 index.gc_deletes 인덱스 설정으로 제어돼요. 이는 OpenSearch가 동시 삭제 요청을 적절히 처리하고 replica 전체에서 일관성을 유지하게 해줘요.
자동 인덱스 생성 (Automatic index creation)
외부 버전 변형(version_type=external 또는 version_type=external_gte)을 사용하면 삭제 연산이 인덱스가 존재하지 않을 때 지정된 인덱스를 자동으로 생성해요. 이 동작은 외부 버전 유형에서만 발생하며 기본 내부 버전 관리에는 적용되지 않아요.
다음 예시 요청은 외부 버전 관리를 사용하므로 auto-created-index 인덱스를 자동으로 만들어요.
DELETE /auto-created-index/_doc/1?version=5&version_type=external
문서가 존재하지 않기 때문에 연산은 not_found 결과를 반환하지만, 부수 효과로 인덱스가 생성돼요. 외부 버전 관리 없이 존재하지 않는 인덱스에서 문서를 삭제하려 하면 index_not_found_exception 오류가 반환돼요.
라우팅 (Routing)
문서가 특정 라우팅 값으로 인덱싱되면 OpenSearch는 그 값을 사용해 문서를 저장할 샤드를 결정해요. 라우팅된 문서를 삭제하려면 인덱싱 때 사용한 것과 같은 라우팅 값을 제공해야 해요. 인덱스 매핑이 _routing을 required로 설정하고 라우팅 값을 지정하지 않고 문서를 삭제하려 하면 OpenSearch는 RoutingMissingException으로 요청을 거부해요.
다음 예시 요청은 라우팅 값 electronics로 인덱싱된 문서를 삭제해요.
DELETE /products/_doc/2?routing=electronics
올바른 라우팅 값이 없으면 OpenSearch는 적절한 샤드에서 문서를 찾을 수 없어 삭제 연산이 실패해요.
분산 실행 (Distributed execution)
삭제 요청을 보내면 OpenSearch는 문서 ID를 해시해 대상 샤드를 결정해요. 그런 다음 요청은 해당 샤드 그룹의 primary 샤드로 라우팅돼요. primary 샤드가 삭제 연산을 처리한 후 변경 사항은 같은 샤드 그룹의 모든 replica 샤드로 복제되어 클러스터 전체에 걸친 일관성을 보장해요.
Refresh
기본적으로 삭제된 문서는 기본적으로 1초마다 발생하는 다음 인덱스 refresh 이후에만 검색 작업에 표시돼요. refresh 파라미터로 이 동작을 제어할 수 있어요.
false(기본값): 삭제 연산이 즉시 반환되고 변경 사항은 다음 자동 refresh 후 표시돼요.true: 삭제 연산 후 OpenSearch가 영향받은 모든 샤드를 즉시 refresh해 변경 사항을 바로 검색 작업에 표시해요. 이 옵션은 성능에 영향을 주므로 아껴서 사용해야 해요.wait_for: 삭제 연산이 다음 자동 refresh를 기다린 후 응답을 반환해, API 호출이 완료될 때 변경 사항이 표시되도록 보장해요.
활성 샤드 대기 (Wait for active shards)
wait_for_active_shards 파라미터는 OpenSearch가 삭제 요청을 처리하기 전에 사용 가능해야 하는 샤드 복사본 수를 제어해요. 기본적으로 이 값은 1로 primary 샤드만 활성이면 돼요. all로 설정해 모든 샤드 복사본(primary와 replica)이 활성이도록 요구하거나, 양의 정수를 지정해 특정 수의 활성 샤드를 요구할 수 있어요. 이 설정은 삭제 연산을 확인하기 전에 replica가 사용 가능해질 때까지 기다려 데이터 내구성을 확보하는 데 도움이 돼요.
타임아웃 (Timeout)
삭제 요청이 도착했을 때 primary 샤드를 사용할 수 없으면(예: 복구나 재배치 중) OpenSearch는 샤드가 사용 가능해질 때까지 기다려요. timeout 파라미터는 요청을 실패 처리하기 전에 기다릴 시간을 지정해요. 기본 타임아웃은 1분이에요. 지정된 타임아웃 기간 내에 primary 샤드가 사용 가능해지지 않으면 OpenSearch는 오류를 반환해요.
다음 예시 요청은 30초의 사용자 정의 타임아웃을 설정해요.
DELETE /products/_doc/4?timeout=30s
보안
Security 플러그인을 사용한다면 적절한 권한이 있는지 확인해야 해요: indices:data/write/delete.
더 알아보기 (Learn more)
- 외부 버전 관리를 쓰면 인덱스가 자동 생성되는 동작에 유의하세요.
- 라우팅된 문서를 삭제할 때는 반드시 같은 라우팅 값을 전달해야 해요.