---
title: "검색 쿼리"
slug: "cloudsearch-searchquery"
updated: 2026-09-17T09:07:20Z
published: 2026-09-17T09:07:20Z
canonical: "guide.ncloud-docs.com/cloudsearch-searchquery"
stale: true
---
> ## Documentation Index
> Fetch the complete documentation index at: https://guide.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 검색 쿼리
Classic/VPC 환경에서 이용 가능합니다.
Cloud Search는 검색을 위한 Search API를 제공합니다. 도메인 생성 시 설정한 문서 설정 및 색인 설정을 이용하여 검색할 수 있습니다. 검색 요청 방법은 다음 중 하나를 선택할 수 있습니다.
- [요청 바디에 입력](/docs/cloudsearch-searchquery#%EC%9A%94%EC%B2%AD%EB%B0%94%EB%94%94%EC%97%90%EC%9E%85%EB%A0%A5): API 요청 시 검색 쿼리를 요청 바디에 입력
- [URI에 입력](/docs/cloudsearch-searchquery#URI%EC%97%90%EC%9E%85%EB%A0%A5): API 요청 시 검색 쿼리를 URL에 입력
검색 쿼리에서는 검색 쿼리의 형식과 필드별 설명 및 작성 예시를 안내합니다.
참고
여기에서는 검색 쿼리에 대한 내용을 중심으로 설명합니다. API 사용 방법에 대한 자세한 내용은 [Cloud Search API 가이드](https://api.ncloud-docs.com/docs/analytics-cloudsearch)를 참조해 주십시오.
## 요청 바디에 입력
검색 쿼리를 요청 바디에 입력하여 API를 호출합니다.
- JSON 형태의 Query DSL 형식으로 입력합니다.
- 메소드는 HTTP POST를 선택합니다.
요청 바디에 입력하는 검색 쿼리의 템플릿은 다음과 같습니다.
```
{
"start": (string|int),
"display": (string|int),
"result_format": (string),
"search": {
"[index_name]": {
"[query_method]": [{
"query": (string),
"name": (string),
"type": (string),
"option": (string|bool),
"ratio": (string|double),
"term_extractor": (string),
"syno": (bool),
"stopword": (string)
}]
}
},
"sort": {
"[sort_target]": (string)
},
"scope": {
"[scope_target]": {
"[scope_method]": (string|int|double|array)
}
},
"key_scope": {
"[scope_method]": (string|array)
},
"user_scope": (string),
"highlighting": {
"enable": (string|bool),
"pre_tag": (string),
"post_tag": (string),
"[highlighting_option]": (string|bool)
},
"display_section": (string|array),
"passage": {
"[section_name]": {
"passage_type": (string),
"passage_option": (string),
"max_length": (string)
},
},
"aggregate": {
"[docprop_name]": {
"max": (string),
"min": (string),
"one": (string),
"sum": (string)
}
},
"result_processing": {
"[section_name]": {
"remove_duplicate": (string|bool)
}
},
"setting": {
"transfer_timeout": (string|int),
"search_timeout": (string|int),
"use_df": (string|bool),
"reuse_term_extractor": (string|bool),
"log_level": (string|list),
}
}
```
각 필드에 대한 설명은 다음과 같습니다.
| 필드명 | 필수 여부 | 타입 | 제약 사항 | 설명 | 참고 |
| --- | --- | --- | --- | --- | --- |
| start | No | String, Integer | 기본값: 1 | 검색 결과의 시작 랭킹 | [start](/docs/cloudsearch-searchquery#start1) |
| display | No | String, Integer | 기본값: 20 | 검색 결과의 개수 | [display](/docs/cloudsearch-searchquery#display1) |
| result_format | No | String | 기본값: json | 검색 결과 형식 지정 | [result_format](/docs/cloudsearch-searchquery#resultformat1) |
| search | Yes | - index_name: String - queryList: List<[SearchQuery](https://api.ncloud-docs.com/docs/common-apidatatype-cssearchquery)> | - index_name: 기존에 생성된 색인 중 선택 - queryList: SearchQuery.query_method가 'main'인 main 쿼리를 반드시 포함 | - index_name: 검색할 색인의 이름 - queryList: 검색 요청 쿼리 | [search](/docs/cloudsearch-searchquery#search1) |
| sort | No | Object | - | 검색 결과 정렬 기준을 나타내는 Map 형태의 Object | [sort](/docs/cloudsearch-searchquery#sort1) |
| scope | No | List<[SearchScope](https://api.ncloud-docs.com/docs/common-apidatatype-cssearchscope)> | - | 제한 검색 설정 목록 | [scope](/docs/cloudsearch-searchquery#scope1) |
| key_scope | No | Object | - | 제한 검색을 설정하는 Map 형태의 Object | [key_scope](/docs/cloudsearch-searchquery#keyscope1) |
| user_scope | No | String | 랭킹 코드 형태의 수식 | - 사용자가 직접 scope 수식 입력 - scope 파라미터의 내용과 AND 조건으로 적용 | [user_scope](/docs/cloudsearch-searchquery#userscope1) |
| highlighting | No | SearchHighlighting | 기본값: true | 검색 결과 구문 강조 설정 | [highlighting](/docs/cloudsearch-searchquery#highlighting1) |
| display_section | No | String, Array | 기존에 생성한 섹션 중 선택 | 검색 결과로 보여줄 섹션을 지정 | [display_section](/docs/cloudsearch-searchquery#displaysection1) |
| passage | No | List<[SearchPassage](https://api.ncloud-docs.com/docs/common-apidatatype-cssearchpassage)> | - | 검색 결과 추출 방식 설정 | [passage](/docs/cloudsearch-searchquery#passage1) |
| aggregate | No | List<[SearchAggregate](https://api.ncloud-docs.com/docs/common-apidatatype-cssearchaggregate)> | - | 검색 결과 요약 설정 목록 | [aggregate](/docs/cloudsearch-searchquery#aggregate1) |
| ranking | No | - ranking.name: string - ranking.code: string - ranking.override_value.{ranking_value}: string, int, float | - | 랭킹 모듈 또는 랭킹 코드 설정 | [ranking](/docs/cloudsearch-searchquery#ranking1) |
| result_processing | No | [SearchResultProcessing](https://api.ncloud-docs.com/docs/common-apidatatype-cssearchresultprocessing) | - | 검색 결과 후처리 설정 | [result_processing](/docs/cloudsearch-searchquery#resultprocessing1) |
| setting | No | [SearchSetting](https://api.ncloud-docs.com/docs/common-apidatatype-cssearchsetting) | - | 검색 시 기타 환경 설정 | [setting](/docs/cloudsearch-searchquery#setting1) |
### start
표시할 검색 결과의 시작 랭킹을 선택하는 필드입니다. 기본값은 1이며, 입력 형식은 다음과 같습니다.
```
{
"start": (string|int)
}
```
<예시>
```
{
"start": 1,
"search": {
"body_sgmt": {
"main": {
"query": "검색",
}
}
},
}
```
### display
표시할 검색 결과의 개수를 선택하는 필드입니다. 기본값은 20이며, 입력 형식은 다음과 같습니다.
```
{
"display": (string|int)
}
```
<예시>
```
{
"display": 20,
"search": {
"body_sgmt": {
"main": {
"query": "검색",
}
}
},
}
```
### result_format
검색 결과의 형식을 지정합니다. 입력 형식은 다음과 같습니다.
```
{
"result_format": (string)
}
```
- `result_format`: 검색 결과 형식을 json, xml 중 선택(기본값: json)
<예시>
```
{
"search": {
"body_sgmt": {
"main": {
"query": "검색",
}
}
},
"result_format": "json"
}
```
### search
검색을 위한 필드로, 반드시 입력해야 하는 필드입니다. 입력 형식은 다음과 같습니다.
```
{
"search": {
"[index_name]": {
"[query_method]": {
"query": (string),
"name": (string),
"type": (string),
"option": (string),
"ratio": (string|double),
"term_extractor": (string),
"syno": (bool),
"stopword": (string)
}
}
}
}
```
- `[index_name]`: 검색할 색인 지정
- `[query_method]`: 검색 방식 선택
- `main`: 검색 요청 시 반드시 포함해야 하며, main 쿼리를 지정합니다.
- 검색 결과는 main 쿼리 결과 집합의 합집합 연산 결과로 나타납니다.
- `intersection`: intersection 쿼리를 지정합니다.
- 검색 결과는 main 쿼리 결과 집합과 intersection 쿼리 결과 집합의 교집합 연산 결과로 나타납니다.
- `scope`: scope 쿼리를 지정합니다. intersection 쿼리와 효과는 같지만, 문서 가중치(qds)가 변경되지 않습니다.
- `exclusion`: exclusion 쿼리를 지정합니다.
- 검색 결과는 main, intersection, scope 쿼리의 결과 집합과 exclusion 쿼리의 결과 집합의 차집합 연산 결과로 나타납니다.
- `rerank`: 검색 결과에 영향을 주지 않지만, 문서 가중치(qds)가 변경됩니다.
- 사용 가능한 쿼리 타입: `simbst`, `proxrank`
- `query`: 검색 질의 지정
- `name`: 검색 시 사용할 질의 이름 지정
- `type`: 쿼리 타입 지정
- `oneterm`: 질의의 텀이 하나일 때 사용하며, 해당 텀을 포함한 문서를 찾습니다. 텀이 여러 개일 때는 첫 번째로 분석된 텀을 사용합니다.
- `nterm`: 질의의 텀이 여러 개일 때 사용하며, 해당 단어를 포함한 문서를 찾습니다. `option` 파라미터를 사용할수 있습니다.
- `nofm`: 질의의 텀이 `ratio` 파라미터로 지정된 비율 이상 포함된 문서를 찾습니다.
- `ebool`: boolean 연산자를 조합한 결과를 만족하는 문서를 찾습니다.
- 사용 가능 연산자: `&`(AND), `|`(OR), `!`(NOT)
- 여러 개의 연산자를 입력할 수 있습니다.
- 검색 사용자가 직접 연산자를 입력할 수 있으며, 연산자(`&`, `|`, `!`)의 좌우에 공백이 있어야 연산자로 인식합니다.
- 색인어와 연산자의 관계를 postorder 형식으로 구성하여 bool 표현식을 작성해야 합니다.
- `simbst`: 검색된 문서 중에서 질의 단어를 포함하는 문서는 `ratio` 파라미터로 주어진 값만큼 문서 가중치(qds)를 올립니다.
- `proxrank`: 근접도(prox)를 계산합니다.
- `null`: 빈 질의로 전체 문서를 검색합니다.
- `option`: 쿼리 타입의 옵션 지정
- `and`: 주어진 모든 텀이 포함된 문서만 찾습니다.
- `or`: 주어진 텀 중 하나라도 포함된 문서를 모두 찾습니다.
- `advance`: 주어진 모든 텀이 순서대로 포함되고 인접한 두 색인어의 거리가 그 위치 차이만큼인 문서를 찾습니다.
- `near`: 주어진 모든 텀이 순서에 상관없이 포함되고 인접한 두 색인어의 거리가 그 위치 차이 이내인 문서를 찾습니다.
- `within`: 주어진 모든 텀이 순서대로 포함되고 인접한 두 색인어의 거리가 그 위치 차이 이내인 문서를 찾습니다.
- `ormax`: `or`과 같지만, 연산자가 적용된 색인어 중 랭킹값이 가장 큰 색인어를 선택합니다. 동의어 검색에서 사용합니다.
- `ratio`: 특정 쿼리 타입(`nofm`, `simbst`) 사용 시 비율 지정
- `term_extractor`: 검색 질의의 텀 추출 방식을 지정(기본값: 색인의 분석 옵션)
- 색인 분석기에 한글과 영어를 동시에 사용할 경우에는 이 옵션을 사용해야 합니다.
- <예시> `"term_extractor": "sgmt +english +revert +korea +josacat +eomicat"`
- 사용 시, `setting` 필드에 `"reuse_term_extractor": true` 옵션을 추가해야 합니다.
- `syno`: 동의어 사전의 사용 여부 선택
- `stopword`: 적용할 불용어 규칙 입력
search 필드의 작성 예시는 다음과 같습니다.
- 검색 방식(`[query_method]`)별 예시
<예시> main 쿼리
```
{
"search": {
"body_sgmt": {
"main": {
"query": "검색",
"type": "nterm",
"option": "and"
}
}
}
}
```
<예시> intersection 쿼리
```
{
"search": {
"body_sgmt": {
"main": {
"query": "검색",
"type": "nterm",
"option": "and"
},
"intersection": {
"query": "좋아요",
"type": "nterm",
"option": "and"
}
}
}
}
```
<예시> scope 쿼리
```
{
"search": {
"body_sgmt": {
"main": {
"query": "검색",
"type": "nterm",
"option": "and"
},
"scope": {
"query": "좋아요",
"type": "nterm",
"option": "and"
}
}
}
}
```
<예시> exclusion 쿼리
```
{
"search": {
"body_sgmt": {
"main": {
"query": "검색",
"type": "nterm",
"option": "and"
},
"exclusion": {
"query": "나빠요",
"type": "nterm",
"option": "and"
}
}
}
}
```
<예시> rerank 쿼리
```
{
"search": {
"body_sgmt": {
"main": {
"query": "검색",
"type": "nterm",
"option": "and"
},
"rerank": {
"query": "좋아요",
"type": "simbst",
"ratio": 0.7
}
}
}
}
```
- 쿼리 타입(`type`)별 예시
<예시> oneterm 타입
```
{
"search": {
"body_sgmt": {
"main": {
"query": "검색",
"type": "oneterm"
}
}
}
}
```
<예시> nterm 타입
```
{
"search": {
"title_sgmt": {
"main": {
"query": "검색이 좋아요",
}
}
}
}
```
<예시> nform 타입
```
{
"search": {
"body_sgmt": {
"main": {
"query": "검색이 좋아요",
"type": "nofm",
"ratio": 0.7
}
}
}
}
```
<예시> ebool 타입
```
{
"search": {
"body_sgmt": {
"main": {
"query": "검색 | 좋아요 & 싫어요 ! 안되요" ,
"type": "ebool"
}
}
}
}
```
<예시> simbst 타입
```
{
"search": {
"body_sgmt": {
"main": {
"query": "테스트"
},
"rerank": {
"query": "검색",
"type": "simbst",
"ratio": 0.7
}
}
}
}
```
<예시> proxrank 타입
```
{
"search": {
"title_sgmt": {
"main": {
"query": "테스트"
},
"rerank": {
"query": "검색",
"type": "proxrank",
"option": "exprox"
}
}
}
}
```
<예시> null 타입
```
{
"search": {
"body_sgmt": {
"main": {
"type": "null"
}
}
}
}
```
- 여러 색인을 검색하는 예시
<예시> main 쿼리
```
{
"search": {
"Index_A": {
"main": [{
"query": "a"
},{
"query": "b"
}]
},
"Index_B": {
"main": {
"query": "c"
}
}
}
}
```
<예시> main 쿼리 + intersection 쿼리
```
{
"search": {
"Index_A": {
"main": {
"query": "a"
}
},
"Index_B": {
"main": {
"query": "b"
}
},
"Index_C": {
"intersection": {
"query" : "c"
}
}
}
}
```
<예시> main 쿼리 + exclusion 쿼리
```
{
"search": {
"Index_A": {
"main": {
"query": "a"
}
},
"Index_B": {
"main": {
"query": "b"
}
},
"Index_C": {
"exclusion": {
"query" : "c"
}
}
}
}
```
### sort
검색 결과 정렬 기준을 설정하는 필드입니다. 입력 형식은 다음과 같습니다.
```
{
"sort": {
"[sort_target]": [sort_option](string)
}
}
```
- `[sort_target]`: 정렬 기준 지정
- 문서 속성 또는 랭킹 모듈의 변수 입력
- `[sort_option]`: 정렬 방식 지정
- `asc`: 오름차순
- `desc`: 내림차순
<예시>
```
{
"search": {
"body_sgmt": {
"main": {
"query": "검색",
}
}
},
"sort": {
"dp_pubdate": "desc"
}
}
```
### scope
검색 대상 및 결과를 제한하는 제한 검색을 하기 위한 필드입니다. 입력 형식은 다음과 같습니다.
```
{
"scope": {
"[scope_target]": {
"[scope_method]": (string|int|double|array)
}
}
}
```
- `[scope_target]`: 제한 검색 대상 지정
- 문서 속성 또는 랭킹 모듈의 변수 입력
- `[scope_method]`: 제한 검색 방식 선택
- `exist`/`nexist`: 지정 문서 속성에 지정한 값이 존재하는/존재하지 않는 문서로 검색 결과를 제한합니다.
- `range`/`nrange`: 지정 문서 속성에 지정한 범위의 값이 존재하는/존재하지 않는 문서로 검색 결과를 제한합니다.
- gte:lte 방식으로 적용됩니다. <예시> `"nrange": [1, 1000]` 입력 시 지정 속성값이 1 이상 1000 이하인 문서 제외
- `gte`, `gt`, `lte`, `lt`: 지정 문서 속성에 지정한 범위의 값이 존재하는 문서로 검색 결과를 제한합니다.(gte: 크거나 같다, gt: 크다, lte: 작거나 같다, lt: 작다)
- 날짜값을 지정한 범위로 검색하기 위해서는 Long 타입의 timestamp 형식으로 변환해서 사용해야 합니다.
- `bit`/`nbit`: 지정한 비트의 값과 문서 속성을 연산하여 참/거짓인 경우의 문서로 검색 결과를 제한합니다.
- `bitmask`: 지정한 비트의 값과 문서 속성을 bitmask 연산하여 참인 경우의 문서로 검색 결과를 제한합니다.
- `contains`/`ncontains` : 멀티 타입(muint32, muint64, mstring 등)의 문서 속성을 대상으로, 지정 문서 속성에 지정한 값을 포함하는/포함하지 않는 문서로 검색 결과를 제한합니다.
제한 검색 방식별 scope 필드의 작성 예시는 다음과 같습니다. <예시> `exist`, `nexist`
```
{
"search": {
"body_sgmt": {
"main": {
"query": "검색",
}
}
},
"scope": {
"dp_docprop1": {
"exist": 1,
"nexist": [1,2,3,4,5],
},
"dp_docprop2": {
"nexist": 5
}
}
}
```
<예시> `range`, `nrange`
```
{
"search": {
"body_sgmt": {
"main": {
"query": "검색",
}
}
},
"scope": {
"dp_docprop1": {
"range": ["1", "10"],
"nrange": ["1", "10"]
},
"dp_docprop2": {
"range": ["2", "5"]
}
}
}
```
<예시> `gte`, `gte`, `lte`, `lt`
```
{
"search": {
"body_sgmt": {
"main": {
"query": "검색",
}
}
},
"scope": {
"dp_docprop": {
"gte": "0",
"gt": "0",
"lte": "1",
"lt": "1"
}
}
}
```
<예시> `bit`, `nbit`, `bitmask`
```
{
"search": {
"body_sgmt": {
"main": {
"query": "검색",
}
}
},
"scope": {
"dp_docprop": {
"bit": "11110000",
"nbit": "10101010",
"bitmask": "11110000"
}
}
}
```
<예시> `contains`, `ncontains`
```
{
"search": {
"body_sgmt": {
"main": {
"query": "검색",
}
}
},
"scope": {
"dp_multi_docprop": {
"contains": [1,2,3],
// "contains" : "1,2,3",
"ncontains": [4,5,6]
// "not contain" : "4,5,6",
}
}
}
```
### key_scope
문서의 key(메인 섹션)를 기준으로 검색 대상 및 결과를 제한하는 key 제한 검색을 하기 위한 필드입니다. 입력 형식은 다음과 같습니다.
```
{
"key_scope": {
"[key_scope_method]": (string|array)
}
}
```
- `[key_scope_method]`: 문서 key에 대한 제한 검색 방식 선택
- `exist`/`nexist`: 지정한 문서 key에 해당하는/해당하지 않는 문서로 검색 결과를 제한합니다.
<예시>
```
{
"search": {
"body_sgmt": {
"main": {
"query": "검색",
}
}
},
"key_scope": {
"exist": "A017a75c_000000000001fca5990e8e04",
"nexist": ["A017a75c_000000000001fca5990e8e10", "A017a75c_000000000001fca5990e8e20"]
}
}
```
### user_scope
필드에 사용자가 직접 scope 수식을 입력하여 제한 검색을 할 수 있습니다. 입력 형식은 다음과 같습니다.
```
{
"user_scope": (string)
}
```
- `user_scope`: 랭킹 코드 형태의 scope 수식 입력
- 입력된 수식은 검색 시 `scope` 파라미터의 내용과 AND 조건으로 적용됩니다.
<예시 1>
```
{
"search": {
"body_sgmt": {
"main": {
"query": "검색",
}
}
},
"user_scope": "(dp_like_cnt => 100) and (dp_like_cnt <= 600)"
}
```
<예시 2>
```
{
"search": {
"body_sgmt": {
"main": {
"query": "검색",
}
}
},
"user_scope": "(dp_grade == 1) or (dp_grade == 2)"
}
```
### highlighting
검색 질의에 대해 구문 강조 설정을 하기 위한 필드입니다. 입력 형식은 다음과 같습니다.
```
"highlighting": {
"enable": (string|bool),
"pre_tag": (string),
"post_tag": (string),
"[highlighting_option]": (string|bool)
}
```
- `enable`: 강조 여부 선택(기본값: `true`)
- `pre_tag`, `post_tag`: 검색 결과 매치된 텀을 강조할 구문 강조 태그 지정
- 지정하지 않으면 기본으로 , 가 사용됩니다.
- `highlighting_option`: 구문 강조 옵션 지정(기본값: `false`)
- `remove_html_tag`: 활성화 시 HTML 태그를 제거합니다.
- `skip_html_tag`: 활성화 시 HTML 태그를 강조하거나 태그에 포함된 문자를 변형하지 않고 그대로 유지합니다.
- `braket_as_tag`: 활성화 시 '<'와 '>' 사이는 모두 HTML 태그로 간주합니다.
- `num_entity_as_char`: 활성화 시 '가'와 같은 숫자형 엔티티를 문자로 취급합니다.
- 강조 처리도 해당 엔티티를 문자로 취급하여 처리합니다.
- `skip_char_entity`: 활성화 시 문자형 엔티티를 강조하거나 포함된 문자를 변형하지 않고 그대로 유지합니다.
- `kata_to_hira`: 활성화 시 서로 대응되는 일본어 카타카나 문자와 히라가나 문자를 같은 문자로 취급합니다.
- `bold_sub_query`: 활성화 시 질의와 정확히 일치하는 문자열이 검색되어도 부분 키워드를 모두 강조합니다.
- `bold_sub_english`: 활성화 시 영어 단어의 일부분이 텀과 일치하는 경우에도 강조합니다.
<예시> 텀이 'a'일 때 'about'의 첫 글자 'a'를 강조합니다.
- `bold_sub_digit`: 활성화 시 숫자의 일부분이 텀과 일치하는 경우에도 강조합니다.
<예시> 텀이 '1'일 때 '12345'의 첫 숫자 '1'을 강조합니다.
- `bold_sub_hanja`: 활성화 시 한자도 강조합니다.
<예시>
```
{
"search": {
"body_sgmt": {
"main": {
"query": "검색",
}
}
},
"highlighting": {
"enable": true,
"pre_tag": "",
"post_tag": "",
"remove_html_tag": true,
"skip_html_tag": true,
"num_entity_as_char": false,
"braket_as_tag": false,
"skip_char_entity": true,
"kata_to_hira": false,
"bold_sub_query": false,
"bold_sub_english": true,
"bold_sub_digit": true,
"bold_sub_hanja": false,
}
}
```
### display_section
검색 결과에 표시할 섹션과 표시 방식을 지정하는 필드입니다.
- 해당 필드를 설정하지 않으면 전체 섹션의 결과를 표시합니다.
- 섹션을 지정하면 선택한 섹션의 정보만 표시합니다.
입력 형식은 다음과 같습니다.
```
{
"display_section": (string|array),
}
```
- `display_section`: 검색 결과에 표시할 섹션을 지정하며, 여러 섹션 조합 가능
<예시> 가격과 이름만 결과로 출력하고 싶을 때: `"price, name"` 입력
<예시> 브랜드와 이름을 하나의 결과로 출력하고 싶을 때: `"brand+name"` 입력
<예시>
```
{
"search": {
"body_sgmt": {
"main": {
"query": "검색",
}
}
},
"display_section": ["TITLE","BODY","CONTENTS","TITLE+BODY"],
"display_section": "TITLE,BODY,CONTENTS,TITLE+BODY"
}
```
### passage
검색 결과를 추출하는 방식을 지정하는 필드입니다.
- 해당 필드를 설정하지 않으면, 전체 섹션의 결과를 읽습니다.
- 섹션을 지정하면, 선택한 섹션의 결과만 읽습니다.
입력 형식은 다음과 같습니다.
```
{
"passage": {
"[section_name]": {
"passage_type": (string),
"passage_option": (string),
"max_length": (string|int)
}
}
}
```
- `[section_name]`: 섹션 이름을 지정하며, 여러 섹션 조합 가능 <예시> `TITLE+BODY`
- `passage_type`: passage 추출 방식 지정
- `none`: 섹션의 앞 부분부터 읽습니다.
- `classic`: 섹션에서 질의 색인어 주변을 읽습니다.
- `passage_option`: passage 추출 옵션 지정
- `max_length`: passage 추출 길이 지정
<예시>
```
{
"search": {
"body_sgmt": {
"main": {
"query": "검색",
}
}
},
"passage": {
"TITLE": {
"passage_type": "classic",
"passage_option": "mspcnt=1;rmtag=on;",
"max_length": 400
},
"TITLE+BODY": {
"passage_type": "classic",
"passage_option": "mspcnt=1;rmtag=on;",
"max_length": 500
}
}
}
```
### aggregate
요약 검색을 위한 필드입니다. 검색된 문서의 지정한 속성값을 연산하여 기준 속성별로 연산 결과를 표시합니다. 입력 형식은 다음과 같습니다.
```
{
"aggregate": {
"[docprop_name]": {
"max": (string),
"min": (string),
"one": (string),
"sum": (string)
}
}
}
```
- `[docprop_name]`: 요약 검색의 기준이 되는 문서 속성 지정
- `max`: 요약 검색의 max 연산 대상 지정
- `min`: 요약 검색의 min 연산 대상 지정
- `one`: 요약 검색의 one 연산 대상 지정
- `sum`: 요약 검색의 sum 연산 대상 지정
- '_1' 키워드 사용시에는 요약된 결과의 수를 구합니다.
<예시> [Cloud Search 예제](/docs/cloudsearch-download)에서 차량 타입(`dp_type`)별 차량 수 및 가격(`dp_price`)의 최솟값 검색
```
{
"aggregate": {
"dp_type": {
"sum": "_1",
"min": "dp_price"
}
}
}
```
<예시>
```
{
"search": {
"body_sgmt": {
"main": {
"query": "검색",
}
}
},
"aggregate": {
"dp_like_cnt": {
"max": ["dp_like_cnt", "dp_dislike_cnt"],
"min": ["dp_like_cnt", "dp_disklike_cnt"],
"one": "dp_like_cnt",
"sum": "_1"
}
}
}
```
### ranking
랭킹을 지정하는 필드입니다. 등록된 랭킹 모듈 이름을 입력하거나 랭킹 코드를 직접 입력합니다. 입력 형식은 다음과 같습니다.
```
{
"ranking": {
"name": (string),
"code": (string),
"override_value": {
"[ranking_value]" : (string|int|float)
}
}
}
```
<예시> 등록된 랭킹 모듈(clous)을 선택하여 검색
```
{
"search": {
"body_sgmt": {
"main": {
"query": "검색",
}
}
},
"ranking": {
"name": "clous"
}
}
```
<예시> 랭킹 코드를 직접 입력하여 검색
```
{
"search": {
"body_sgmt": {
"main": {
"query": "검색",
}
}
},
"ranking": {
"code": "overridable quality = 0.5; _relevance = 0.3 * qds + 0.7 * quality;",
"override_value": {
"quality": 1.0
}
}
}
```
### result_processing
검색 결과의 후처리를 설정하는 필드입니다. 입력 형식은 다음과 같습니다.
```
{
"result_processing": {
"[section_name]": {
"[result_processing_method]": (string|bool)
}
}
}
```
- `[section_name]`: 섹션 지정
- `[result_processing_method]`: 후처리 방식 지정
- `remove_duplicate`: passage 중복 제거
<예시>
```
{
"search": {
"body_sgmt": {
"main": {
"query": "검색",
}
}
},
"result_processing": {
"BODY": {
"remove_duplicate": true
}
}
}
```
### setting
검색 시 기타 환경 설정을 할 수 있습니다. 입력 형식은 다음과 같습니다.
```
{
"setting": {
"search_timeout": (string|int),
"ranking_value": (string|bool),
"reuse_term_extractor": (string|bool),
"log_level": (string|list),
}
}
```
- `search_timeout`: 검색 요청의 타임아웃 값 지정
- `ranking_value`: 결과에 랭킹 변수 값 노출 여부 지정
- `reuse_term_extractor`: `search` 필드의 `term_extractor` 옵션에서 생성한 텀 분석기를 서버에 저장할지 여부 지정(기본값: `false`)
- `true`: `term_extractor` 옵션을 통해 런타임에 만든 텀 분석기를 다음 요청에도 사용할 수 있도록 서버에 저장합니다.(총 50개까지 저장)
- `false`: `term_extractor` 옵션을 통해 런타임에 만든 텀 분석기를 한 번 사용 후 버립니다.
- 해당 옵션은 검색 결과에 영향을 주지 않으며, 성능에 영향을 줍니다.
- `term_extractor` 옵션을 사용해서 검색 쿼리를 작성할 예정이라면 실제 트래픽을 받기 전에 옵션을 반드시 활성화해 주십시오.
- 테스트 시에는 텀 분석기의 수가 최대 숫자(50개)를 넘을 수 있기 때문에 옵션을 비활성화하고 테스트하는 것을 권장합니다.
<예시>
```
{
"setting": {
"search_timeout": 30,
"ranking_value": true,
"reuse_term_extractor": true
}
}
```
## URI에 입력
검색 쿼리를 URL에 입력하여 API를 호출합니다.
- JSONPath 형태의 쿼리 문자열 파라미터 형식으로 입력합니다.
- 메소드는 HTTP GET을 선택합니다.
- Request Body의 형식을 그대로 적용하여 사용할 수 있습니다.
참고
여기에서는 검색 쿼리를 URI에 입력할 경우 입력 형식과 예시를 안내합니다. 각 필드 및 설정값에 대한 자세한 설명은 [요청 바디에 입력](/docs/cloudsearch-searchquery#%EC%9A%94%EC%B2%AD%EB%B0%94%EB%94%94%EC%97%90%EC%9E%85%EB%A0%A5) 하위 내용을 참조해 주십시오.
### start
표시할 검색 결과의 시작 랭킹을 선택합니다. 기본값은 1이며, 입력 형식은 다음과 같습니다.
```
?start=(string)
```
<예시>
```
?start=1
```
### display
표시할 검색 결과의 개수를 선택합니다. 기본값은 20이며, 입력 형식은 다음과 같습니다.
```
?display=(string)
```
<예시>
```
?display=20
```
### result_format
검색 결과의 형식을 지정합니다. 기본값은 json이며, 입력 형식은 다음과 같습니다.
```
?result_format=(string)
```
<예시>
```
?result_format=json
```
### search
검색을 위한 파라미터로, 필수 파라미터입니다. 입력 형식은 다음과 같습니다.
```
?search.[index_name].[query_method].query=(string)
?search.[index_name].[query_method].type=(string)
?search.[index_name].[query_method].option=(string)
?search.[index_name].[query_method].ratio=(string)
?search.[index_name].[query_method].term_extractor=(string)
```
<예시>
```
?search.body_sgmt.main.query=검색&search.body_sgmt.main.type=nterm&search.body_sgmt.main.option=and
```
### sort
검색 결과 정렬 기준을 설정하는 파라미터입니다. 입력 형식은 다음과 같습니다.
```
?sort.[sort_target]=[sort_option]
```
<예시>
```
?sort.relevance=desc
```
### scope
검색 대상 및 결과를 제한하는 제한 검색을 위한 파라미터입니다. 입력 형식은 다음과 같습니다.
```
?scope.[scope_target].[scope_method]=(string)
```
<예시>
```
?scope.dp_grade.exist=1
?scope.dp_pubdate.range=180403,180410
?scope.dp_price.gte=777
```
### key_scope
문서의 key(메인 섹션)를 기준으로 검색 대상 및 결과를 제한하는 key 제한 검색을 위한 파라미터입니다. 입력 형식은 다음과 같습니다.
```
?key_scope.[key_scope_method]=(string)
```
<예시>
```
?key_scope.exist=gdid_000000001
?key_scope.nexist=gdid_00000010
```
### user_scope
사용자가 직접 scope 수식을 입력하여 제한 검색을 할 수 있습니다. 입력 형식은 다음과 같습니다.
```
?user_scope=(string)
```
<예시>
```
?user_scope=(dp_price > 400)
?user_scope=(dp_price >= 400) and (dp_price < 1000)
?user_scope=(dp_grade == 1) and (dp_grade == 2)
```
### highlighting
검색 질의에 대해 구문 강조 설정을 하기 위한 파라미터입니다. 입력 형식은 다음과 같습니다.
```
?highlighting.enable=(string)
?highlighting.pre_tag=(string)
?highlighting.post_tag=(string)
?highlighting.[highlighting_option]=(string)
```
<예시>
```
?highlighting.enable=true
?highlighting.pre_tag=&highlighting.post_tag=
?highlighting.bold_sub_digit=true
```
### display_section
검색 결과에 표시할 섹션과 표시 방식을 지정하는 파라미터입니다.
- 해당 파라미터를 지정하지 않으면 전체 섹션의 결과를 표시합니다.
- 섹션을 지정하면 선택한 섹션의 정보만 표시합니다.
입력 형식은 다음과 같습니다.
```
?display_section=(string)
```
<예시>
```
?display_section=BODY:TITLE
```
### passage
검색 결과를 추출하는 방식을 지정하는 파라미터입니다.
- 해당 파라미터를 지정하지 않으면, 전체 섹션의 결과를 읽습니다.
- 섹션을 지정하면, 선택한 섹션의 결과만 읽습니다.
입력 형식은 다음과 같습니다.
```
?passage.[section_name].passage_type=(string)
?passage.[section_name].passage_option=(string)
?passage.[section_name].max_length=(string)
```
<예시>
```
?passage.BODY.passage_type=classic
?passage.BODY.passage_option=mspcnt=1;rmtag=on;
?passage.BODY.max_length=400
```
### aggregate
요약 검색을 위한 파라미터입니다. 검색된 문서의 지정한 필드를 지정한 연산으로 수행한 결과를 표시합니다. 입력 형식은 다음과 같습니다.
```
?aggregate.[docprop_name].max=(string)
?aggregate.[docprop_name].min=(string)
?aggregate.[docprop_name].one=(string)
?aggregate.[docprop_name].sum=(string)
```
<예시>
```
?aggregate.dp_like_cnt.max=dp_like_cnt,dp_dislike_cnt
?aggregate.dp_like_cnt.min=dp_like_cnt,dp_type
?aggregate.dp_like_cnt.sum=_1
```
### ranking
랭킹을 지정하는 파라미터입니다. 등록된 랭킹 모듈 이름을 입력하거나 랭킹 코드를 직접 입력합니다. 입력 형식은 다음과 같습니다.
```
?ranking.name=(string)
?ranking.code=(string)
?ranking.override_value.[ranking_value]=(string)
```
<예시>
```
?ranking.name=clous
?ranking.code=relevance = qds * 0.1;
?ranking.override_value.[ranking_value]=10.123
```
### result_processing
검색 결과의 후처리를 지정하는 파라미터입니다. 입력 형식은 다음과 같습니다.
```
?result_processing.[section_name].[result_processing_method]=(string)
```
<예시>
```
?result_processing.TITLE.remove_duplicate=true
```
### setting
검색 시 기타 환경 설정을 할 수 있습니다. 입력 형식은 다음과 같습니다.
```
?setting.transfer_timeout=(string)
?setting.search_timeout=(string)
?setting.use_df=(string)
?setting.reuse_term_extractor=(string)
```
<예시>
```
?setting.transfer_timeout=30
?setting.search_timeout=30
?setting.use_df=true
?setting.reuse_term_extractor=true
```