search_after API 로 OpenSearch에서 10,000건 이상 Pagination 안되는 문제 해결하기

best practice 가 아닐 수 있습니다. 참고 해주시면 감사하겠습니다.

문제 상황

OpenSearch에서 from과 size를 활용해 페이징 쿼리를 요청하던 중, 데이터가 10,000건을 넘어가면서 다음과 같은 에러가 발생했습니다.

"Result window is too large, from + size must be less than or equal to: [10000] but was [10008]. 
See the scroll api for a more efficient way to request large data sets. 
This limit can be set by changing the [index.max_result_window] index level setting."

OpenSearch(ElasticSearch) 는 깊은 페이지를 조회하는 것은 성능에 상당한 부담이 되기 때문에 기본 설정상 from + size가 10,000을 초과할 수 없다는 제약이었습니다.

Querying for pages deep in your results can have a significant performance impact, so OpenSearch limits this approach to 10,000 results.

 

기존 방식은 정책으로 10,000건 이상 조회 시, 페이징을 하지 않고 "10,000+ 건" 을 UI 에 보여주며 정책으로 해결했습니다.

하지만, 고객사의 요청에 따라 10,000건 이상의 페이징을 요구받았고, 그 과정을 설명합니다.

 

저의 총 데이터는 13,000건 입니다.

 

해결 방법 대안 및 결정 

이 문제를 해결하고자 Paginate Results 에서 3가지 대안을 찾았습니다.

• Scroll API
• index.max_result_window 설정 값 증가
• search_after API

이 중, search_after API 를 선택한 이유를 설명합니다.

 

1. Scroll API

문서에 따르면 Scroll API는 스크롤을 이용해 대용량 데이터를 조회하는 방법입니다. 각 샤드의 인덱스마다 어디까지 읽었는지, 데이터의 읽은 위치를 메모리에 저장한다고 합니다.

 

그러다 보니, 웹 환경같이 사용자의 요청이 빈번할 때 scroll API 를 사용하면 사용자마다 scroll 의 위치를 저장해야 하니 메모리 사용량이 많아지게 됩니다.

Because open search contexts consume a lot of memory, we suggest you don’t use the scroll
 operation for frequent user queries that don’t need the search context to be open

 

그래서 OpenSearch에서도 대용량 머신러닝 작업 같은 배치 처리에 권장하고 있습니다.

If you need to request volumes of data larger than 1 PB from, for example, a machine learning job, use the scroll operation instead. The scroll operation allows you to request an unlimited number of results.

 

저는 웹 환경에서 페이징을 해야하기 때문에 선택하지 않았습니다.

 

2. index.max_result_window 증가

index.max_result_window 설정값을 늘려 OpenSearch의 기본 설정된 10,000건을 우회해서 from + size 를 사용할 수 있지만, 선택하지 않았습니다.

 

첫 번째 이유는 성능 문제입니다.

from + size 방식은 offset 기반 페이징으로, offset 이 커질수록 읽은 데이터를 버리기 때문에 대용량 데이터에서 적합하지 않습니다. 예를 들어 10만 번째 offset(from) 부터 10건을 조회하려면, 앞의 10만 건을 모두 읽고 버려야 합니다.

 

두 번째 이유는 설치 복잡성입니다.

제 회사는 솔루션을 온프레미스에 설치하는 형태입니다. 공공기관마다 데이터 양이 다를 텐데, 그때마다 index에 설정값을 변경해야 하는 복잡성을 낮추고 싶었습니다.

 

설치 시, 설정값을 하나라도 줄이는 것이 좋다고 판단했습니다.

 

3. search_after API

search_after는 이전 페이지의 결과를 이용해서 다음 페이지의 결과를 얻는 방법입니다.

문서를 읽어보면 search_after 는 커서 기반 페이징과 유사한 것 같습니다.

 

특히, search_after 문서 내용에 해당 API를 정렬 조건과 함께 써야 하는 것이 명시되어 있습니다.

The search_after parameter provides a live cursor that uses the previous page’s results to obtain the next page’s results. ... You can use search_after only when sorting is applied.

 

이는 MySQL의 인덱스가 정렬되어 있다는 것을 이용해 커버링 인덱스로 PK를 가져오고, PK로 다시 조회하여 대용량 데이터를 빠르게 페이징 처리할 수 있는 방식을 생각하면 search_after 사용 시 정렬 조건을 함께 써야하는 것이 이해가 갑니다.

 

다만, search_after 는 stateless(무상태) 방식이기 때문에 실시간으로 인덱스가 업데이트되거나 삭제될 경우 결과의 일관성이 보장되지 않아 데이터 누락이 발생할 수 있습니다. 즉, 배치처리에 search_after 를 사용한다면 배치 도중에 데이터가 누락될 수 있다는 단점이 있습니다.

 

이를 위해 OpenSearch는 이러한 일관성 문제를 해결하기 위해 PIT (Point In Time) API를 지원합니다.

PIT는 쿼리 시점에 스냅샷을 찍어 해당 시간 동안(쿼리의 파라미터로 준 시간) 일관된 읽기를 보장할 수 있다고 합니다.

 

본론으로 돌아와 제 상황은 새벽 3시에 10분정도 일괄적으로 인덱싱을 완료되며 사용자가 조회 중에는 추가 인덱싱이 발생하지 않아 일관된 읽기가 비즈니스 특성 상 보장됩니다. 물론, 해당 페이징을 하려는 기능은 도중에 데이터가 추가되어도 괜찮습니다.

 

따라서 PIT 없이 search_after 를 사용하기로 결정했습니다.

구현 상세: from/size 방식과 search_after 방식의 비교 및 적용

1. 기존 구현 방식: from/size (Offset 기반 페이징)

from과 size를 활용한 방식은 가장 기본적인 Offset 기반 페이징입니다.

 

기존에는 10,000건 이상의 데이터 조회 요구사항이 없어, hits.total.value가 10,000건이고 relation이 gte일 경우 백오피스 UI 상에서 '10,000+'로 표시하고 최대 10,000건까지만 페이징을 제공했습니다

 

이를 위해 page와 limit을 파라미터로 받아 OpenSearch 쿼리를 구성했었습니다.

String query = """
    {
      "from": %d, // (page - 1) * limit
      "size": %d,
      "query": {
          "match": {
            "meta_id": %s
          }
      },
      "_source": {
        "excludes": ["..."]
      },
      "sort": [
        { "meta_id": "ASC" } // 정렬 조건
      ]
    }
""".formatted((page - 1) * limit, limit, meta_id);

 

이 결과에서 페이징 처리를 위해 hits.total.value 와 hits.total.relation 으로 판단합니다.

value 가 10,000 이고 relation 이 "gte" 라면, UI 상에서 "10,000+" 를 보여주고, 그 전까진 offset 방식으로 페이징 처리하면 됩니다.

 

2. 개선된 구현 방식: search_after (커서 기반 페이징)

10,000건 초과 페이징 요구사항을 해결하기 위해 RDB의 커서 기반 페이징 방식과 같다고 생각하는 search_after를 도입했습니다.

이 방식은 이전 페이지의 마지막 결과(커서)를 기준으로 다음 페이지를 조회합니다.

 

검색 요청 시(GET {index_name}/_search), 이전 페이지의 마지막 meta_id 값인 lastMetaId를 파라미터로 전달받아 search_after를 구성합니다.

 

이 lastMetaId 는 이전 페이지를 sort 로 정렬했을 때의 마지막 데이터에 있는 sort 필드(meta_id)의 값을 뜻합니다. 

 

클라이언트로가 lastMetaId 를 null 로 준다면 첫 페이지를 조회하는 것이기 때문에 아래와 같이 쿼리를 구성할 수 있습니다.

// search_after 파라미터 구성
String searchAfterQuery = "";
if (request.lastMetaId() != null) {
    searchAfterQuery = """
          "search_after": ["%s"],
          """.formatted(request.lastMetaId());
}
    
// 검색 쿼리 {index_name}/_search
String searchQuery = """
    {
      "size": %s,
      %s
      "sort": {
         "meta_id": "asc"  // search_after 사용 시 정렬 조건 필수
       },
      "_source": ["meta_id", "title", "createdAt", "sort"]
    }
    """.formatted(limit, searchAfterQuery);

 

하지만, search_after 방식은 전체 데이터 수를 알 수 없기 때문에 다음 페이지 그룹으로 이동하는 버튼(>)의 활성화 여부를 판단하기 위해 별도의 count 쿼리가 필요합니다.

 

버튼(>) 활성화를 위해 전체 count 를 할 수 있지만, OpenSearch 는 응답 개수를 10,000개로 기본 값을 제어하고 있습니다.

이는 성능 상 10,000건 이상의 데이터를 조회하지 않게 하려는 의도가 담겨있다고 생각을 했기 때문에 _count API 를 사용하지 않고 전체 카운트 대신 필요한 범위까지만 카운트하고자 했습니다.

 

예를 들어, 한 화면에 10개의 페이지가 있다고 할 때 (1~10, 11~20 등) 이동 버튼(>)의 활성화 여부를 알기 위해서는 아래 공식을 사용할 수 있습니다. 만약 한 화면에 5개의 페이지씩 보여준다면 10L 대신 5L 이 공식에 들어갑니다.

Long pageLimit = ((page - 1) / 10L + 1) * limit * 10L + 1;

 

이 공식과 함께 track_total_hits 파라미터를 사용했습니다.

 

track_total_hits 는 매칭되는 문서의 개수가 특정 임계값(예: 10,000개)을 초과할 경우, 정확한 전체 개수를 반환하지 않습니다. 대신 10000을 반환하고, relation 값을 gte (greater than or equal to, 이상)로 표시합니다.

The number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query

 

쿼리는 다음과 같습니다.

// count 쿼리
// 한 화면에 10개의 페이지가 있다고 가정(1~10, 11~20, 21~30)
Long pageLimit = ((page - 1) / 10L + 1) * limit * 10L + 1;
// {index_name}/_search
String countQuery = """
    {
      "size": 0,       
      "track_total_hits": %d
    }
    """.formatted(pageLimit);

 

_search API에 track_total_hits 옵션을 설정하면, 응답 결과에서 hits.total.value와 hits.total.relation 값을 얻을 수 있습니다.

이 두 값을 기준으로 다음 페이지 그룹으로 이동하는 버튼(>)의 활성화 여부를 판단했습니다.

 

만약, 1~10페이지를 보여줄 때, pageLimit 의 결과는 101이 됩니다. 이 때, hits.total.value 가 101, hits.total.relation 이 gte 가 나오면 ">" 버튼을 활성화 합니다.

 

1. 첫 페이지 그룹(1~10페이지)에서 다음 그룹 존재 여부 확인

• 1~10페이지(Limit 10 기준)를 보여주는 상황에서, 다음 페이지 그룹이 존재하는지 확인하기 위해 pageLimit을 101로 설정합니다.
• 만약, hits.total.value가 101이고, hits.total.relation이 gte (크거나 같음)로 반환된다면, 이는 데이터가 101건 이상 존재한다는 의미이므로 > 버튼을 활성화합니다.

2. 다음 페이지 그룹(11~20페이지)에서 마지막 페이지 확인

• 사용자가 > 버튼을 클릭하여 11페이지를 요청합니다.
• 11~20페이지 그룹에 속해있는 상황에서, 다음 그룹(21페이지)이 있는지 확인하기 위해 pageLimit을 201로 설정합니다.
• 요청에 대한 결과로 hits.total.value가 145이고, hits.total.relation이 eq (같음)로 반환된다면, 이는 데이터가 145건까지 정확히 존재한다는 의미입니다.
• 따라서 11~20페이지 그룹 내에서 15페이지까지만 데이터가 있으며, 그 이후 페이지는 없다는 것을 알 수 있습니다. 이 경우 > 버튼은 비활성화됩니다.

하지만, 이 방식으로 다음 페이지 그룹으로 이동 버튼(>) 을 구현 할 수 있지만, 총 개수는 여전히 모르기 때문에 마지막 페이지로 한 번에 갈 수 없습니다. 

 

이는 정렬 옵션을 asc 로 주던 것을 desc 로 변경하여 해결 하였습니다.

 

추가 고려 사항: YML 설정에 따라 Bean 주입하기

기존에는 10,000건 이상의 데이터 조회 요구사항이 없어, hits.total.value가 10,000건이고 relation이 gte일 경우 백오피스 UI 상에서 '10,000+'로 표시하고 최대 10,000건까지만 페이징을 제공했습니다

 

하지만, "10,000건 이상의 문서도 최대한 모두 볼 수 있으면 좋겠다"는 이번 고객사의 요구사항에 맞춰 search_after를 적용했습니다.

그러다 보니 향후 다른 고객사에서도 이와 같은 요구사항이 발생할 수 있다고 판단하여, 환경 설정(YML) 값에 따라 기존의 Offset 방식(from/size)과 새로운 커서 기반(search_after) 방식 중 하나를 선택적으로 주입하고자 했습니다. 아래는 그 구현 예시입니다.

 

아래 처럼 @ConditionalOnProperty 를 사용해 yml 이 가지는 값을 기준으로 빈을 등록하고, 설정값이 없을 경우도 고려해 기본 값도 설정 했습니다.

@Slf4j
@Configuration
public class OpenSearchQueryServiceConfig {

    @Bean
    @ConditionalOnProperty(name = "opensearch.search.offset.enabled", havingValue = "true", matchIfMissing = true)
    public OpenSearchQueryService openSearchOffsetQueryService(..., OpenSearchRestClient openSearchRestClient) {
        return new OpenSearchOffsetQueryService(..., openSearchRestClient);
    }

    @Bean
    @ConditionalOnProperty(name = "opensearch.search.offset.enabled", havingValue = "false")
    public OpenSearchQueryService openSearchSearchAfterQueryService(..., OpenSearchRestClient openSearchRestClient) {
        return new OpenSearchSearchAfterQueryService(..., openSearchRestClient);
    }
}

 

하지만, 위 방식은 하나의 API 엔드포인트에서 YML 설정에 따라 내부 동작 방식이 달라지고, 그 결과 API 서버가 요구하는 Query Parameter(Offset 방식은 page, limit / search_after 방식은 lastMetaId, limit)가 달라지는 문제가 발생했습니다.

 

이는 프론트엔드 코드의 분기문을 늘려 불필요한 복잡성을 유발한다고 판단했습니다.

 

따라서, YML에 따른 Bean 주입 대신 API를 분리하기로 결정했습니다.

• Offset 기반 페이징: /api/offset
• search_after 기반 페이징: /api/cursor

Query Parameter가 달라지는 경우, 코드를 우아하게 통합하려 하기보다는 API를 명확하게 분리하는 것이 협업과 유지보수 측면에서 더 효율적이라는 것을 배울 수 있었습니다.

 

마무리

추가 학습 포인트, Doc Value 란?

MySQL 은 세컨더리 인덱스를 활용해 커버링 인덱스로 where 조건에 맞는 PK를 가져온 후 PK를 바탕으로 select 절을 처리하는 방식으로 대용량 데이터를 빠르게 처리합니다. 이는 인덱스가 미리 정렬되어 있다는 특성을 이용한 것입니다.

 

OpenSearch 는 정렬과 집계를 위해 Doc values 를 사용한다고 합니다. Doc values가 어떤 방식으로 구성되어 있기에 OpenSearch에서 빠른 정렬이 가능한지, 역 인덱스와는 어떻게 다른지 추가 학습이 필요하다고 생각합니다.

 

추후에 학습 후, 포스팅해보겠습니다.

 

참고 자료

• OpenSearch Paginate Results
• Point In Time API
• Doc Values 파라미터
• 다나와의 Elasticsearch Search After 성능 체크(읽어 볼만한 자료)