검색 리플레이

Show: All versions v2 only

검색 리플레이(Search Replay)는 이전에 캡처된 검색 호출에서 반환된 search_id를 사용해 과거 검색을 다시 실행합니다. 평가, 회귀 테스트(regression testing), 순위 변경의 A/B 비교를 위해 개별 검색 파라미터를 덮어쓸 수 있습니다.

참고: 리플레이(replay)는 버킷(bucket) 검색처럼 검색 세션을 생성하는 검색에 대해 사용할 수 있습니다. 이 엔드포인트는 아직 연합 메모리 검색(federated memory search)을 하나의 논리적 쿼리로 리플레이하지 않습니다.

POST /v1/search/replay

search_id로 과거 검색을 다시 실행합니다.

요청 본문

필드	타입	필수	기본값	설명
search_id	string	예	—	캡처된 검색 호출에서 반환된 ID입니다. 최대 128자입니다.
override	object	아니오	null	재실행에 적용할 선택적 파라미터 덮어쓰기입니다. 덮어쓰기 필드를 참조하세요.
include_original	boolean	아니오	false	캡처된 첫 실행 결과를 응답에 포함합니다.

덮어쓰기 필드

필드	타입	설명
top_k	integer (1–1000)	반환할 결과 개수입니다.
filter	object	검색 필터 객체입니다.
min_score	number (0.0–1.0)	최소 결과 점수입니다.
mode	string	검색 모드 덮어쓰기입니다.
rerank	boolean	재순위화(reranking) 적용 여부입니다.
expand_neighbors	object	이웃 확장(neighbor expansion) 파라미터입니다.

요청 예시

curl -X POST https://api.schift.io/v1/search/replay \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "search_id": "search_abc123",
    "override": {
      "min_score": 0.7,
      "rerank": true
    },
    "include_original": true
  }'

응답

{
  "original": {
    "search_id": "search_abc123",
    "query": "soccer rules offside",
    "bucket_id": "bkt_xyz",
    "created_at": "2026-04-30T12:34:56Z",
    "result_count": 8,
    "results": [
      {
        "id": "chunk-x",
        "score": 0.91,
        "text": "",
        "metadata": { "rank": 1 }
      }
    ]
  },
  "rerun": {
    "search_id": "search_def456",
    "results": [
      {
        "id": "chunk-x",
        "score": 0.89,
        "text": "A player is in an offside position if...",
        "metadata": {}
      }
    ],
    "diff": {
      "added": ["chunk-z"],
      "removed": ["chunk-y"],
      "shared": 5,
      "rank_correlation": 0.83
    }
  }
}

참고: include_original이 true이면 원본 결과 항목은 id, score, 순위 메타데이터만 포함합니다. 원본 청크 텍스트는 검색 이벤트 원장(search event ledger)에 저장되지 않으므로 text 필드는 비어 있습니다.

응답 필드

필드	타입	설명
original	object	캡처된 첫 실행 요약입니다.
original.search_id	string	원본 search_id입니다.
original.query	string	원본 실행의 쿼리 텍스트입니다.
original.bucket_id	string	원본 실행에서 검색한 버킷(bucket) ID입니다.
original.created_at	string | null	원본 세션의 ISO 8601 타임스탬프입니다.
original.result_count	integer	원본 실행에서 캡처된 결과 개수입니다.
original.results	array | null	include_original이 true일 때의 원본 결과 항목입니다.
rerun	object	새 실행 요약입니다.
rerun.search_id	string	재실행의 새 search_id입니다.
rerun.results	array	재실행 결과 항목입니다.
rerun.diff	object	두 결과 집합을 비교하는 diff 메트릭입니다.

diff 메트릭

필드	타입	설명
added	string 배열	재실행에는 있지만 원본에는 없는 ID입니다.
removed	string 배열	원본에는 있지만 재실행에는 없는 ID입니다.
shared	integer	두 결과 집합에 모두 있는 ID 개수입니다.
rank_correlation	number | null	공유 ID에 대한 Spearman 순위 상관계수입니다. 1.0은 동일한 순서, -1.0은 반대 순서를 의미합니다. 공유 ID가 2개 미만이면 null입니다.

오류 예시

404 Not Found — 해당 조직(organization)에 search_id가 존재하지 않습니다.

{
  "detail": "search_id not found for this org"
}

422 Unprocessable Entity — 캡처된 세션에 필요한 쿼리나 버킷 정보가 누락되었습니다.

{
  "detail": "Original search lacks query/bucket — replay not possible"
}

API 버전

검색 리플레이는 v1만 사용할 수 있으며, 폐기 예정인 버전은 없습니다.

제한 사항

• 원본 전체 요청 페이로드 — filter, top_k 등을 포함한 모든 파라미터 — 는 아직 영구 저장되지 않습니다. 따라서 수정하지 않은 리플레이는 비트 단위로 동일한 설정이 아닌 기본 검색 파라미터로 실행됩니다.
• 향후 릴리스에서는 세션 생성 시 전체 BucketSearchRequest를 영구 저장하여 수정하지 않은 리플레이도 재현할 수 있도록 할 예정입니다.

참고 항목

• 버킷(Buckets)
• 필터 연산자
• 메모리 검색