--- title: "Document 검색" slug: "analytics-cloudsearch-searchdocument" updated: 2026-04-23T08:56:09Z published: 2026-04-23T09:02:28Z canonical: "api.ncloud-docs.com/analytics-cloudsearch-searchdocument" --- > ## Documentation Index > Fetch the complete documentation index at: https://api.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 사용 ```http POST https://cloudsearch.apigw.ntruss.com/CloudSearch/real/v1/domain/{name}/document/search ``` ## 요청 ### 요청 파라미터 | 파라미터명 | 필수 여부 | 타입 | 제약 사항 | 설명 | |-------------|-----------|--------|----------|----------------------------------------| | name | Yes | string | | 생성되어져 있는 Domain 이름 | ### overview Search Query에 대한 자세한 예제는 [Cloud Search 사용가이드 - Search Query 사용 가이드](https://guide.ncloud-docs.com/docs/cloudsearch-overview){target="_blank"}를 참고하시기 바랍니다. ```JSON { "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 형태의 Object
  • key : 정렬 기준 섹션
  • value : 정렬 방식 지정(desc, asc)
    • | | scope | No | List<[SearchScope](/docs/common-apidatatype-cssearchscope)> | | 제한 검색 설정 목록| | key_scope | No | Object | | 제한 검색을 설정하는 Map 형태의 Object
  • key : 제한 검색 방식 선택
  • 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 및 [SearhchQuery](/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)와 동일합니다. ### 일반 검색 요청 예시(검색어 "현대") ```http POST https://cloudsearch.apigw.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.ntruss.com Content-Type: application/json x-ncp-apigw-signature-v2: cDwtHuQeGmwWyNmwlN6XIGA66zge4iMXvfoDQNna05g= x-ncp-apigw-timestamp: 1545817618751 x-ncp-iam-access-key: teGTwtcSEGA7fu28BGGi { "search": { "brand_name": { "main": { "query": "현대" } } }, "ip_str": "10.78.140.200" } ``` ### 응답 예시 ```json { "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") ```json { "type": "filter", "word_list": [ "은", "는", "이", "가", "을", "를", "의", "와" ] } ``` 검색어와 매칭되는 모든 단어를 찾기 위해서는 "or" option이 필요합니다. ```http POST https://cloudsearch.apigw.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.ntruss.com 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" } } } } ``` ### 응답 예시 ```json { "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": "중형" } ] } } ```