Search API
Search API (gRPC)
3.0에서 도입되었어요. 이 기능은 실험적이며 프로덕션 환경에서의 사용은 권장되지 않아요. 기능 진행 상황이나 피드백은 관련 GitHub 이슈를 참고하세요.
gRPC Search API는 gRPC 위의 프로토콜 버퍼를 사용해 쿼리를 실행하는 고성능 이진 인터페이스를 제공해요. HTTP Search API의 기능을 그대로 따르면서 protobuf 타입 계약과 gRPC 전송의 이점을 얻어요. gRPC API는 저지연·고처리량 애플리케이션에 이상적이에요.
출처: 문서
본문
사전 요구 사항 (Prerequisite)
gRPC 요청을 제출하려면 클라이언트 쪽에 protobuf 세트가 있어야 해요. protobuf를 얻는 방법은 Using gRPC APIs를 참고하세요.
gRPC 서비스와 메서드 (gRPC service and method)
gRPC Document API는 SearchService에 있어요.
SearchService 안의 Search gRPC 메서드를 호출해서 검색 요청을 제출할 수 있어요. 이 메서드는 SearchRequest를 받아 SearchResponse를 반환해요.
현재 지원되는 검색 쿼리는 Supported Queries를 참고하세요. 추가 쿼리 유형은 이후 버전에서 지원될 예정이에요.
요청 필드 (Request fields)
gRPC Search API는 다음 요청 필드를 지원해요.
SearchRequest 필드 (SearchRequest fields)
SearchRequest 메시지는 다음 필드를 받아요. 모든 필드는 선택 사항이에요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| index | repeated string | 검색할 인덱스 목록이에요. 제공하지 않으면 모든 인덱스가 기본값이 돼요. |
| x_source | SourceConfigParam | 응답에서 전체 _source, _source 없음, 또는 _source의 특정 필드만 반환할지 제어해요. |
| x_source_excludes | repeated string | _source에서 제외할 필드예요. source가 false이면 무시돼요. |
| x_source_includes | repeated string | _source에서 포함할 필드예요. source가 false이면 무시돼요. |
| allow_no_indices | bool | 어떤 인덱스와도 일치하지 않는 와일드카드를 무시할지 여부예요. 기본값은 true예요. |
| allow_partial_search_results | bool | 오류나 제한 시간 시 부분 결과를 반환할지 여부예요. 기본값은 true예요. |
| analyze_wildcard | bool | 와일드카드/접두사 쿼리를 분석할지 여부예요. 기본값은 false예요. |
| batched_reduce_size | int32 | 한 노드에서 리듀스할 샤드 수예요. 기본값은 512예요. |
| cancel_after_time_interval | string | 요청이 취소될 시간이에요. 기본값은 -1이에요. |
| ccs_minimize_roundtrips | bool | 노드와 원격 클러스터 사이의 왕복을 최소화할지 여부예요. 기본값은 true예요. |
| default_operator | Operator | 쿼리 문자열의 기본 연산자예요. 유효한 값은 AND 또는 OR이에요. 기본값은 OR이에요. |
| df | string | 필드 접두사가 없는 쿼리 문자열의 기본 필드예요. |
| docvalue_fields | repeated string | doc value로 반환할 필드예요. |
| expand_wildcards | repeated ExpandWildcard | 와일드카드 표현이 일치할 수 있는 인덱스 유형이에요. 유효한 값은 all(모든 인덱스 일치), open(열린, 숨겨지지 않은 인덱스 일치), closed(닫힌, 숨겨지지 않은 인덱스 일치), hidden(숨겨진 인덱스 일치), none(와일드카드 표현 거부)이에요. 기본값은 open이에요. |
| ignore_throttled | bool | 별칭을 해석할 때 프로즌 인덱스를 무시할지 여부예요. 기본값은 true예요. |
| ignore_unavailable | bool | 사용할 수 없는 인덱스나 샤드를 무시할지 여부예요. 기본값은 false예요. |
| max_concurrent_shard_requests | int32 | 노드당 동시 샤드 요청 수예요. 기본값은 5예요. |
| phase_took | bool | 단계별(phase-level) took 값을 반환할지 여부예요. 기본값은 false예요. |
| pre_filter_shard_size | int32 | 샤드 크기로 사전 필터링을 트리거하는 임계값이에요. 기본값은 128예요. |
| preference | string | 쿼리 실행을 위한 샤드 또는 노드 선호도예요. |
| q | string | Lucene 문법의 쿼리 문자열이에요. |
| request_cache | bool | 요청 캐시를 사용할지 여부예요. 기본값은 인덱스의 설정이에요. |
| total_hits_as_int | bool | 전체 hits 수를 정수로 반환할지 여부예요. 기본값은 false예요. |
| routing | repeated string | 요청을 특정 샤드로 보내는 데 사용하는 라우팅 값이에요. |
| scroll | string | 스크롤링을 위해 검색 컨텍스트를 유지하는 시간이에요. |
| search_type | SearchType | 관련성 점수를 계산하는 방법이에요. 유효한 값은 QUERY_THEN_FETCH와 DFS_QUERY_THEN_FETCH예요. 기본값은 QUERY_THEN_FETCH예요. |
| suggest_field | string | 제안(제)을 기반으로 하는 필드예요. |
| suggest_mode | SuggestMode | 제안 모드예요(예: always, missing, popular). |
| suggest_size | int32 | 반환할 제안 수예요. |
| suggest_text | string | 제안을 생성하기 위한 입력 텍스트예요. |
| typed_keys | bool | 집계와 제안 키에 타입 정보를 포함할지 여부예요. 기본값은 true예요. |
| search_request_body | SearchRequestBody | 쿼리와 필터를 포함한 메인 검색 요청 페이로드예요. |
| global_params | GlobalParams | 요청의 전역 파라미터예요. 선택 사항이에요. |
SearchRequestBody 필드 (SearchRequestBody fields)
SearchRequestBody 메시지는 다음 필드를 받아요. 모든 필드는 선택 사항이에요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| collapse | FieldCollapse | 필드로 결과를 그룹화해요. 그룹당 최상위 문서만 반환해요. |
| explain | bool | 일치한 문서에 대한 점수 설명을 반환해요. |
| ext | ObjectMap | RAG 같은 확장을 위한 plugin별 메타데이터예요. |
| from | int32 | 페이지네이션 결과의 시작 인덱스예요. 기본값은 0이에요. |
| highlight | Highlight | 결과 스니펫에서 일치한 용어를 하이라이트해요. |
| track_total_hits | TrackHits | 전체 hit 수를 반환할지 여부예요. |
| indices_boost | map<string, float> | 더 이상 사용되지 않아요(deprecated). indices_boost_2를 사용하세요. |
| docvalue_fields | repeated FieldAndFormat | doc_values 형태로 반환할 필드예요. 반환 값에 형식을 포함할 수 있어요(예: 날짜 형식). knn_vector 필드의 경우 지원되는 형식은 binary(기본값, Base64 인코딩)와 array(JSON 숫자 배열)예요. 자세한 내용은 docvalue_fields로 벡터 필드 검색을 참고하세요. |
| min_score | float | 결과에 문서가 포함되기 위해 필요한 최소 점수예요. |
| post_filter | QueryContainer | 집계가 적용된 후 hits를 필터링해요. |
| profile | bool | 쿼리 성능을 분석하는 프로파일링을 활성화해요. |
| search_pipeline | string | 적용할 검색 파이프라인의 이름이에요. |
| verbose_pipeline | bool | 검색 파이프라인에서 상세 로깅을 활성화해요. |
| query | QueryContainer | 검색을 위한 쿼리 도메인 특화 언어(DSL)예요. |
| rescore | repeated Rescore | 정밀도를 높이기 위해 상위 N개 hits를 다시 점수 매겨요. |
| script_fields | map<string, ScriptField> | 값이 스크립트로 계산되는 사용자 지정 필드예요. |
| search_after | repeated FieldValue | 이전 페이지의 값을 사용하는 커서 기반 페이지네이션이에요. |
| size | int32 | 반환할 결과 수예요. 기본값은 10이에요. |
| slice | SlicedScroll | 병렬 처리를 위해 스크롤 컨텍스트를 슬라이스로 나눠요. |
| sort | repeated SortCombinations | 정렬 규칙이에요(예: 필드, 점수, 사용자 지정 순서). |
| x_source | SourceConfig | 응답에서 전체 _source, _source 없음, 또는 _source의 특정 필드만 반환할지 제어해요. |
| fields | repeated FieldAndFormat | 형식 옵션과 함께 반환할 추가 필드예요. |
| terminate_after | int32 | 조기 종료 전 처리할 최대 일치 문서(hits) 수예요. 기본값은 0이에요. |
| timeout | string | 쿼리 실행을 기다리는 최대 시간이에요. |
| track_scores | bool | 결과에 문서 점수를 반환할지 여부예요. |
| include_named_queries_score | bool | 이름 붙은 쿼리의 점수를 포함할지 여부예요. |
| version | bool | 응답에 문서 버전을 포함할지 여부예요. |
| seq_no_primary_term | bool | 각 hit에 시퀀스 번호와 프라이머리 텀을 포함할지 여부예요. |
| stored_fields | repeated string | 반환할 저장된 필드예요(다시 활성화하지 않으면 _source 제외). |
| pit | PointInTimeReference | 고정 스냅샷을 검색하는 데 사용하는 Point in Time 참조예요. |
| stats | repeated string | 요청과 연결할 태깅 또는 로깅 필드예요. |
| derived | map<string, DerivedField> | 응답에 반환되는 동적으로 계산된 필드예요. |
| indices_boost_2 | repeated FloatMap | 인덱스별 부스트 배율의 현재 protobuf 표현이에요. 각 항목은 인덱스-부스트 매핑을 포함해요. |
| aggregations | map<string, AggregationContainer> | 검색 요청의 일부로 계산할 집계예요. |
DerivedField 필드 (DerivedField fields)
DerivedField 메시지는 검색 실행 중에 계산되는 동적 필드에 사용돼요. 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| name | string | 파생 필드의 이름이에요. 필수예요. |
| type | string | 파생 필드의 데이터 타입이에요. 필수예요. |
| script | Script | 필드 값을 계산하는 스크립트예요. 필수예요. |
| prefilter_field | string | 스크립트 실행을 최적화하기 위한 사전 필터링에 사용할 필드예요. 선택 사항이에요. |
| properties | ObjectMap | 파생 필드의 추가 속성이에요. 선택 사항이에요. |
| ignore_malformed | bool | 필드 계산 중 잘못된 형식의 값을 무시할지 여부예요. 선택 사항이에요. |
| format | string | 필드 값에 적용할 형식이에요(예: 날짜 형식). 선택 사항이에요. |
QueryContainer 필드 (QueryContainer fields)
QueryContainer는 모든 지원 쿼리 유형의 진입점이에요.
각 QueryContainer 메시지에서 다음 필드 중 정확히 하나를 제공해야 해요.
일부 쿼리 유형은 현재 지원되지 않는다는 점에 유의하세요. 구현된 쿼리 유형의 현재 목록은 Supported queries를 참고하세요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| bool | BoolQuery | AND, OR, NOT 로직으로 여러 절을 결합하는 Boolean 쿼리예요. 유일하게 설정해야 하는 필드예요. |
| constant_score | ConstantScoreQuery | 필터를 감싸고 모든 일치 문서에 일정한 관련성 점수를 할당해요. 유일하게 설정해야 하는 필드예요. |
| function_score | FunctionScoreQuery | 사용자 지정 함수로 결과의 점수를 조정해요. 유일하게 설정해야 하는 필드예요. |
| exists | ExistsQuery | 특정 필드를 포함하는 문서와 일치해요. 유일하게 설정해야 하는 필드예요. |
| fuzzy | FuzzyQuery | 검색 용어와 유사한 용어와 일치해요(퍼지 매칭). 유일하게 설정해야 하는 필드예요. |
| ids | IdsQuery | _id 값으로 문서와 일치해요. 유일하게 설정해야 하는 필드예요. |
| prefix | PrefixQuery | 특정 접두사를 가진 용어와 일치해요. 유일하게 설정해야 하는 필드예요. |
| range | RangeQuery | 지정된 범위 내의 용어와 일치해요. 유일하게 설정해야 하는 필드예요. |
| regexp | RegexpQuery | 정규 표현식으로 용어와 일치해요. 유일하게 설정해야 하는 필드예요. |
| term | TermQuery | 정확한 용어와 일치해요(분석 없음). 유일하게 설정해야 하는 필드예요. |
| terms | TermsQuery | 필드에서 지정된 용어를 하나 이상 포함하는 문서와 일치해요. 유일하게 설정해야 하는 필드예요. |
| terms_set | TermsSetQuery | 필드에서 최소한의 정확한 용어 수를 포함하는 문서와 일치해요. 유일하게 설정해야 하는 필드예요. |
| wildcard | WildcardQuery | 와일드카드 패턴으로 용어와 일치해요. 유일하게 설정해야 하는 필드예요. |
| match | MatchQuery | 텍스트 또는 정확한 값 필드에 대한 전체 텍스트 일치를 수행해요. 유일하게 설정해야 하는 필드예요. |
| match_bool_prefix | MatchBoolPrefixQuery | Boolean 스타일 쿼리에서 전체 단어와 접두사와 일치해요. 유일하게 설정해야 하는 필드예요. |
| match_phrase | MatchPhraseQuery | 순서대로 정확한 구문과 일치해요. 유일하게 설정해야 하는 필드예요. |
| match_phrase_prefix | MatchPhrasePrefixQuery | 마지막 용어를 접두사로 취급하는 구문과 일치해요. 유일하게 설정해야 하는 필드예요. |
| multi_match | MultiMatchQuery | 단일 쿼리 문자열로 여러 필드를 검색해요. 유일하게 설정해야 하는 필드예요. |
| knn | KnnQuery | 벡터 필드에 대한 k-NN 쿼리예요. 유일하게 설정해야 하는 필드예요. |
| match_all | MatchAllQuery | 인덱스의 모든 문서와 일치해요. 유일하게 설정해야 하는 필드예요. |
| match_none | MatchNoneQuery | 어떤 문서와도 일치하지 않아요. 유일하게 설정해야 하는 필드예요. |
| nested | NestedQuery | 중첩 필드를 대상으로 하는 쿼리를 감싸요. 유일하게 설정해야 하는 필드예요. |
| geo_distance | GeoDistanceQuery | 제공된 지오포인트에서 지정된 거리 내에 있는 지오포인트를 포함하는 문서를 반환해요. 유일하게 설정해야 하는 필드예요. |
| geo_bounding_box | GeoBoundingBoxQuery | 지정된 경계 상자 안에 있는 지오포인트를 포함하는 문서를 반환해요. 유일하게 설정해야 하는 필드예요. |
| script | ScriptQuery | Painless 스크립팅 언어로 작성된 사용자 지정 조건으로 문서를 필터링해요. 유일하게 설정해야 하는 필드예요. |
| hybrid | HybridQuery | 여러 쿼리의 관련성 점수를 하나의 점수로 결합해요. 유일하게 설정해야 하는 필드예요. |
지원되는 쿼리 (Supported queries)
gRPC Search API는 다음 쿼리 유형을 지원해요.
- 용어 수준(term-level): exists, fuzzy, ids, prefix, range, regexp, term, terms, terms_set, wildcard
- 전체 텍스트(full-text): match, match_bool_prefix, match_phrase, match_phrase_prefix, multi_match
- 전체 일치(match all): match_all, match_none
- 복합 쿼리(compound): bool, constant_score, function_score, hybrid
- 지리(geographic): geo_bounding_box, geo_distance
- 조인 쿼리(joining): nested
- 특수 쿼리(specialized): knn, script
이 쿼리 유형에 대한 자세한 내용은 Query DSL을 참고하세요.
용어 수준 쿼리 필드 (Term-level query fields)
다음 섹션은 각 용어 수준 쿼리 메시지의 필드를 설명해요.
ExistsQuery 필드 (ExistsQuery fields)
ExistsQuery 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| field | string | 필수. 검색할 필드의 이름이에요. |
| boost | optional float | 쿼리의 관련성 점수를 낮추거나 높이는 데 사용하는 부동소수점 숫자예요. 기본값은 1.0이에요. |
| x_name | optional string | 쿼리 태깅용 쿼리 이름이에요. |
FuzzyQuery 필드 (FuzzyQuery fields)
FuzzyQuery 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| field | string | 필수. 검색 쿼리를 실행할 필드예요. |
| value | FieldValue | 필수. 지정된 필드에서 검색할 용어예요. |
| boost | optional float | 쿼리의 관련성 점수를 낮추거나 높이는 데 사용하는 부동소수점 숫자예요. 기본값은 1.0이에요. |
| x_name | optional string | 쿼리 태깅용 쿼리 이름이에요. |
| max_expansions | optional int32 | 쿼리가 확장될 수 있는 최대 용어 수예요. 기본값은 50이에요. |
| prefix_length | optional int32 | 퍼지 일치에서 고려하지 않는 선행 문자 수예요. 기본값은 0이에요. |
| rewrite_deprecated | optional MultiTermQueryRewrite | 더 이상 사용되지 않아요(deprecated). rewrite를 사용하세요. |
| transpositions | optional bool | 인접한 두 문자의 전위(transposition)를 편집으로 허용할지 여부예요. 기본값은 true예요. |
| fuzziness | optional Fuzziness | 용어가 값과 일치하는지 판단할 때 한 단어를 다른 단어로 바꾸는 데 필요한 문자 편집(삽입, 삭제, 대체) 수예요. |
| rewrite | optional string | OpenSearch가 쿼리를 다시 작성하는 방법을 결정해요. Rewrite parameter values를 참고하세요. 기본값은 constant_score예요. |
IdsQuery 필드 (IdsQuery fields)
IdsQuery 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| boost | optional float | 쿼리의 관련성 점수를 낮추거나 높이는 데 사용하는 부동소수점 숫자예요. 기본값은 1.0이에요. |
| x_name | optional string | 쿼리 태깅용 쿼리 이름이에요. |
| values | repeated string | 검색할 문서 ID예요. |
PrefixQuery 필드 (PrefixQuery fields)
PrefixQuery 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| field | string | 필수. 검색 쿼리를 실행할 필드예요. |
| value | string | 필수. 지정된 필드에서 검색할 용어예요. |
| boost | optional float | 쿼리의 관련성 점수를 낮추거나 높이는 데 사용하는 부동소수점 숫자예요. 기본값은 1.0이에요. |
| x_name | optional string | 쿼리 태깅용 쿼리 이름이에요. |
| rewrite_deprecated | optional MultiTermQueryRewrite | 더 이상 사용되지 않아요(deprecated). rewrite를 사용하세요. |
| case_insensitive | optional bool | ASCII 대소문자 구분 없는 일치를 허용해요. 기본값은 false예요. |
| rewrite | optional string | OpenSearch가 쿼리를 다시 작성하는 방법을 결정해요. Rewrite parameter values를 참고하세요. 기본값은 constant_score예요. |
RangeQuery 필드 (RangeQuery fields)
RangeQuery 메시지는 NumberRangeQuery 또는 DateRangeQuery를 포함할 수 있는 oneof 타입이에요.
NumberRangeQuery 필드 (NumberRangeQuery fields)
NumberRangeQuery 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| field | string | 필수. 검색 쿼리를 실행할 필드예요. |
| boost | optional float | 쿼리의 관련성 점수를 낮추거나 높이는 데 사용하는 부동소수점 숫자예요. 기본값은 1.0이에요. |
| x_name | optional string | 쿼리 태깅용 쿼리 이름이에요. |
| relation | optional RangeRelation | 범위 필드에 대해 range 쿼리가 값을 일치시키는 방법을 나타내요. |
| gt | optional double | 초과(greater than)예요. |
| gte | optional double | 이상(greater than or equal to)이에요. |
| lt | optional double | 미만(less than)이에요. |
| lte | optional double | 이하(less than or equal to)예요. |
| from | optional NumberRangeQueryAllOfFrom | 범위의 시작 값이에요. |
| to | optional NumberRangeQueryAllOfTo | 범위의 끝 값이에요. |
| include_lower | optional bool | 하한을 포함할지 여부예요. |
| include_upper | optional bool | 상한을 포함할지 여부예요. |
DateRangeQuery 필드 (DateRangeQuery fields)
DateRangeQuery 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| field | string | 필수. 검색 쿼리를 실행할 필드예요. |
| boost | optional float | 쿼리의 관련성 점수를 낮추거나 높이는 데 사용하는 부동소수점 숫자예요. 기본값은 1.0이에요. |
| x_name | optional string | 쿼리 태깅용 쿼리 이름이에요. |
| relation | optional RangeRelation | 범위 필드에 대해 range 쿼리가 값을 일치시키는 방법을 나타내요. |
| gt | optional string | 초과(greater than)예요. |
| gte | optional string | 이상(greater than or equal to)이에요. |
| lt | optional string | 미만(less than)이에요. |
| lte | optional string | 이하(less than or equal to)예요. |
| from | optional DateRangeQueryAllOfFrom | 범위의 시작 값이에요. |
| to | optional DateRangeQueryAllOfTo | 범위의 끝 값이에요. |
| format | optional string | 날짜 형식 패턴이에요. |
| time_zone | optional string | 시간대 식별자예요. |
| include_lower | optional bool | 하한을 포함할지 여부예요. |
| include_upper | optional bool | 상한을 포함할지 여부예요. |
RegexpQuery 필드 (RegexpQuery fields)
RegexpQuery 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| field | string | 필수. 검색 쿼리를 실행할 필드예요. |
| value | string | 필수. 제공된 필드에서 검색할 용어를 위한 정규 표현식이에요. |
| boost | optional float | 쿼리의 관련성 점수를 낮추거나 높이는 데 사용하는 부동소수점 숫자예요. 기본값은 1.0이에요. |
| x_name | optional string | 쿼리 태깅용 쿼리 이름이에요. |
| case_insensitive | optional bool | 정규 표현식의 대소문자 구분 없는 일치를 허용해요. 기본값은 false예요. |
| flags | optional string | 정규 표현식에 선택 연산자를 활성화해요. |
| max_determinized_states | optional int32 | 쿼리가 필요한 최대 오토마타 상태 수예요. 기본값은 10000이에요. |
| rewrite_deprecated | optional MultiTermQueryRewrite | 더 이상 사용되지 않아요(deprecated). rewrite를 사용하세요. |
| rewrite | optional string | OpenSearch가 다중 용어 쿼리를 다시 작성하고 점수를 매기는 방법을 결정해요. Rewrite parameter values를 참고하세요. 기본값은 constant_score예요. |
TermQuery 필드 (TermQuery fields)
TermQuery 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| field | string | 필수. 검색 쿼리를 실행할 필드예요. |
| boost | optional float | 쿼리의 관련성 점수를 낮추거나 높이는 데 사용하는 부동소수점 숫자예요. 기본값은 1.0이에요. |
| x_name | optional string | 쿼리 태깅용 쿼리 이름이에요. |
| value | FieldValue | 필수. 제공된 필드에서 검색할 용어예요. 필드 값과 정확히 일치해야 해요. |
| case_insensitive | optional bool | ASCII 대소문자 구분 없는 일치를 허용해요. 기본값은 false예요. |
TermsQuery 필드 (TermsQuery fields)
TermsQuery 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| boost | optional float | 쿼리의 관련성 점수를 낮추거나 높이는 데 사용하는 부동소수점 숫자예요. 기본값은 1.0이에요. |
| x_name | optional string | 쿼리 태깅용 쿼리 이름이에요. |
| value_type | optional TermsQueryValueType | 필터링에 사용되는 값의 유형이에요. 유효한 값은 default와 bitmap이에요. 기본값은 default예요. |
| terms | map<string, TermsQueryField> | 필드 이름에서 용어 값 또는 용어 조회(terms lookup)로의 맵이에요. |
TermsSetQuery 필드 (TermsSetQuery fields)
TermsSetQuery 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| field | string | 필수. 검색 쿼리를 실행할 필드예요. |
| terms | repeated string | 필수. 지정된 필드에서 검색할 용어 배열이에요. |
| boost | optional float | 쿼리의 관련성 점수를 낮추거나 높이는 데 사용하는 부동소수점 숫자예요. 기본값은 1.0이에요. |
| x_name | optional string | 쿼리 태깅용 쿼리 이름이에요. |
| minimum_should_match_field | optional string | 필요한 일치 용어 수를 지정하는 숫자 필드의 이름이에요. |
| minimum_should_match_script | optional Script | 필요한 일치 용어 수를 반환하는 스크립트예요. |
WildcardQuery 필드 (WildcardQuery fields)
WildcardQuery 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| field | string | 필수. 검색 쿼리를 실행할 필드예요. |
| boost | optional float | 쿼리의 관련성 점수를 낮추거나 높이는 데 사용하는 부동소수점 숫자예요. 기본값은 1.0이에요. |
| x_name | optional string | 쿼리 태깅용 쿼리 이름이에요. |
| case_insensitive | optional bool | 대소문자 구분 없는 일치를 허용해요. 기본값은 false예요. |
| rewrite_deprecated | optional MultiTermQueryRewrite | 더 이상 사용되지 않아요(deprecated). rewrite를 사용하세요. |
| value | optional string | 지정된 필드의 용어를 일치시키는 데 사용하는 와일드카드 패턴이에요. wildcard가 설정되지 않았을 때 필수예요. |
| wildcard | optional string | 지정된 필드의 용어를 일치시키는 데 사용하는 와일드카드 패턴이에요. value가 설정되지 않았을 때 필수예요. |
| rewrite | optional string | OpenSearch가 쿼리를 다시 작성하는 방법을 결정해요. Rewrite parameter values를 참고하세요. 기본값은 constant_score예요. |
전체 텍스트 쿼리 필드 (Full-text query fields)
다음 섹션은 각 전체 텍스트 쿼리 메시지의 필드를 설명해요.
MatchQuery 필드 (MatchQuery fields)
MatchQuery 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| field | string | 필수. 검색 쿼리를 실행할 필드예요. |
| query | FieldValue | 필수. 검색에 사용할 쿼리 문자열이에요. |
| boost | optional float | 쿼리의 관련성 점수를 낮추거나 높이는 데 사용하는 부동소수점 숫자예요. 기본값은 1.0이에요. |
| x_name | optional string | 쿼리 태깅용 쿼리 이름이에요. |
| analyzer | optional string | 쿼리 문자열 텍스트를 토큰화하는 데 사용하는 분석기예요. |
| auto_generate_synonyms_phrase_query | optional bool | 다중 용어 동의어에 대해 match phrase 쿼리를 자동으로 만들지 여부예요. |
| fuzziness | optional Fuzziness | 용어가 값과 일치하는지 판단할 때 한 단어를 다른 단어로 바꾸는 데 필요한 문자 편집(삽입, 삭제, 대체, 전위) 수예요. |
| fuzzy_rewrite_deprecated | optional MultiTermQueryRewrite | 더 이상 사용되지 않아요(deprecated). fuzzy_rewrite를 사용하세요. |
| fuzzy_transpositions | optional bool | 퍼지 작업에 인접 문자 스왑을 추가해요. 기본값은 true예요. |
| lenient | optional bool | 쿼리와 문서 필드 사이의 데이터 타입 불일치를 무시해요. 기본값은 false예요. |
| max_expansions | optional int32 | 쿼리가 확장될 수 있는 최대 용어 수예요. 기본값은 50이에요. |
| minimum_should_match | optional MinimumShouldMatch | 문서가 일치로 간주되기 위해 일치해야 하는 용어 수예요. |
| operator | optional Operator | 모든 용어가 일치해야 하는지(AND) 하나의 용어만 일치해도 되는지(OR)예요. 기본값은 OR이에요. |
| prefix_length | optional int32 | 퍼지 일치에서 고려하지 않는 선행 문자 수예요. 기본값은 0이에요. |
| zero_terms_query | optional ZeroTermsQuery | 분석기가 모든 용어를 제거할 때 어떤 문서도 일치하지 않게 할지(none) 모든 문서와 일치하게 할지(all) 지정해요. 기본값은 none이에요. |
| fuzzy_rewrite | optional string | OpenSearch가 쿼리를 다시 작성하는 방법을 결정해요. Rewrite parameter values를 참고하세요. 기본값은 constant_score예요. |
MatchBoolPrefixQuery 필드 (MatchBoolPrefixQuery fields)
MatchBoolPrefixQuery 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| field | string | 필수. 검색 쿼리를 실행할 필드예요. |
| query | string | 필수. 제공된 필드에서 검색할 용어예요. 마지막 용어는 접두사 쿼리로 사용돼요. |
| boost | optional float | 쿼리의 관련성 점수를 낮추거나 높이는 데 사용하는 부동소수점 숫자예요. 기본값은 1.0이에요. |
| x_name | optional string | 쿼리 태깅용 쿼리 이름이에요. |
| analyzer | optional string | 쿼리 문자열 텍스트를 토큰화하는 데 사용하는 분석기예요. |
| fuzziness | optional Fuzziness | 용어가 값과 일치하는지 판단할 때 한 단어를 다른 단어로 바꾸는 데 필요한 문자 편집(삽입, 삭제, 대체, 전위) 수예요. |
| fuzzy_rewrite_deprecated | optional MultiTermQueryRewrite | 더 이상 사용되지 않아요(deprecated). fuzzy_rewrite를 사용하세요. |
| fuzzy_transpositions | optional bool | 퍼지 작업에 인접 문자 스왑을 추가해요. 기본값은 true예요. |
| max_expansions | optional int32 | 쿼리가 확장될 수 있는 최대 용어 수예요. 기본값은 50이에요. |
| minimum_should_match | optional MinimumShouldMatch | 문서가 일치로 간주되기 위해 일치해야 하는 용어 수예요. |
| operator | optional Operator | 모든 용어가 일치해야 하는지(AND) 하나의 용어만 일치해도 되는지(OR)예요. 기본값은 OR이에요. |
| prefix_length | optional int32 | 퍼지 일치에서 고려하지 않는 선행 문자 수예요. 기본값은 0이에요. |
| fuzzy_rewrite | optional string | OpenSearch가 쿼리를 다시 작성하는 방법을 결정해요. Rewrite parameter values를 참고하세요. 기본값은 constant_score예요. |
MatchPhraseQuery 필드 (MatchPhraseQuery fields)
MatchPhraseQuery 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| field | string | 필수. 검색 쿼리를 실행할 필드예요. |
| query | string | 필수. 검색에 사용할 쿼리 문자열이에요. |
| boost | optional float | 쿼리의 관련성 점수를 낮추거나 높이는 데 사용하는 부동소수점 숫자예요. 기본값은 1.0이에요. |
| x_name | optional string | 쿼리 태깅용 쿼리 이름이에요. |
| analyzer | optional string | 쿼리 문자열 텍스트를 토큰화하는 데 사용하는 분석기예요. |
| slop | optional int32 | 쿼리 구문의 단어 사이에 허용되는 다른 단어 수예요. 기본값은 0(정확히 일치)이에요. |
| zero_terms_query | optional ZeroTermsQuery | 분석기가 모든 용어를 제거할 때 어떤 문서도 일치하지 않게 할지(none) 모든 문서와 일치하게 할지(all) 지정해요. 기본값은 none이에요. |
MatchPhrasePrefixQuery 필드 (MatchPhrasePrefixQuery fields)
MatchPhrasePrefixQuery 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| field | string | 필수. 검색 쿼리를 실행할 필드예요. |
| query | string | 필수. 검색에 사용할 쿼리 문자열이에요. |
| boost | optional float | 쿼리의 관련성 점수를 낮추거나 높이는 데 사용하는 부동소수점 숫자예요. 기본값은 1.0이에요. |
| x_name | optional string | 쿼리 태깅용 쿼리 이름이에요. |
| analyzer | optional string | 쿼리 문자열 텍스트를 토큰화하는 데 사용하는 분석기예요. |
| max_expansions | optional int32 | 쿼리가 확장될 수 있는 최대 용어 수예요. 기본값은 50이에요. |
| slop | optional int32 | 쿼리 구문의 단어 사이에 허용되는 다른 단어 수예요. 기본값은 0(정확히 일치)이에요. |
| zero_terms_query | optional ZeroTermsQuery | 분석기가 모든 용어를 제거할 때 어떤 문서도 일치하지 않게 할지(none) 모든 문서와 일치하게 할지(all) 지정해요. 기본값은 none이에요. |
MultiMatchQuery 필드 (MultiMatchQuery fields)
MultiMatchQuery 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| query | string | 필수. 검색에 사용할 쿼리 문자열이에요. |
| boost | optional float | 쿼리의 관련성 점수를 낮추거나 높이는 데 사용하는 부동소수점 숫자예요. 기본값은 1.0이에요. |
| x_name | optional string | 쿼리 태깅용 쿼리 이름이에요. |
| analyzer | optional string | 쿼리 문자열 텍스트를 토큰화하는 데 사용하는 분석기예요. |
| auto_generate_synonyms_phrase_query | optional bool | 다중 용어 동의어에 대해 match phrase 쿼리를 자동으로 만들지 여부예요. 기본값은 true예요. |
| fields | repeated string | 검색할 필드 목록이에요. |
| fuzzy_rewrite_deprecated | optional MultiTermQueryRewrite | 더 이상 사용되지 않아요(deprecated). fuzzy_rewrite를 사용하세요. |
| fuzziness | optional Fuzziness | 용어가 값과 일치하는지 판단할 때 한 단어를 다른 단어로 바꾸는 데 필요한 문자 편집(삽입, 삭제, 대체, 전위) 수예요. |
| fuzzy_transpositions | optional bool | 퍼지 작업에 인접 문자 스왑을 추가해요. 기본값은 true예요. |
| lenient | optional bool | 쿼리와 문서 필드 사이의 데이터 타입 불일치를 무시해요. 기본값은 false예요. |
| max_expansions | optional int32 | 쿼리가 확장될 수 있는 최대 용어 수예요. 기본값은 50이에요. |
| minimum_should_match | optional MinimumShouldMatch | 문서가 일치로 간주되기 위해 일치해야 하는 용어 수예요. |
| operator | optional Operator | 모든 용어가 일치해야 하는지(AND) 하나의 용어만 일치해도 되는지(OR)예요. 기본값은 OR이에요. |
| prefix_length | optional int32 | 퍼지 일치에서 고려하지 않는 선행 문자 수예요. 기본값은 0이에요. |
| slop | optional int32 | 쿼리 구문의 단어 사이에 허용되는 다른 단어 수예요. phrase와 phrase_prefix 쿼리 유형에 지원돼요. |
| tie_breaker | optional float | 여러 쿼리 절과 일치하는 문서에 더 많은 가중치를 할당하는 데 사용하는 0과 1.0 사이의 계수예요. |
| type | optional TextQueryType | 다중 일치 쿼리 유형이에요. 유효한 값은 best_fields, most_fields, cross_fields, phrase, phrase_prefix, bool_prefix예요. 기본값은 best_fields예요. |
| zero_terms_query | optional ZeroTermsQuery | 분석기가 모든 용어를 제거할 때 어떤 문서도 일치하지 않게 할지(none) 모든 문서와 일치하게 할지(all) 지정해요. 기본값은 none이에요. |
| fuzzy_rewrite | optional string | OpenSearch가 쿼리를 다시 작성하는 방법을 결정해요. Rewrite parameter values를 참고하세요. 기본값은 constant_score예요. |
MatchAllQuery 필드 (MatchAllQuery fields)
MatchAllQuery 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| boost | optional float | 쿼리의 관련성 점수를 낮추거나 높이는 데 사용하는 부동소수점 숫자예요. 기본값은 1.0이에요. |
| x_name | optional string | 쿼리 태깅용 쿼리 이름이에요. |
MatchNoneQuery 필드 (MatchNoneQuery fields)
MatchNoneQuery 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| boost | optional float | 쿼리의 관련성 점수를 낮추거나 높이는 데 사용하는 부동소수점 숫자예요. 기본값은 1.0이에요. |
| x_name | optional string | 쿼리 태깅용 쿼리 이름이에요. |
복합 쿼리 필드 (Compound query fields)
다음 섹션은 각 복합 쿼리 메시지의 필드를 설명해요.
BoolQuery 필드 (BoolQuery fields)
BoolQuery 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| boost | optional float | 쿼리의 관련성 점수를 낮추거나 높이는 데 사용하는 부동소수점 숫자예요. 기본값은 1.0이에요. |
| x_name | optional string | 쿼리 태깅용 쿼리 이름이에요. |
| filter | repeated QueryContainer | 일치하는 문서에 반드시 있어야 하는 절(쿼리)이에요. 쿼리 점수는 무시돼요. |
| minimum_should_match | optional MinimumShouldMatch | 일치해야 하는 should 절의 최소 수예요. |
| must | repeated QueryContainer | 일치하는 문서에 반드시 있어야 하고 점수에 기여하는 절(쿼리)이에요. |
| must_not | repeated QueryContainer | 일치하는 문서에 있으면 안 되는 절(쿼리)이에요. 모든 문서에 0점이 반환돼요. |
| should | repeated QueryContainer | 일치하는 문서에 있어야 하는 절(쿼리)이에요. |
| adjust_pure_negative | optional bool | 쿼리가 must_not 절만 포함할 때 올바른 동작을 보장해요. 기본값은 true예요. |
ConstantScoreQuery 필드 (ConstantScoreQuery fields)
ConstantScoreQuery 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| filter | QueryContainer | 필수. 문서가 결과에 반환되기 위해 일치해야 하는 필터 쿼리예요. |
| boost | optional float | 쿼리의 관련성 점수를 낮추거나 높이는 데 사용하는 부동소수점 숫자예요. 기본값은 1.0이에요. |
| x_name | optional string | 쿼리 태깅용 쿼리 이름이에요. |
FunctionScoreQuery 필드 (FunctionScoreQuery fields)
FunctionScoreQuery 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| boost | optional float | 쿼리의 관련성 점수를 낮추거나 높이는 데 사용하는 부동소수점 숫자예요. 기본값은 1.0이에요. |
| x_name | optional string | 쿼리 태깅용 쿼리 이름이에요. |
| boost_mode | optional FunctionBoostMode | 계산된 함수 점수가 쿼리 점수와 결합되는 방법을 결정해요. |
| functions | repeated FunctionScoreContainer | 점수 함수예요. 각 항목은 filter, weight, 그리고 exp, gauss, linear, field_value_factor, random_score, script_score 중 하나를 설정할 수 있어요. |
| max_boost | optional float | 함수가 문서 점수에 적용할 수 있는 최대 부스트 값이에요. |
| min_score | optional float | 이 임계값보다 낮은 점수의 문서를 결과에서 제외해요. |
| query | optional QueryContainer | 점수 함수를 적용하기 전에 문서를 선택하는 데 사용하는 쿼리예요. |
| score_mode | optional FunctionScoreMode | 여러 함수의 점수를 하나로 결합하는 방법을 결정해요. |
자세한 내용은 Function score query를 참고하세요.
조인 쿼리 필드 (Joining query fields)
다음 섹션은 각 조인 쿼리 메시지의 필드를 설명해요.
NestedQuery 필드 (NestedQuery fields)
NestedQuery 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| path | string | 필수. 검색할 필드 또는 필드 경로 배열이에요. |
| query | QueryContainer | 필수. 지정된 경로 내의 중첩 객체에서 실행할 쿼리예요. |
| boost | optional float | 쿼리의 관련성 점수를 낮추거나 높이는 데 사용하는 부동소수점 숫자예요. 기본값은 1.0이에요. |
| x_name | optional string | 쿼리 태깅용 쿼리 이름이에요. |
| ignore_unmapped | optional bool | true로 설정하면 매핑되지 않은 필드를 무시하고 어떤 문서와도 일치하지 않아요. 기본값은 false예요. |
| inner_hits | optional InnerHits | 제공되면 쿼리와 일치한 기본 hits를 반환해요. |
| score_mode | optional ChildScoreMode | 일치하는 내부 문서의 점수가 부모 문서의 점수에 영향을 주는 방법을 정의해요. |
지리 쿼리 필드 (Geographic query fields)
다음 섹션은 각 지리 쿼리 메시지의 필드를 설명해요.
GeoBoundingBoxQuery 필드 (GeoBoundingBoxQuery fields)
geo-bounding box 쿼리는 쿼리에 지정된 경계 상자 안에 지오포인트가 있는 문서를 반환해요. GeoBoundingBoxQuery 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| boost | optional float | 쿼리의 관련성 점수를 낮추거나 높이는 데 사용하는 부동소수점 숫자예요. 기본값은 1.0이에요. |
| x_name | optional string | 쿼리 태깅용 쿼리 이름이에요. |
| type | optional GeoExecution | 지리 쿼리의 실행 유형이에요. |
| validation_method | optional GeoValidationMethod | 검증 방법이에요. 유효한 값은 IGNORE_MALFORMED, COERCE, STRICT예요. 기본값은 STRICT예요. |
| ignore_unmapped | optional bool | 매핑되지 않은 필드를 무시할지 여부예요. 기본값은 false예요. |
| bounding_box | map<string, GeoBounds> | 경계 상자를 정의하는 필드 이름에서 지오바운드로의 맵이에요. |
GeoDistanceQuery 필드 (GeoDistanceQuery fields)
geodistance 쿼리는 제공된 지오포인트에서 지정된 거리 내에 지오포인트가 있는 문서를 반환해요. GeoDistanceQuery 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| distance | string | 필수. 점을 일치시킬 거리예요. 이 거리는 지정된 점을 중심으로 한 원의 반지름이에요. |
| boost | optional float | 쿼리의 관련성 점수를 낮추거나 높이는 데 사용하는 부동소수점 숫자예요. 기본값은 1.0이에요. |
| x_name | optional string | 쿼리 태깅용 쿼리 이름이에요. |
| distance_type | optional GeoDistanceType | 거리 계산 방법을 지정해요. 유효한 값은 arc와 plane이에요. 기본값은 arc예요. |
| validation_method | optional GeoValidationMethod | 검증 방법이에요. 유효한 값은 IGNORE_MALFORMED, COERCE, STRICT예요. 기본값은 STRICT예요. |
| ignore_unmapped | optional bool | true로 설정하면 매핑되지 않은 필드를 무시하고 어떤 문서와도 일치하지 않아요. 기본값은 false예요. |
| unit | optional DistanceUnit | 거리 측정 단위예요. |
| location | map<string, GeoLocation> | 중심점을 지정하는 필드 이름에서 지오로케이션으로의 맵이에요. |
특수 쿼리 필드 (Specialized query fields)
다음 섹션은 각 특수 쿼리 메시지의 필드를 설명해요.
knn 쿼리 필드에 대해서는 k-NN (gRPC)를 참고하세요.
ScriptQuery 필드 (ScriptQuery fields)
script 쿼리는 Painless 스크립팅 언어로 작성된 사용자 지정 조건으로 문서를 필터링해요. 자세한 내용은 Painless scripting language를 참고하세요. ScriptQuery 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| script | Script | 필수. 문서를 필터링하기 위해 실행할 스크립트예요. |
| boost | optional float | 쿼리의 관련성 점수를 낮추거나 높이는 데 사용하는 부동소수점 숫자예요. 기본값은 1.0이에요. |
| x_name | optional string | 쿼리 태깅용 쿼리 이름이에요. |
HybridQuery 필드 (HybridQuery fields)
hybrid 쿼리는 주어진 문서에 대해 여러 쿼리의 관련성 점수를 하나의 점수로 결합해요. HybridQuery 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| boost | optional float | 쿼리의 관련성 점수를 낮추거나 높이는 데 사용하는 부동소수점 숫자예요. 기본값은 1.0이에요. |
| x_name | optional string | 쿼리 태깅용 쿼리 이름이에요. |
| queries | repeated QueryContainer | 문서를 일치시키는 데 사용하는 하나 이상의 쿼리 절 배열이에요. 문서가 결과에 반환되려면 최소한 하나의 쿼리 절과 일치해야 해요. 문서의 모든 쿼리 절의 관련성 점수는 검색 파이프라인을 적용해 하나의 점수로 결합돼요. 쿼리 절의 최대 수는 5예요. |
| pagination_depth | optional int32 | hybrid 쿼리의 페이지네이션 깊이예요. |
| filter | optional QueryContainer | hybrid 쿼리의 모든 하위 쿼리에 적용할 필터예요. |
AggregationContainer 필드 (AggregationContainer fields)
AggregationContainer는 실행할 집계를 정의해요. 각 AggregationContainer 메시지에서 다음 필드 중 정확히 하나를 지정하세요.
현재 gRPC Search API는 max, min, terms 집계 유형만 지원해요.
AggregationContainer 메시지는 단일 집계 정의를 감싸고 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| meta | ObjectMap | 집계에 붙이는 선택 사용자 지정 메타데이터예요. |
| max | MaxAggregation | 최댓값 metric 집계예요. 유일하게 설정해야 하는 집계 유형이에요. |
| min | MinAggregation | 최솟값 metric 집계예요. 유일하게 설정해야 하는 집계 유형이에요. |
| terms_aggregation | TermsAggregation | 용어 값으로 문서를 그룹화하는 terms bucket 집계예요. 유일하게 설정해야 하는 집계 유형이에요. |
공통 메시지 값 (Common message values)
다음 섹션은 공통 메시지 유형이 사용하는 값을 설명해요.
Fuzziness
Fuzziness 메시지는 다음 값을 받는 oneof 타입이에요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| string | string | AUTO가 용어의 길이를 기반으로 편집 거리를 생성해요. 선택적으로 AUTO:[low],[high]를 제공할 수 있어요. |
| int32 | int32 | 0, 1, 또는 2: 허용되는 최대 Levenshtein 거리예요. |
Rewrite parameter values
wildcard, prefix, regexp, fuzzy, range 같은 다중 용어 쿼리는 내부적으로 용어 집합으로 확장돼요. rewrite와 fuzzy_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> | 정적 부스트 | 빠름 | 덜 정확한 점수 매기기예요. |
| top_terms_blended_freqs_<n> | 혼합 점수 | 균형 | 최상의 점수/효율 트레이드오프예요. |
MinimumShouldMatch
MinimumShouldMatch 메시지는 다음 값을 받는 oneof 타입이에요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| int32 | int32 | 일치해야 하는 최소 용어 수를 지정하는 정수예요. |
| string | string | 백분율이나 조합을 지정하는 문자열이에요. Minimum should match를 참고하세요. |
FieldValue
FieldValue 메시지는 필드 값을 나타내며 다음 값을 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| bool | optional bool | Boolean 값이에요. |
| general_number | optional GeneralNumber | 숫자 값이에요. |
| string | optional string | 문자열 값이에요. |
| null_value | optional NullValue | null 값이에요. |
InnerHits 필드 (InnerHits fields)
InnerHits 메시지는 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| name | optional string | 응답에서 특정 inner hit 정의에 사용할 이름이에요. |
| size | optional int32 | inner_hits에서 반환할 최대 hit 수예요. |
| from | optional int32 | inner hit의 시작 문서 오프셋이에요. |
| collapse | optional FieldCollapse | 특정 필드 값으로 검색 결과를 그룹화해요. |
| docvalue_fields | repeated FieldAndFormat | OpenSearch가 doc_values를 사용해 반환해야 하는 필드예요. |
| explain | optional bool | OpenSearch가 문서의 점수를 계산한 방법에 대한 세부 정보를 반환할지 여부예요. 기본값은 false예요. |
| highlight | optional Highlight | 하이라이팅은 결과에서 검색 용어를 강조해요. |
| ignore_unmapped | optional bool | 매핑되지 않은 필드를 어떻게 처리할지 지정해요. 기본값은 false예요. |
| script_fields | map<string, ScriptField> | 스크립트를 사용해 값이 계산되는 사용자 지정 필드예요. |
| seq_no_primary_term | optional bool | 각 문서 hit의 마지막 작업의 시퀀스 번호와 프라이머리 텀을 반환할지 여부예요. |
다음 예제들은 모두 SearchService/Search gRPC 메서드로 보낼 수 있는 유효한 요청 페이로드예요.
전체 일치 쿼리 (Match all query)
match_all 쿼리는 인덱스의 모든 문서를 반환해요. 예를 들어 다음 요청은 인덱스에서 최대 50개 문서를 반환해요.
{
"search_request_body": {
"query": {
"match_all": {}
},
"size": 50
}
}
용어 쿼리 (Term query)
term 쿼리는 특정 용어와 단일 필드를 일치시켜요. 예를 들어 다음 쿼리는 제목에 Rush라는 단어를 포함하는 것을 검색해요.
{
"index": "my_index",
"search_request_body": {
"query": {
"term": {
"field": "title",
"value": {
"string_value": "Rush"
},
"case_insensitive": true
}
}
}
}
용어들 쿼리 (Terms query)
terms 쿼리는 특정 필드가 목록의 어떤 값이라도 포함하는 문서와 일치해요. 예를 들어 다음 쿼리는 ID 61809와 61810을 가진 라인을 검색해요.
{
"search_request_body": {
"query": {
"terms": {
"terms_lookup_field_string_array_map": {
"line_id": {
"string_array": {
"string_array": ["61809", "61810"]
}
}
}
}
}
}
}
용어 조회가 있는 용어들 쿼리 (Terms query with a terms lookup)
용어 조회(terms lookup)가 있는 terms 쿼리는 쿼리에 직접 지정하는 대신 클러스터의 다른 문서에서 필터링할 용어를 가져올 수 있게 해주는 terms 쿼리의 특수 형태예요. 예를 들어 다음 요청은 students 인덱스에서 enrolled 배열의 값 중 하나와 id가 일치하는 모든 학생과 일치하는 문서를 찾아요.
{
"search_request_body": {
"query": {
"terms": {
"boost": 1.0,
"terms_lookup_field_string_array_map": {
"student_id": {
"terms_lookup_field": {
"index": "classes",
"id": "101",
"path": "enrolled"
}
}
}
}
}
}
}
어떤 문서도 일치하지 않는 쿼리 (Match none query)
match_none 쿼리는 어떤 문서와도 일치하지 않아요.
{
"search_request_body": {
"query": {
"match_none": {}
}
}
}
응답 필드 (Response fields)
gRPC Search API는 다음 응답 필드를 반환해요.
SearchResponse 필드 (SearchResponse fields)
다음 표는 SearchResponse 메시지의 지원 필드를 보여줘요.
소스 문서는 바이트로 반환돼요. gRPC 응답에서 _source 필드를 읽으려면 Base64 디코딩을 사용하세요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| took | int64 | 검색 요청을 처리하는 데 걸린 시간(밀리초)이에요. |
| timed_out | bool | 검색이 제한 시간을 넘겼는지 여부예요. |
| x_shards | ShardStatistics | 샤드 수준의 성공/실패/전체 메타데이터예요. |
| phase_took | PhaseTook | 응답의 단계별 took 시간 값이에요. |
| hits | HitsMetadata | 메인 문서 결과와 메타데이터예요. |
| processor_results | repeated ProcessorExecutionDetail | 프로세서 실행 세부 정보예요. |
| x_clusters | ClusterStatistics | 원격 클러스터를 검색할 때 각 클러스터에 대한 검색 정보예요. |
| fields | ObjectMap | 더 이상 사용되지 않아요(deprecated). 검색 응답에서 특정 필드를 가져왔어요. |
| num_reduce_phases | int32 | 코디네이팅 노드가 샤드 응답 배치에서 결과를 집계한 횟수예요. |
| profile | Profile | 쿼리 실행의 프로파일링 데이터(디버깅/성능 인사이트)예요. |
| pit_id | string | Point in Time ID예요. |
| x_scroll_id | string | 검색과 그 검색 컨텍스트의 식별자예요. |
| terminated_early | bool | 쿼리가 조기 종료되었는지 여부예요. |
| aggregations | map<string, Aggregate> | 검색 응답과 함께 반환되는 집계 결과예요. |
Aggregate 필드 (Aggregate fields)
Aggregate 메시지는 단일 집계 결과를 나타내며 다음 필드를 받아요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| dterms | DoubleTermsAggregate | double 값 버킷 키를 가진 terms 집계예요. |
| lterms | LongTermsAggregate | signed long 버킷 키를 가진 terms 집계예요. |
| max | SingleMetricAggregateBase | max 집계의 결과예요. |
| min | SingleMetricAggregateBase | min 집계의 결과예요. |
| sterms | StringTermsAggregate | string 버킷 키를 가진 terms 집계예요. |
| ulterms | UnsignedLongTermsAggregate | unsigned long 버킷 키를 가진 terms 집계예요. |
| umterms | UnmappedTermsAggregate | 매핑되지 않은 필드의 terms 집계 결과예요. |
HitsMetadata 필드 (HitsMetadata fields)
HitsMetadata 객체는 검색 결과에 대한 정보를 담고 있어요. 일치하는 전체 문서 수와 개별 문서 일치 배열을 포함해요. 다음 필드를 포함해요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| total | HitsMetadataTotal | 일치하는 전체 문서 수에 대한 메타데이터(value + relation)예요. |
| max_score | HitsMetadataMaxScore | 반환된 hits의 가장 높은 관련성 점수예요(null일 수 있음). |
| hits | repeated HitsMetadataHitsInner | 실제 일치 문서 목록이에요. 각 hit는 index, id, score, source 같은 핵심 필드와 추가 선택 필드를 포함해요. |
HitsMetadataHitsInner 필드 (HitsMetadataHitsInner fields)
각 HitsMetadataHitsInner는 쿼리와 일치한 단일 문서를 나타내며 다음 필드를 포함해요.
| 필드 | Protobuf 타입 | 설명 |
|---|---|---|
| x_type | string | 문서 유형이에요. |
| x_index | string | 반환된 문서를 담고 있는 인덱스의 이름이에요. |
| x_id | string | 인덱스 안에서 문서의 고유 ID예요. |
| x_score | HitXScore | hit의 관련성 점수예요. |
| x_explanation | Explanation | _score가 어떻게 계산되었는지에 대한 텍스트 설명이에요. |
| fields | ObjectMap | 문서 필드 값이에요. |
| highlight | map<string, StringArray> | hit별 하이라이트된 필드와 조각이에요. |
| inner_hits | map<string, InnerHitsResult> | 전체 쿼리 결과에 기여한 다른 스코프의 일치하는 중첩 문서예요. |
| matched_queries | repeated string | 더 이상 사용되지 않아요(deprecated). 문서와 일치하는 쿼리 이름 목록이에요. |
| x_nested | NestedIdentity | hit가 유래한 내부 중첩 객체로의 경로예요. |
| x_ignored | repeated string | 무시된 필드 목록이에요. |
| ignored_field_values | map<string, StringArray> | 문서 원본 JSON의 가공되지 않은, 처리되지 않은 값이에요. |
| x_shard | string | hit를 가져온 샤드 ID예요. |
| x_node | string | hit를 가져온 노드 ID예요. |
| x_routing | string | 사용자 지정 샤드 라우팅에 사용한 라우팅 값이에요. |
| x_source | bytes | Base64 인코딩된 _source 문서예요. |
| x_seq_no | int64 | 시퀀스 번호예요(인덱싱 기록과 버전 관리에 사용). |
| x_primary_term | int64 | 프라이머리 텀 번호예요(낙관적 동시성 제어에 사용). |
| x_version | int64 | 문서 버전 번호예요. |
| sort | repeated FieldValue | 결과 정렬에 사용되는 정렬 값이에요. |
| meta_fields | ObjectMap | 문서의 메타데이터 값이에요. |
| matched_queries_2 | HitMatchedQueries | 문서에 대한 일치 쿼리 이름의 현재 protobuf 표현이에요. |
source는 Base64 인코딩되어 있으며, JSON 문서를 얻으려면 디코딩해야 해요.
예제 응답 (Example response)
{
"response_body": {
"took": 64,
"timed_out": false,
"shards": {
"successful": 1,
"total": 1
},
"hits": {
"total": {
"total_hits": {
"relation": "TOTAL_HITS_RELATION_EQ",
"value": 1
}
},
"hits": [
{
"index": "my_index",
"id": "3",
"score": {
"float_value": 1.0
},
"source": "eyAidGl0bGUiOiAiUnVzaCIsICJ5ZWFyIjogMjAxM30=",
"meta_fields": {}
}
],
"max_score": {
"float_value": 1.0
}
}
}
}
Java gRPC 클라이언트 예제 (Java gRPC client example)
다음 예제는 예제 검색 term 쿼리 gRPC 요청을 제출하고 검색 응답에서 반환된 hit 수를 출력하는 Java 클라이언트 프로그램을 보여줘요.
import org.opensearch.protobufs.*;
import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;
public class SearchClient {
public static void main(String[] args) {
ManagedChannel channel = ManagedChannelBuilder.forAddress("localhost", 9400)
.usePlaintext()
.build();
SearchServiceGrpc.SearchServiceBlockingStub stub = SearchServiceGrpc.newBlockingStub(channel);
// Create a term query
TermQuery termQuery = TermQuery.newBuilder()
.setField("director")
.setValue(FieldValue.newBuilder().setStringValue("Nolan").build())
.build();
// Create query container
QueryContainer queryContainer = QueryContainer.newBuilder()
.setTerm(termQuery)
.build();
// Create search request body
SearchRequestBody requestBody = SearchRequestBody.newBuilder()
.setQuery(queryContainer)
.setSize(5)
.build();
// Create search request
SearchRequest request = SearchRequest.newBuilder()
.addIndex("movies")
.setSearchRequestBody(requestBody)
.build();
try {
SearchResponse response = stub.search(request);
// Handle the response
System.out.println("Search took: " + response.getTook() + " ms");
System.out.println("Timed out: " + response.getTimedOut());
HitsMetadata hits = response.getHits();
if (hits.hasTotal()) {
System.out.println("Total hits: " + hits.getTotal().getTotalHits().getValue());
}
// Process individual hits
for (HitsMetadataHitsInner hit : hits.getHitsList()) {
System.out.println("Hit ID: " + hit.getXId());
System.out.println("Hit Index: " + hit.getXIndex());
if (hit.hasXScore()) {
System.out.println("Score: " + hit.getXScore().getDouble());
}
}
} catch (io.grpc.StatusRuntimeException e) {
System.err.println("gRPC search request failed with status: " + e.getStatus());
System.err.println("Error message: " + e.getMessage());
}
channel.shutdown();
}
}
Python gRPC 클라이언트 예제 (Python gRPC client example)
다음 예제는 Python 클라이언트 애플리케이션으로 같은 요청을 보내는 방법을 보여줘요.
먼저 pip로 opensearch-protobufs 패키지를 설치해요.
pip install opensearch-protobufs==1.2.0
다음 코드로 요청을 보내요.
import grpc
from opensearch.protobufs.schemas import *
from opensearch.protobufs.services import SearchServiceStub
channel = grpc.insecure_channel(
target="localhost:9400",
)
search_stub = SearchServiceStub(channel)
# Create a term query
term_query = TermQuery(
field="field",
value=FieldValue(string="value")
)
query_container = QueryContainer(term=term_query)
# Create a search request
request = SearchRequest(
search_request_body=SearchRequestBody(query=query_container),
index=["my-index"]
)
# Send request and handle response
try:
response = search_stub.Search(request=request)
if response.hits:
print("Found {} hits".format(response.hits.total))
print(response.hits)
elif response.timed_out or response.terminated_early:
print("Request timed out or terminated early")
elif response.x_shards.failed:
print("Some shards failed to execute the search")
print(response.x_shards.failures)
except grpc.RpcError as e:
if e.code() == StatusCode.UNAVAILABLE:
print("Failed to reach server: {}".format(e))
elif e.code() == StatusCode.PERMISSION_DENIED:
print("Permission denied: {}".format(e))
elif e.code() == StatusCode.INVALID_ARGUMENT:
print("Invalid argument: {}".format(e))
finally:
channel.close()