인덱스 리프레시 API

인덱스 리프레시 API (Refresh Index API)

1.0부터 도입되었어요.

인덱스 리프레시(Refresh Index) API는 하나 이상의 인덱스를 리프레시해서 마지막 리프레시 이후 그 인덱스에서 수행된 모든 작업을 검색할 수 있게 해 줘요. 문서를 인덱싱하면 먼저 트랜스로그(translog)에 기록되고 인메모리 버퍼에 추가돼요. 리프레시 작업이 이 인메모리 구조를 디스크의 검색 가능한 세그먼트로 변환하기 전까지는 문서를 검색할 수 없어요. 데이터 스트림의 경우 리프레시 인덱스 API는 스트림의 백킹 인덱스를 리프레시해요.

OpenSearch에서 리프레시 작업이 어떻게 동작하는지에 대한 개념적 개요는 Refresh를 참고해요.

출처: 문서

본문

리프레시 주기

index.refresh_interval 설정은 인덱스가 자동으로 리프레시되는 빈도를 제어해요. OpenSearch의 리프레시 동작은 index.refresh_interval이 설정되었는지에 따라 달라져요:

설정되면 인덱스는 index.refresh_interval 설정(초 단위)에 따라 리프레시돼요. index.refresh_interval 설정에 대한 자세한 내용은 Dynamic index-level index settings를 참고해요.
설정되지 않으면 샤드가 index.search.idle.after 설정(초 단위)이 지정한 시간 이상 검색 요청을 받지 않을 때까지 매초 리프레시돼요. 기본값은 30s예요.

샤드가 유휴 상태가 된 후에는 다음 검색 요청이나 리프레시 인덱스 API 요청이 올 때까지 인덱스가 리프레시되지 않아요. 유휴 샤드에 대한 첫 검색 요청은 리프레시 작업이 완료될 때까지 기다려요.

리프레시 인덱스 API를 사용하려면 리프레시할 인덱스에 대한 쓰기 권한이 필요해요.

리프레시 요청 동작

리프레시 인덱스 API 호출은 동기적이에요. 대상이 되는 모든 샤드가 리프레시된 후에만 응답이 반환돼요.

모범 사례

리프레시 작업은 리소스를 많이 사용하며 클러스터 성능에 영향을 줄 수 있어요. 최적의 클러스터 성능을 위해 다음 모범 사례를 권장해요:

자동 리프레시에 의존하기: 가능하면 명시적으로 리프레시를 수행하기보다 OpenSearch의 주기적 리프레시(index.refresh_interval이 제어)를 기다려요.
인덱싱 워크플로에는 refresh=wait_for 사용하기: 애플리케이션이 문서를 인덱싱한 직후 그 문서를 검색한다면 리프레시 API를 호출하는 대신 인덱싱 작업에 refresh=wait_for 쿼리 파라미터를 사용해요. 이 옵션은 즉시 리프레시를 강제하지 않고 인덱싱 작업이 반환되기 전에 주기적 리프레시를 기다리도록 해 줘요. 자세한 내용은 The refresh query parameter를 참고해요.
프로덕션에서 refresh=true 피하기: index, update, delete 작업에 refresh=true를 사용하면 즉시 리프레시를 강제하고 나중에 머지해야 하는 비효율적인 인덱스 구조(작은 세그먼트)를 만들어 인덱싱과 검색 성능 모두에 영향을 줘요.

엔드포인트

POST /_refresh
GET /_refresh
POST /{index}/_refresh
GET /{index}/_refresh

경로 파라미터

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

파라미터	데이터 타입	설명
`index`	String	리프레시할 인덱스 이름의 쉼표로 구분된 목록이에요. 와일드카드를 지원해요.

쿼리 파라미터

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

파라미터	데이터 타입	설명
`ignore_unavailable`	Boolean	`false`이면 요청이 누락되었거나 닫힌 인덱스를 대상으로 할 때 오류를 반환해요. 기본값은 `false`예요.
`allow_no_indices`	Boolean	`false`이면 요청이 열린 인덱스에 대해 이루어지더라도 와일드카드 표현식, 인덱스 별칭, 또는 `_all`이 닫히거나 누락된 인덱스만 대상으로 하면 리프레시 인덱스 API가 오류를 반환해요. 기본값은 `true`예요.
`expand_wildcards`	String	와일드카드 패턴이 일치할 수 있는 인덱스 유형이에요. 요청이 데이터 스트림을 대상으로 한다면 이 인자는 와일드카드 표현식이 숨은 데이터 스트림과 일치하는지 여부를 결정해요. `open,hidden` 같은 쉼표로 구분된 값을 지원해요. 유효한 값은 `all`, `open`, `closed`, `hidden`, `none`이에요.

요청 예시: 여러 데이터 스트림 또는 인덱스 리프레시

다음 요청 예시는 my-index-A와 my-index-B라는 두 인덱스를 리프레시해요:

POST /my-index-A,my-index-B/_refresh

요청 예시: 모든 데이터 스트림과 인덱스 리프레시

다음 요청은 클러스터의 모든 데이터 스트림과 인덱스를 리프레시해요:

POST /_refresh

요청 예시: GET 메서드로 리프레시

GET 메서드로도 인덱스를 리프레시할 수 있어요. 다음 예제는 GET을 사용해 특정 인덱스를 리프레시해요:

GET /my-index/_refresh

GET 메서드는 POST 메서드와 동일하게 동작하며, POST 요청이 제한된 환경이나 읽기 같은 작업에 GET을 선호하는 경우에 유용해요.

refresh 쿼리 파라미터

Index, Update, Delete, Bulk 같은 문서 API는 요청으로 인한 변경 사항이 언제 검색에 노출되는지 제어하는 refresh 쿼리 파라미터를 지원해요. 이 파라미터는 리프레시 인덱스 API를 명시적으로 호출하는 대안을 제공해요.

refresh 파라미터에 대한 자세한 내용은 Index Document API, Update Document API, Delete Document API, Bulk API 문서를 참고해요.

필요한 권한

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

더 알아보기 (Learn more)

OpenSearch 공식 문서