rewrite 파라미터

wildcard, prefix, regexp, fuzzy, range 같은 다중 용어 쿼리(multi-term query)는 내부적으로 용어 세트로 확장돼요. rewrite 파라미터를 사용하면 이러한 용어 확장이 어떻게 실행되고 점수가 매겨지는지 제어할 수 있습니다.

다중 용어 쿼리가 많은 용어로 확장되면(예: prefix: "error*"가 수백 개의 용어와 일치) 내부적으로 term 쿼리로 변환돼요. 이 과정에는 다음과 같은 단점이 있을 수 있어요.

indices.query.bool.max_clause_count 한도(기본값 1024)를 초과할 수 있어요.
일치하는 문서의 점수 계산 방식에 영향을 줄 수 있어요.
사용된 rewrite 방식에 따라 메모리와 지연 시간에 영향을 줄 수 있어요.

rewrite 파라미터는 다중 용어 쿼리가 내부적으로 어떻게 동작할지 제어할 수 있게 해줘요.

모드	점수	성능	참고
constant_score	모든 일치에 동일한 점수	최상	기본 모드, 필터에 이상적
scoring_boolean	TF/IDF 기반	보통	전체 관련성 점수 계산
constant_score_boolean	동일한 점수지만 Boolean 구조	보통	must_not 또는 minimum_should_match와 함께 사용
top_terms_N	상위 N개 용어에 TF/IDF	효율적	확장을 잘라냄
top_terms_boost_N	정적 boost	빠름	덜 정확
top_terms_blended_freqs_N	혼합(blended) 점수	균형	최상의 점수/효율 절충

출처: 문서

본문

사용 가능한 rewrite 방식 (Available rewrite methods)

다음 표는 사용 가능한 rewrite 방식을 요약해요.

constant_score (기본값): 확장된 모든 용어를 단일 단위로 함께 평가해 모든 일치에 동일한 점수를 부여해요. 일치하는 문서를 개별적으로 점수 매기지 않으므로 필터링 용도에 매우 효율적이에요.
scoring_boolean: 쿼리를 일치당 하나의 term 쿼리가 있는 Boolean should 절로 분해해요. 각 결과는 관련성을 기준으로 개별적으로 점수가 매겨져요.
constant_score_boolean: scoring_boolean과 비슷하지만 용어 빈도와 관계없이 모든 문서가 고정 점수를 받아요. TF/IDF 가중치 없이 Boolean 구조를 유지해요.
top_terms_N: N개의 가장 빈번한 용어로 점수 계산과 실행을 제한해요. 리소스 사용을 줄이고 절 과부하를 방지해요.
top_terms_boost_N: top_terms_N과 같지만 전체 점수 계산 대신 정적 부스팅을 사용해요. 단순화된 관련성으로 성능 개선을 제공해요.
top_terms_blended_freqs_N: 상위 N개 일치 용어를 선택하고 문서 빈도를 평균해 점수를 매겨요. 전체 용어 폭발 없이 균형 잡힌 점수를 생성해요.

Boolean 기반 rewrite 한도 (Boolean-based rewrite limits)

scoring_boolean, constant_score_boolean, top_terms_* 같은 모든 Boolean 기반 rewrite는 다음 동적 클러스터 레벨 인덱스 설정의 적용을 받아요.

indices.query.bool.max_clause_count

이 설정은 허용되는 최대 Boolean should 절 수(기본값 1024)를 제어해요. 쿼리가 이 한도보다 많은 절로 확장되면 HTTP 400 Bad Request 응답으로 too_many_clauses 오류가 나며 거부됩니다. 마찬가지로 쿼리와 모든 하위 항목이 누적되어 이 한도보다 많은 총 절 수로 확장되면 HTTP 400 Bad Request 응답으로 too_many_nested_clauses 오류가 나며 거부됩니다.

예를 들어 "error*" 같은 wildcard는 수백 또는 수천 개의 일치 용어("error", "errors", "error_log", "error404" 등)로 확장될 수 있어요. 각 용어는 별도의 term 쿼리가 됩니다. 용어 수가 indices.query.bool.max_clause_count 한도를 초과하면 쿼리가 실패해요.

POST /logs/_search
{
  "query": {
    "wildcard": {
      "message": {
        "value": "error*",
        "rewrite": "scoring_boolean"
      }
    }
  }
}

쿼리는 내부적으로 다음과 같이 확장돼요.

{
  "bool": {
    "should": [
      { "term": { "message": "error" } },
      { "term": { "message": "errors" } },
      { "term": { "message": "error_log" } },
      { "term": { "message": "error404" } },
      ...
    ]
  }
}

상수 점수 (Constant score)

기본값인 constant_score rewrite 방식은 확장된 모든 용어를 단일 쿼리로 감싸고 점수 계산 단계를 완전히 건너뜁니다. 이 접근 방식의 특징은 다음과 같아요.

모든 용어 일치를 단일 비트 배열 쿼리로 실행해요.
점수 계산을 완전히 무시하고, 모든 문서가 _score 1.0을 받아요.
가장 빠른 옵션이며 필터링에 이상적이에요.

다음 예제는 기본 constant_score rewrite 방식을 사용한 wildcard 쿼리를 실행해 message 필드에서 warning* 패턴과 일치하는 문서를 효율적으로 필터링해요.

POST /logs/_search
{
  "query": {
    "wildcard": {
      "message": {
        "value": "warning*"
      }
    }
  }
}

점수 Boolean (Scoring Boolean)

scoring_boolean rewrite 방식은 확장된 용어를 Boolean should 절 아래 결합된 별도의 term 쿼리로 분해해요. 이 접근 방식은 다음과 같이 동작해요.

wildcard를 Boolean should 절 안의 개별 term 쿼리로 확장해요.
각 문서의 점수는 일치하는 용어 수와 용어 빈도를 반영해요.

다음 예제는 scoring_boolean rewrite 구성을 사용해요.

POST /logs/_search
{
  "query": {
    "wildcard": {
      "message": {
        "value": "warning*",
        "rewrite": "scoring_boolean"
      }
    }
  }
}

상수 점수 Boolean (Constant score Boolean)

constant_score_boolean rewrite 방식은 scoring_boolean과 동일한 Boolean 구조를 사용하지만 점수 계산을 비활성화해, 관련성 순위 없이 절 로직이 필요할 때 유용해요. 이 방식의 특징은 다음과 같아요.

scoring_boolean과 구조가 비슷하지만 문서가 순위가 매겨지지 않아요.
모든 일치 문서가 동일한 점수를 받아요.
순위 없이 must_not을 사용하는 등 Boolean 절의 유연성을 유지해요.

다음 예제 쿼리는 must_not Boolean 절을 사용해요.

POST /logs/_search
{
  "query": {
    "bool": {
      "must_not": {
        "wildcard": {
          "message": {
            "value": "error*",
            "rewrite": "constant_score_boolean"
          }
        }
      }
    }
  }
}

이 쿼리는 내부적으로 다음과 같이 확장돼요.

{
  "bool": {
    "must_not": {
      "bool": {
        "should": [
          { "term": { "message": "error" } },
          { "term": { "message": "errors" } },
          { "term": { "message": "error_log" } },
          ...
        ]
      }
    }
  }
}

상위 용어 N (Top terms N)

top_terms_N 방식은 다중 용어 쿼리를 확장할 때 점수 정확도와 성능의 균형을 맞추기 위해 설계된 여러 rewrite 옵션 중 하나예요. 다음과 같이 동작해요.

일치하는 가장 빈번한 N개 용어만 선택되고 점수가 매겨져요.
대규모 용어 확장이 예상될 때 부하를 제한하고 싶을 때 유용해요.
성능 유지를 위해 다른 유효한 용어는 무시돼요.

다음 쿼리는 top_terms_2 rewrite 방식을 사용해 message 필드에서 warning* 패턴과 일치하는 가장 빈번한 두 용어만 점수 매겨요.

POST /logs/_search
{
  "query": {
    "wildcard": {
      "message": {
        "value": "warning*",
        "rewrite": "top_terms_2"
      }
    }
  }
}

상위 용어 boost N (Top terms boost N)

top_terms_boost_N rewrite 방식은 상위 N개 일치 용어를 선택하고 전체 관련성 점수 대신 정적 boost 값을 적용해요. 다음과 같이 동작해요.

top_terms_N처럼 확장을 상위 N개 용어로 제한해요.
TF/IDF를 계산하는 대신 각 용어에 사전 설정된 boost를 부여해요.
예측 가능한 관련성 가중치로 더 빠른 실행을 제공해요.

다음 예제는 top_terms_boost_2 rewrite 파라미터를 사용해요.

POST /logs/_search
{
  "query": {
    "wildcard": {
      "message": {
        "value": "warning*",
        "rewrite": "top_terms_boost_2"
      }
    }
  }
}

상위 용어 혼합 빈도 N (Top terms blended frequencies N)

top_terms_blended_freqs_N rewrite 방식은 상위 N개 일치 용어를 선택하고 문서 빈도를 혼합해 더 균형 잡힌 관련성 점수를 생성해요. 이 접근 방식의 특징은 다음과 같아요.

상위 N개 일치 용어를 선택하고 모든 용어에 혼합 빈도를 적용해요.
혼합 덕분에 빈도가 다른 용어 간 점수 계산이 더 부드러워져요.
현실적인 점수 계산과 함께 성능을 원할 때 좋은 절충안이에요.

다음 예제는 top_terms_blended_freqs_2 rewrite 파라미터를 사용해요.

POST /logs/_search
{
  "query": {
    "wildcard": {
      "message": {
        "value": "warning*",
        "rewrite": "top_terms_blended_freqs_2"
      }
    }
  }
}

더 알아보기 (Learn more)

OpenSearch 공식 문서