Explain API

Explain API

1.0에서 도입

Explain API는 특정 문서가 쿼리와 일치하거나 일치하지 않는 이유에 대한 상세 정보를 반환해요. 이 API는 OpenSearch가 각 검색 결과의 관련성 점수(_score)를 어떻게 계산하는지 이해하는 데 도움을 줘서, 검색 관련성 문제를 디버깅하고 쿼리를 최적화하는 데 필수적인 도구예요.

OpenSearch는 Okapi BM25라는 확률 기반 랭킹 프레임워크로 관련성 점수를 계산해요. Okapi BM25는 Apache Lucene이 쓰는 원래 term frequency/inverse document frequency (TF/IDF) 프레임워크를 기반으로 해요.

Explain API는 리소스와 시간 양쪽 모두 비용이 많이 들어요. 프로덕션 클러스터에서는 트러블슈팅 목적으로만 아껴서 사용하기를 권장해요.

출처: 문서

본문

제한 사항 (Limitations)

Explain API는 search_pipeline 매개변수를 지원하지 않아요. 인라인 또는 명명된 검색 파이프라인을 담은 요청을 보내면 parsing_exception 오류가 발생해요. 이는 모든 쿼리 유형에 적용돼요.

explain에서 검색 파이프라인 프로세서를 사용하려면 Search API에 explain=true 쿼리 매개변수를 제공해요. 하이브리드 쿼리에서 explain을 사용하는 방법은 Hybrid search explain을 참고해요.

엔드포인트 (Endpoints)

GET  /{index}/_explain/{id}
POST /{index}/_explain/{id}

경로 매개변수 (Path parameters)

다음 표는 사용 가능한 경로 매개변수예요.

쿼리 매개변수 (Query parameters)

인덱스와 문서 ID를 지정해야 해요. 나머지 매개변수는 모두 선택 사항이에요.

요청 본문 필드 (Request body fields)

요청 본문에는 지정된 문서에 대해 설명할 쿼리가 들어 있어요. 다음 표는 사용 가능한 요청 본문 필드예요.

예시: match 쿼리 설명하기 (Explaining a match query)

다음 예시는 products 인덱스의 문서 1이 name 필드에서 "computer"라는 용어에 대해 쿼리와 일치하는 이유를 설명해요:

POST /products/_explain/1
{
"query": {
"match": {
"name": "computer"
}
}
}

Python 클라이언트로는 이렇게 호출해요:

response = client.explain(
id = "1",
index = "products",
body =   {
"query": {
"match": {
"name": "computer"
}
}
}
)

예시 응답 (Example response)

Explain API는 문서가 쿼리와 일치하는지 여부와 점수 계산의 상세한 분석을 포함한 응답을 반환해요. 설명에는 BM25 점수 공식 구성 요소인 term frequency(tf), inverse document frequency(idf), 필드 길이 정규화가 포함돼요:

{
"_index": "products",
"_id": "1",
"matched": true,
"explanation": {
"value": 0.31506687,
"description": "weight(name:computer in 0) [PerFieldSimilarity], result of:",
"details": [
{
"value": 0.31506687,
"description": "score(freq=1.0), computed as boost * idf * tf from:",
"details": [
{
"value": 0.6931472,
"description": "idf, computed as log(1 + (N - n + 0.5) / (n + 0.5)) from:",
"details": [
{
"value": 2,
"description": "n, number of documents containing term",
"details": []
},
{
"value": 4,
"description": "N, total number of documents with field",
"details": []
}
]
},
{
"value": 0.45454544,
"description": "tf, computed as freq / (freq + k1 * (1 - b + b * dl / avgdl)) from:",
"details": [
{
"value": 1.0,
"description": "freq, occurrences of term within document",
"details": []
},
{
"value": 1.2,
"description": "k1, term saturation parameter",
"details": []
},
{
"value": 0.75,
"description": "b, length normalization parameter",
"details": []
},
{
"value": 2.0,
"description": "dl, length of field",
"details": []
},
{
"value": 2.0,
"description": "avgdl, average length of field",
"details": []
}
]
}
]
}
]
}
}

예시: 쿼리 문자열 매개변수 사용하기 (Using the query string parameter)

요청 본문을 제공하는 대신 q 매개변수로 Lucene 쿼리 문자열 구문을 사용해 쿼리를 지정할 수 있어요. 다음 예시는 문서 1이 "name:laptop" 쿼리 문자열과 일치하는 이유를 설명해요:

GET /products/_explain/1?q=name:laptop

Python 클라이언트로는 이렇게 호출해요:

response = client.explain(
id = "1",
index = "products",
params = { "q": "name:laptop" },
body = { "Insert body here" }
)

응답 본문 필드 (Response body fields)

응답은 문서가 쿼리와 일치하는지 여부와 관련성 점수가 계산된 방법에 대한 상세 정보를 담고 있어요. 다음 표는 응답 본문 필드예요.

BM25 점수 구성 요소 (BM25 scoring components)

설명 세부 내용에는 다음 BM25 점수 구성 요소가 포함돼요.

최종 관련성 점수는 이 구성 요소들을 곱해 계산돼요: score = boost * idf * tf. 값은 문서를 추가하거나 업데이트할 때 색인 시간에 계산·저장되며, 샤드 수준 통계에 따라 작은 부정확성이 있을 수 있어요.

필요한 권한 (Required permissions)

Security 플러그인을 사용한다면 적절한 권한이 있는지 확인해야 해요: indices:data/read/explain.

더 알아보기

• Search API
• Search