강제 머지 API

강제 머지 API (Force Merge API)

1.0부터 도입되었어요.

강제 머지(force merge) API 작업은 하나 이상의 인덱스의 샤드에 대해 강제로 머지를 수행해요. 데이터 스트림의 경우 API는 스트림의 백킹 인덱스 샤드에 대해 강제 머지를 수행해요.

출처: 문서

본문

머지 작업

OpenSearch에서 샤드는 Lucene 인덱스인데, 이는 세그먼트(segment) 또는 세그먼트 파일들로 구성돼요. 세그먼트는 인덱싱된 데이터를 저장해요. 주기적으로 더 작은 세그먼트가 더 큰 세그먼트로 머지되고, 더 큰 세그먼트는 불변 상태가 돼요. 머지는 각 샤드의 전체 세그먼트 수를 줄이고 디스크 공간을 확보해요.

OpenSearch는 index.merge.policy.max_merged_segment(기본값 5GB)보다 크지 않은 세그먼트를 생성하는 백그라운드 세그먼트 머지를 수행해요.

삭제된 문서

OpenSearch 인덱스에서 문서가 삭제되면 Lucene 세그먼트에서 실제로 삭제되는 것이 아니라 삭제 대상으로만 표시돼요. 세그먼트 파일이 머지될 때 삭제된 문서는 제거(또는 expunge)돼요. 따라서 머지는 삭제 대상으로 표시된 문서가 차지하던 공간도 확보해 줘요.

강제 머지 API

주기적인 머지 외에도 강제 머지(Force Merge) API를 사용해 세그먼트 머지를 강제로 수행할 수 있어요.

강제 머지 API는 인덱스에 보내진 모든 쓰기 요청이 완료된 후에만 인덱스에 사용해 주세요. 강제 머지 작업은 아주 큰 세그먼트를 만들 수 있어요. 인덱스에 여전히 쓰기 요청이 들어오면 머지 정책은 세그먼트가 주로 삭제된 문서로 구성될 때까지 이 세그먼트들을 머지하지 않아요. 이로 인해 디스크 공간 사용량이 늘어나고 성능이 저하될 수 있어요.

강제 머지 API를 호출하면 머지가 완료될 때까지 호출이 차단돼요. 이 동안 연결이 끊어지면 강제 머지 작업은 백그라운드에서 계속 진행돼요. 같은 인덱스에 보내진 새 강제 머지 요청은 현재 실행 중인 머지 작업이 완료될 때까지 차단돼요.

여러 인덱스 강제 머지

여러 인덱스를 강제 머지하려면 다음 인덱스 조합에 강제 머지 API를 호출할 수 있어요:

  • 여러 인덱스
  • 여러 백킹 인덱스를 포함하는 하나 이상의 데이터 스트림
  • 여러 인덱스를 가리키는 하나 이상의 인덱스 별칭
  • 클러스터의 모든 데이터 스트림과 인덱스

여러 인덱스를 강제 머지하면 노드의 각 샤드에서 머지 작업이 순차적으로 실행돼요. 강제 머지 작업이 진행되는 동안 모든 세그먼트를 새 세그먼트로 다시 쓸 수 있도록 샤드의 저장 공간이 일시적으로 늘어나요. max_num_segments가 1로 설정되면 샤드의 저장 공간이 일시적으로 두 배가 돼요.

데이터 스트림 강제 머지

특히 롤오버(rollover) 작업 이후에 데이터 스트림의 백킹 인덱스를 관리하기 위해 데이터 스트림을 강제 머지하는 것이 유용할 수 있어요. 시간 기반 인덱스는 지정된 시간 동안만 인덱싱 요청을 받아요. 그 시간이 지나 인덱스가 더 이상 쓰기 요청을 받지 않으면 모든 인덱스 샤드의 세그먼트를 하나의 세그먼트로 강제 머지할 수 있어요. 단일 세그먼트 샤드에 대한 검색은 더 단순한 데이터 구조를 사용하기 때문에 더 효율적이에요.

경로 파라미터

사용할 수 있는 경로 파라미터는 아래 표와 같아요. 모든 경로 파라미터는 선택사항이에요.

파라미터 데이터 타입 설명
<index> String 작업이 적용되는 인덱스, 데이터 스트림, 또는 인덱스 별칭의 쉼표로 구분된 목록이에요. 와일드카드 표현식(*)을 지원해요. 클러스터의 모든 인덱스와 데이터 스트림을 지정하려면 _all 또는 *을 사용해요.

쿼리 파라미터

사용할 수 있는 쿼리 파라미터는 아래 표와 같아요. 모든 쿼리 파라미터는 선택사항이에요.

파라미터 데이터 타입 설명
allow_no_indices Boolean false이면 어떤 와일드카드 표현식이나 인덱스 별칭이 닫히거나 누락된 인덱스를 대상으로 하면 오류를 반환해요. 기본값은 true예요.
expand_wildcards String 와일드카드 표현식이 확장될 수 있는 인덱스 유형을 지정해요. 쉼표로 구분된 값을 지원해요. 유효한 값은 all(숨은 인덱스를 포함한 모든 열린·닫힌 인덱스로 확장), open(열린 인덱스로 확장), closed(닫힌 인덱스로 확장), hidden(확장 시 숨은 인덱스 포함 — open, closed, 또는 둘 다와 함께 사용해야 해요), none(와일드카드 표현식을 받지 않음)이에요. 기본값은 open이에요.
flush Boolean 강제 머지 후 인덱스에 대해 플러시를 수행해요. 플러시는 파일이 디스크에 저장되도록 보장해요. 기본값은 true예요.
ignore_unavailable Boolean true이면 OpenSearch가 누락되거나 닫힌 인덱스를 무시해요. false이면 강제 머지 작업이 누락되거나 닫힌 인덱스를 만나면 오류를 반환해요. 기본값은 false예요.
max_num_segments Integer 작은 세그먼트들이 머지되는 더 큰 세그먼트의 수예요. 모든 세그먼트를 하나의 세그먼트로 머지하려면 이 파라미터를 1로 설정해요. 기본 동작은 필요에 따라 머지를 수행하는 것이에요.
only_expunge_deletes Boolean true이면 머지 작업이 일정 비율 이상의 삭제된 문서를 포함하는 세그먼트만 expunge해요. 그 비율은 기본적으로 10%이며 index.merge.policy.expunge_deletes_allowed 설정에서 구성할 수 있어요. OpenSearch 2.12 이전에는 only_expunge_deletes가 index.merge.policy.max_merged_segment 설정을 무시했어요. OpenSearch 2.12부터는 only_expunge_deletes를 사용해도 index.merge.policy.max_merged_segment(기본 5GB)보다 큰 세그먼트가 생성되지 않아요. 자세한 내용은 삭제된 문서를 참고해요. 기본값은 false예요.
primary_only Boolean true로 설정하면 머지 작업이 인덱스의 프라이머리 샤드에서만 수행돼요. 머지 완료 후 인덱스의 스냅샷을 만들고 싶을 때 유용해요. 스냅샷은 프라이머리 샤드의 세그먼트만 복사해요. 프라이머리 샤드를 머지하면 리소스 사용을 줄일 수 있어요. 기본값은 false예요.
wait_for_completion Boolean false이면 OpenSearch가 완료를 기다리지 않고 강제 머지 작업을 비동기로 실행해요. 요청은 즉시 반환되고 작업은 백그라운드에서 계속돼요. 진행 상황은 Tasks API로 모니터링할 수 있어요. 기본값이 true이므로 작업은 동기적으로 실행돼요.

요청 예시

다음 예제들은 강제 머지 API 사용법을 보여줘요.

특정 인덱스 강제 머지

다음 예제는 특정 인덱스를 강제 머지해요:

POST /testindex1/_forcemerge

여러 인덱스 강제 머지

다음 예제는 여러 인덱스를 강제 머지해요:

POST /testindex1,testindex2/_forcemerge

모든 인덱스 강제 머지

다음 예제는 모든 인덱스를 강제 머지해요:

POST /_forcemerge

데이터 스트림의 백킹 인덱스를 하나의 세그먼트로 강제 머지

다음 예제는 데이터 스트림의 백킹 인덱스를 하나의 세그먼트로 강제 머지해요:

POST /.testindex-logs/_forcemerge?max_num_segments=1

프라이머리 샤드 강제 머지

다음 예제는 인덱스의 프라이머리 샤드를 강제 머지해요:

POST /.testindex-logs/_forcemerge?primary_only=true

응답 예시

{
  "_shards": {
    "total": 2,
    "successful": 1,
    "failed": 0
  }
}

응답 본문 필드

모든 응답 필드는 아래 표와 같아요.

필드 데이터 타입 설명
shards Object 요청이 실행된 샤드에 대한 정보를 담고 있어요.
shards.total Integer 작업이 실행된 샤드의 수예요.
shards.successful Integer 작업이 성공한 샤드의 수예요.
shards.failed Integer 작업이 실패한 샤드의 수예요.

필요한 권한

보안 플러그인을 사용한다면 다음 권한이 필요해요: indices:admin/forcemerge.

더 알아보기 (Learn more)