---
title: "Document 검색 "
slug: "analytics-cloudsearch-searchdocument"
tags: ["Cloud Search"]
updated: 2026-10-22T10:46:51Z
published: 2026-10-22T10:46:51Z
canonical: "api-gov.ncloud-docs.com/analytics-cloudsearch-searchdocument"
---
> ## Documentation Index
> Fetch the complete documentation index at: https://api-gov.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Document 검색
색인별로 생성한 문서에 대해 검색을 수행합니다. 해당 요청을 수행하기 이전에 [Domain 생성](/docs/analytics-cloudsearch-createdomain/) 및 [Document 생성](/docs/analytics-cloudsearch-managedocument)이 되어져 있어야 합니다.
- 검색 서비스 구성을 위해서는 검색 기본 지식이 필요합니다.
- 서비스 생성 시 설정한 [Schema](/docs/common-apidatatype-csschema)로 검색 수행
- JSON 형태의 queryDSL 사용
```
POST https://cloudsearch.apigw.gov-ntruss.com/CloudSearch/real/v1/domain/{name}/document/search
```
## 요청
### 요청 파라미터
| 파라미터 명 | 필수 여부 | 타입 | 제약사항 | 설명 |
| --- | --- | --- | --- | --- |
| name | Yes | string | | 생성되어져 있는 Domain 이름 |
### overview
Search Query에 대한 자세한 예제는 [Cloud Search 사용가이드 - Search Query 사용 가이드](https://guide-gov.ncloud-docs.com/docs/cloudsearch-searchquery) 참고 바람
```
{
"search": {
"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),
"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),
}
},
"ip_str": (string)
}
```
### 요청 바디
| 필드명 | 필수 여부 | 타입 | 제약사항 | 설명 |
| --- | --- | --- | --- | --- |
| start | No | String, Integer | default : 1 | 검색 결과의 시작 랭킹 |
| display | No | String, Integer | default : 20 | 검색 결과의 개수 |
| result_format | No | String | json | 검색 결과 포맷 지정, 현재는 json 포맷만 지원 |
| index_name | Yes | String | 기존에 생성된 색인 중 선택 | 검색 할 색인의 이름 |
| queryList | Yes | List<[SearchQuery](/docs/common-apidatatype-cssearchquery)> | SearchQuery.query_method가 "main"인 SearchQuery를 반드시 포함 | 검색 요청 쿼리 |
| sort | No | Object | | 검색 결과 정렬 기준을 가지는 Map 형태의 Objectkey : 정렬 기준 섹션value : 정렬 방식 지정(desc, asc) |
| scope | No | List<[SearchScope](/docs/common-apidatatype-cssearchscope)> | | 제한 검색 설정 목록 |
| key_scope | No | Object | | 제한 검색을 설정하는 Map 형태의 Objectkey : 제한 검색 방식 선택value : 제한 검색 방식에 따른 값 설정key 옵션 종류 - exist, nexist: 지정한 값이 존재하는 문서 속성으로 검색 결과를 제한함 |
| user_scope | No | String | 랭킹 코드 형태의 수식 | 사용자가 직접 scope 수식을 입력, 입력된 수식은 'scope' 파라미터의 내용과 and 조건으로 추가됨ex) price가 2000 초과 5000 미인 문서를 찾을 때,"(dp_price > '2000') and (dp_price < '5000')" |
| highlighting | No | [SearchHighlighting](/docs/common-apidatatype-cssearchhighlighting) | Default: true | 검색 결과 구문 강조 설정 |
| display_section | No | String, Array | 기존에 생성한 섹션 중 선택 | 검색 결과로 보여줄 섹션을 지정(지정하지 않으면 모든 섹션 데이터 출력) 예 : 가격과 이름만 결과로 출력하고 싶을 때, "price, name"여러 섹션 조합 가능 예 : 브랜드와 이름을 하나의 결과로 출력하고 싶을 때, "brand+name" |
| passage | No | List<[SearchPassage](/docs/common-apidatatype-cssearchpassage)> | | 검색 결과 추출 방식 설정 |
| aggregate | No | List<[SearchAggregate](/docs/common-apidatatype-cssearchaggregate)> | | 검색 결과 요약 설정 목록 |
| result_processing | No | [SearchResultProcessing](/docs/common-apidatatype-cssearchresultprocessing) | | 검색 결과 후처리 설정 |
| setting | No | [SearchSetting](/docs/common-apidatatype-cssearchsetting) | | 검색 시 기타 환경 설정 |
| ip_str | No | String | | IP type format 이여야 함 예 : 10.78.140.200 |
## 응답
| 필드명 | 타입 | 설명 | 비고 |
| --- | --- | --- | --- |
| type | string | 응답 타입 | |
| version | string | | |
| status | number | 응답 상태 | |
| message | string | 에러 메세지 | 응답 결과가 에러일 경우 출력 |
| time_zone | string | 타임존 | |
| elapsed_time | number | 검색 시 걸린 시간 | |
| term | object | 질의 내용 | index_name 및 [SearchQuery](/docs/common-apidatatype-cssearchquery)의 내용이 mapping 된 object |
| result | object | 검색 결과 | |
| result.start | number | 검색 결과의 시작 랭킹 | default : 1 |
| result.display | number | 검색 결과의 개수 | default : 20 |
| result.ranking | string | 랭킹 방식 | "clous" |
| result.sort_by | string | 랭킹 기준 | default : "qds" |
| result.total_count | number | 총 검색 결과 | |
| result.removed_count | number | 삭제된 검색 결과 | |
| result.item_count | number | 검색 결과 갯수 | |
| result.items | Array | 검색된 문서 | [Document 생성](/docs/analytics-cloudsearch-managedocument)시 작성한 request[].content 데이터와 검색 정보를 포함하는 list |
| result.items[]._rank | number | 검색 랭킹 | |
| result.items[]._key | string | 문서의 primary key | |
| result.items[]._qds | number | 검색 query와 해당 문서의 일치 정도 | |
### 응답 Status
| HTTP Status | Desc |
| --- | --- |
| 200 | OK(검색 완료) |
| 200 | No collection founded, insert document please |
| 400 | Bad Request |
| 401 | Unauthorized |
| 401 | there is no such service |
| 403 | Forbidden |
| 404 | Not Found |
| 500 | Internal Server Error |
## 요청 예시
예시에서 사용되는 문서는, [검색 서비스 생성 예제](/docs/analytics-cloudsearch#%EA%B2%80%EC%83%89%EC%84%9C%EB%B9%84%EC%8A%A4%EC%83%9D%EC%84%B1%EC%98%88%EC%A0%9C)와 동일합니다.
### 일반 검색 요청 예시(검색어 "현대")
```
POST https://cloudsearch.apigw.gov-ntruss.com/CloudSearch/real/v1/domain/car_dev/document/search
{
"search": {
"brand_name": {
"main": {
"query": "현대"
}
}
},
"ip_str": "10.78.140.200"
}
```
### 응답 예시
```
{
"version": "1.3.0",
"status": 200,
"type": "response",
"time_zone": "+09:00",
"elapsed_time": 0.000521,
"term": {
"brand_name": {
"main": {
"term_count": 1,
"term_list": [
"현대"
]
}
}
},
"result": {
"start": 1,
"display": 20,
"ranking": "clous",
"sort_by": "qds",
"total_count": 2,
"removed_count": 0,
"item_count": 2,
"items": [
{
"_rank": 1,
"_key": "car-10001",
"_qds": 0.8729686141014099,
"brand": "현대",
"docid": "car-10001",
"name": "2018 싼타페",
"price": 2815,
"type": "중형"
},
{
"_rank": 2,
"_key": "car-10002",
"_qds": 0.8729686141014099,
"brand": "현대",
"docid": "car-10002",
"name": "2018 그랜저",
"price": 2615,
"type": "중형"
}
]
}
}
```
### 불용어 검색 요청 예시(검색어 "현대와 쉐보레")
#### 불용어 예시(rule name: "josa")
```
{
"type": "filter",
"word_list": [
"은", "는", "이", "가", "을", "를", "의", "와"
]
}
```
검색어와 매칭되는 모든 단어를 찾기 위해서는 "or" option이 필요합니다.
```
POST https://cloudsearch.apigw.gov-ntruss.com/CloudSearch/real/v1/domain/car_dev/document/search
POST /CloudSearch/real/v1/domain/car_dev/document/manage HTTP/1.1
Host:cloudsearch.apigw.gov-ntruss.com
accept:application/json
x-ncp-apigw-signature-v2: cDwtHuQeGmwWyNmwlN6XIGA66zge4iMXvfoDQNna05g=
x-ncp-apigw-timestamp: 1545817618751
x-ncp-iam-access-key: teGTwtcSEGA7fu28BGGi
{
"search": {
"brand_name": {
"main": {
"query": "현대와 쉐보레",
"option":"or",
"stopword":"josa"
}
}
}
}
```
### 응답 예시
```
{
"version": "1.3.0",
"status": 200,
"type": "response",
"time_zone": "+09:00",
"elapsed_time": 0.000517,
"term": {
"brand_name": {
"main": {
"term_count": 2,
"term_list": [
"쉐보레",
"현대"
]
}
}
},
"result": {
"start": 1,
"display": 20,
"ranking": "clous",
"sort_by": "qds",
"total_count": 3,
"removed_count": 0,
"item_count": 3,
"items": [
{
"_rank": 1,
"_key": "car-10001",
"_qds": 0.8729686141014099,
"brand": "현대",
"docid": "car-10001",
"name": "2018 싼타페",
"price": 2815,
"type": "중형"
},
{
"_rank": 2,
"_key": "car-10002",
"_qds": 0.8729686141014099,
"brand": "현대",
"docid": "car-10002",
"name": "2018 그랜저",
"price": 2615,
"type": "중형"
},
{
"_rank": 3,
"_key": "car-3",
"_qds": 0.8707408308982849,
"brand": "쉐보레",
"docid": "car-3",
"name": "2018 말리부",
"price": 2388,
"type": "중형"
}
]
}
}
```