Template 쿼리
Template 쿼리
자리표시자(placeholder) 변수를 포함한 검색 쿼리를 만들려면 template 쿼리를 사용해요. 자리표시자는 "${variable_name}" 문법으로 지정하며, 검색 요청 프로세서가 처리할 때까지 해석되지 않은 채 남아 있어요.
출처: 문서
본문
2.19 버전에서 도입되었어요. 플레이스홀더 변수가 포함된 검색 쿼리를 만들려면 template 쿼리를 사용해요. 플레이스홀더는 "${variable_name}" 문법으로 지정해요(변수는 반드시 따옴표로 감싸야 해요). 검색 요청을 제출하면 이 플레이스홀더는 검색 요청 프로세서(search request processor)가 처리할 때까지 해석되지 않은 채 남아 있어요. 이 방식은 초기 검색 요청에 런타임에 변환되거나 생성되어야 하는 데이터가 포함될 때 특히 유용해요. 예를 들어 검색 과정에서 텍스트 입력을 벡터 임베딩으로 변환하는 ml_inference 검색 요청 프로세서를 사용할 때 template 쿼리를 쓰게 돼요. 프로세서는 최종 쿼리가 실행되기 전에 플레이스홀더를 생성된 값으로 대체해요. 전체 예제는 Query rewriting using template queries를 참고하세요. This page documents the template query, which uses placeholder variables resolved by search request processors (such as ML inference) at runtime. If you want to create reusable, parameterized queries using Mustache syntax (``), see Search Template API.
예제 (Example)
다음 예제는 "vector": "${text_embedding}" 플레이스홀더를 가진 template k-NN 쿼리를 보여줘요. "${text_embedding}" 플레이스홀더는 ml_inference 검색 요청 프로세서가 text 입력 필드에서 생성한 임베딩으로 대체돼요:
GET /template-knn-index/_search?search_pipeline=my_knn_pipeline
{
"query": {
"template": {
"knn": {
"text_embedding": {
"vector": "${text_embedding}", // Placeholder for the vector field
"k": 2
}
}
}
},
"ext": {
"ml_inference": {
"text": "sneakers" // Input text for the ml_inference processor
}
}
}
template 쿼리를 검색 요청 프로세서와 함께 사용하려면 검색 파이프라인(search pipeline)을 구성해야 해요. 다음은 ml_inference 검색 요청 프로세서의 예제 구성이에요. input_map은 문서 필드를 모델 입력에 매핑해요. 이 예제에서는 문서의 ext.ml_inference.text 소스 필드가 모델의 예상 입력 필드인 inputText 필드에 매핑돼요. output_map은 모델 출력을 문서 필드에 매핑해요. 이 예제에서는 모델의 embedding 출력 필드가 문서의 text_embedding 대상 필드에 매핑돼요:
PUT /_search/pipeline/my_knn_pipeline
{
"request_processors": [
{
"ml_inference": {
"model_id": "Sz-wFZQBUpPSu0bsJTBG",
"input_map": [
{
"inputText": "ext.ml_inference.text" // Map input text from the request
}
],
"output_map": [
{
"text_embedding": "embedding" // Map output to the placeholder
}
]
}
}
]
}
ml_inference 검색 요청 프로세서가 실행된 후 검색 요청은 다시 작성(rewrite)돼요. vector 필드에는 프로세서가 생성한 임베딩이 들어가고, text_embedding 필드에는 프로세서 출력이 들어가요:
GET /template-knn-1/_search
{
"query": {
"template": {
"knn": {
"text_embedding": {
"vector": [0.6328125, 0.26953125, ...],
"k": 2
}
}
}
},
"ext": {
"ml_inference": {
"text": "sneakers",
"text_embedding": [0.6328125, 0.26953125, ...]
}
}
}
제한 사항 (Limitations)
template 쿼리는 플레이스홀더를 해석하려면 검색 요청 프로세서가 최소 하나 이상 필요해요. 검색 요청 프로세서는 파이프라인에서 기대하는 변수를 생성하도록 구성되어야 해요.
다음 단계 (Next steps)
- 전체 예제는 Template queries를 참고하세요.