Boost

Boost (부드러운 순위 조정)

검색 결과에서 일부 문서를 제거하지 않고 위로 끌어올리고 싶을 때가 있어요. Boost는 그런 "소프트 랭킹"을 합니다. 조건에 매칭되는 문서는 위로 올라가고, 매칭되지 않는 문서도 결과에 남되 아래로 순위가 내려갑니다. 최신성, 인기도, 소프트 필터 같은 신호로 결과를 치우칠 때 유용합니다.

Boost는 벡터, 하이브리드, BM25, near-text, near-vector, near-object, near-image, near-media 쿼리에 모두 적용할 수 있어요. gRPC 전용 기능이라 REST/curl로는 사용할 수 없습니다.

출처: 공식문서

동작 방식

Boost는 **검색 후 리스코어러(post-retrieval rescorer)**입니다.

  1. 기본 검색(벡터, 하이브리드, BM25 등)이 depth 개의 후보 결과를 가져옵니다. 첫 페이지를 넘어서는 보정을 원하면 depth를 offset + limit보다 높게 설정하세요.
  2. Boost 스코어러가 각 후보에 조건을 평가하고, 결과 집합별로 정규화한 뒤 기본 점수와 블렌딩해 그 후보들을 메모리에서 재점수화합니다. 새로운 인덱스 쿼리는 없어요. 인덱스 팬아웃이 아닌 후보별 인메모리 점수화 비용이 발생합니다.
  3. 사용자의 원래 offset과 limit은 재정렬 이후에 적용됩니다.

조건 타입

Boost는 하나 이상의 조건을 블렌딩한 하나의 리스코어입니다. 각 조건은 filter, 프로퍼티 값, 시간 감쇠, 숫자 감쇠 중 하나입니다.

Filter 조건 (소프트 WHERE)

결과가 필터에 매칭되면 점수가 1, 아니면 0입니다. 매칭되지 않는 문서도 결과에 남되 매칭되는 문서보다 아래로 순위가 내려갑니다. 지원 필터 연산자: Equal, NotEqual, GreaterThan, GreaterThanEqual, LessThan, LessThanEqual, And, Or, Not. (Like, IsNull, 지리 연산자, ref-path 필터는 부스트 조건에서 지원하지 않습니다.)

boost=Boost.filter(
    Filter.by_property("category").equal("research"),
    weight=0.5,
),

프로퍼티 값 조건

숫자 프로퍼티(likes, downloads, popularity 등) 값에 비례한 연속 점수입니다. 원시 값은 선택적으로 변형된 뒤 결과 집합에서 [0, 1]로 min-max 정규화됩니다.

name 인자는 필수이고, 숫자 프로퍼티(int, number)만 지원합니다.

Modifier 효과 사용 시점
NONE (기본) score = value 값이 좁은 범위에 있을 때.
LOG1P score = log(1 + value) 롱테일 감쇠(예: 다운로드 수 5~5_000_000).
SQRT score = sqrt(value) 더 온화한 롱테일 감쇠. 
boost=Boost.numeric_property(
    "likes",
    modifier=Boost.Modifier.LOG1P,
    weight=0.7,
),

시간 감쇠 (Time decay)

원점(origin) 시간으로부터의 거리에 따라 감쇠하는 연속 [0, 1] 점수입니다. 대표적인 용도는 "더 최근 문서를 부스트"입니다.

파라미터 필수 설명
property Yes date 프로퍼티 이름.
origin No "now"(기본), datetime, 또는 ISO 문자열.
scale Yes 점수가 decay와 같아지는 거리. timedelta 또는 기간 문자열("7d", "6h", "30m").
offset No 점수가 정확히 1이 되는 거리. 기본 0.
curve No EXPONENTIAL(기본), GAUSSIAN, LINEAR.
decay No scale 거리에서의 점수. 기본 0.5. 범위 (0, 1]. 
boost=Boost.time_decay(
    "published",
    origin="now",
    scale=timedelta(days=30),
    curve=Boost.Curve.EXPONENTIAL,
    decay=0.5,
    weight=0.6,
),

숫자 감쇠 (Numeric decay)

시간 감쇠와 같지만 숫자(int, number) 프로퍼티용입니다. "특정 값 X에 가까울수록 좋다"일 때 씁니다—목표 가격, 좌표 근처의 거리, 특정 대역 근처의 나이 등. scale/offset/decay/curve 의미는 시간 감쇠와 동일하며 값은 숫자로 표현합니다.

scale은 > 0이어야 하고, decay(설정 시)는 (0, 1]이어야 해요.

boost=Boost.numeric_decay(
    "price",
    origin=49.99,
    scale=10.0,
    curve=Boost.Curve.GAUSSIAN,
    decay=0.5,
    weight=0.5,
),

곡선(Curves)

세 가지 감쇠 곡선은 거리에 따라 점수가 떨어지는 형태를 정합니다. distance == 0이면 점수는 항상 1, distance == scale이면 항상 정확히 decay입니다.

곡선 형태 사용 시점
EXPONENTIAL (기본) 무거운 꼬리: 원점 지나 scale마다 점수가 기하급수적으로 반감 "최신성이 중요하지만 오래된 항목을 0으로 밀어내진 않는" 경우
GAUSSIAN 종 모양: scale 넘어서 급격히 감쇠 "원점 근처는 훌륭, 멀어지면 거의 무가치"
LINEAR 직선: scale 지나 유한 거리에서 0 도달 "명확한 컷오프가 있는 예측 가능한 감쇠"

이 세 값만 허용됩니다. 다른 값은 요청 시점에 거부됩니다.

블렌딩과 가중치

Boost는 최소 1개, 최대 20개의 조건을 가져야 해요. Boost.blend(...)로 여러 조건을 하나의 리스코어로 결합합니다. 각 조건은 자체 weight(기본 1.0)를 가질 수 있고, 바깥 weight(기본 0.5)는 결합된 부스트가 최종 점수에 얼마나 영향을 주는지 제어합니다.

final_score = (1 − weight) · primary_norm + weight · boost_norm
  • weight: 바깥 블렌딩 가중치, [0, 1]. 기본 0.5.
  • weight: 0: no-op. 부스트가 short-circuit되고 기본 결과가 그대로 반환됩니다.
  • 조건별 weight: float 기본 1.0. 여러 부스트 균형(예: "최신성이 인기도보다 2배 중요")을 맞출 때 사용.
  • 음수 조건별 weight: 매칭 문서를 낮춥니다. 결과에는 남지만 매칭되지 않은 문서보다 아래로 순위가 내려갑니다.
boost=Boost.blend(
    [
        Boost.time_decay("published", origin="now", scale=timedelta(days=30), weight=2.0),
        Boost.numeric_property("likes", modifier=Boost.Modifier.LOG1P, weight=1.0),
    ],
    weight=0.4,
    depth=200,  # 벡터 매치 상위 200개 리스코어
),

깊이(depth)와 페이지네이션

depth는 후보 풀을 제어합니다. 기본 검색이 부스트 리스코어러 실행 전에 depth개의 결과를 가져옵니다. 리스코어 후 사용자의 offset과 limit이 적용됩니다.

프로퍼티 값
기본값 100
연산자 오버라이드 QUERY_BOOST_DEFAULT_DEPTH 환경변수
하드 캡 QUERY_MAXIMUM_RESULTS (클러스터 전역 한도)
하한 최소 offset + limit (페이지를 채울 만큼 항상 보임)
허용 범위 ≥ 0, 0이면 "기본값 사용"

:::tip 기본 top-100을 넘어 재정렬하려면 depth를 올리세요 Boost는 기본 검색이 이미 가져온 것만 재정렬할 수 있어요. 기본 top-100을 넘어서까지 재정렬해야 한다면(인기 있는 오래된 글을 1페이지로 끌어올리는 등) 쿼리에 더 높은 depth를 넘기세요. 단, depth가 클수록 기본 검색(BM25/벡터 인덱스 작업)과 후보별 점수화 비용이 늘어납니다. 사용 사례에 맞게 최대한 타이트하게 설정하세요. :::

더 알아보기 (Learn more)