---
title: "Cloud Search 개요"
slug: "analytics-cloudsearch"
tags: ["Cloud Search", "overview"]
updated: 2026-04-23T08:56:09Z
published: 2026-04-23T09:02:33Z
canonical: "api.ncloud-docs.com/analytics-cloudsearch"
---
> ## 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.
# Cloud Search 개요
Cloud Search는 네이버 클라우드 플랫폼의 API Gateway를 통해 API를 제공합니다. API 인증을 위해서 Access Key, Secret Key가 필요하며, API Key 생성 및 사용방법은 [API Gateway 사용가이드 - API 호출하기](https://guide.ncloud-docs.com/docs/apigw-apigw-2-5)을 참고하시기 바랍니다. Access Key와 Secret Key에 관해서는 [공통 가이드 - API 개요](/docs/common-ncpapi)을 참고하시기 바랍니다.
Cloud Search는 다양한 API를 제공하고 있으며 Swagger 페이지를 통해서 API 스펙을 확인하고 간단한 테스트를 수행할 수 있습니다. Cloud Search의 Swagger 문서는 아래 과정을 통해서 접근할 수 있습니다.
1. 콘솔 접속
2. **Services** > **API Gateway** 서비스 선택
3. **Published APIs** > **CloudSearch** > **Catalog** 선택
4. CloudSearch 선택 후 하단의 API 설명서 선택
이때 노출되는 화면이 Cloud Search의 Swagger 페이지이며, 페이지 상단에 표시되는 링크인 `https://cloudsearch.apigw.ntruss.com/CloudSearch/real`이 Cloud Search의 API 주소입니다.
## 공통 설정
### Cloud Search API URL
```
https://cloudsearch.apigw.ntruss.com/CloudSearch/real
```
### 요청 헤더
| 헤더 명 | 설명 |
| --- | --- |
| x-ncp-apigw-timestamp | 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 **밀리초(Millisecond)로 나타내며 API Gateway 서버와 시간 차가 5분 이상 나는 경우 유효하지 않은 요청으로 간주** `x-ncp-apigw-timestamp:{Timestamp}` |
| x-ncp-iam-access-key | 네이버 클라우드 플랫폼 포털에서 발급받은 Access Key ID 값 `x-ncp-iam-access-key:{Sub Account Access Key}` |
| x-ncp-apigw-signature-v2 | Access Key ID 값과 Secret Key로 암호화한 서명 `x-ncp-apigw-signature-v2:{API Gateway Signature}` |
| Content-Type | Request body content type을 application/json으로 지정 `Content-Type: application/json` |
## 검색 서비스 생성 예제
본 예제에서는 세계 여러 자동차 모델의 정보를 제공하는 검색 포털 서비스를 만드는 것을 예제로 API 사용법을 설명하겠습니다. 도메인을 생성하기에 앞서, 도메인 생성 시 설정할 검색 설정(Schema)을 정의해보겠습니다.
## 검색 설정 생성
자동차 모델 각각은 아래의 정보를 가지고 있다고 가정하겠습니다. 검색 엔진에서는 검색의 대상을 나타내는 정보의 묶음을 **문서**라고 지칭합니다. 즉, 아래 정보의 묶음이 하나의 문서가 됩니다.
- docid : 개별 문서의 key가 되는 항목
- brand : 자동차 브랜드
- name : 자동차명
- price : 가격
- type : 차종
### 섹션
여기에서 각 항목을 Cloud Search에서는 **섹션**이라 부릅니다. 그리고, 그 중에 이 문서를 지칭할 수 있는 섹션, 즉 key가 되는 섹션을 **메인 섹션**이라 부릅니다. 예를 들면, 아래의 json은 하나의 문서이며, 이 문서의 key는 "car-10001"입니다.
```
{
"docid": "car-10001",
"brand": "현대",
"name": "2018 싼타페",
"price": "2815",
"type": "중형"
}
```
이와 같은 문서를 넣기 위해서는 docid, brand, name, price, type을 섹션으로 추가해야 합니다.
일반 문자열인 경우에는 섹션의 데이터 타입을 생략할 수 있으며, 그렇지 않은 경우에는 float, uint8, uint16, uint32, uint64, int8, int16, int32, int64, string, mstring, muint8, muint32 중의 하나로 지정해야 합니다.
각 섹션에는 다양한 특성을 부여할 수 있는데, price라는 섹션에 대해 dp_price라는 이름을 부여하면 [Document 검색](/docs/analytics-cloudsearch-searchdocument)의 부가적인 검색 기능에 활용할 수 있습니다.
```
{
"docProperties":[
{
"type":"uint32",
"name":"dp_price"
}
],
"name":"price"
}
```
### 색인
자동차를 검색할 때 브랜드명만을 이용해서 검색하는 경우가 있고 브랜드명, 자동차명, 차종을 통틀어서 검색하는 경우가 있습니다. 이와 같이 용도에 따라 검색하는 대상이 되는 섹션이나 검색의 특성을 달리해서 검색하고자 할 때에는 목적에 맞게 각각 색인을 생성해야 합니다. 특별히 이런 구분을 하고 싶지 않다면 모든 섹션을 넣어서 색인을 만들면 됩니다.
아래의 예제는 brand와 name 섹션을 위한 brand_name이라는 색인을 생성합니다.
색인 생성 시 다양한 언어의 형태소 분석기를 설정할 수 있습니다. 본 예제에서는 brand_name 색인에 대해 한글로 형태소 분석기를 지정합니다. 다른 언어의 형태소 분석 지원 여부는 [형태소 분석 옵션 조회 - 가능한 언어 목록](/docs/analytics-cloudsearch-gettokenizerlist) 통해 확인이 가능합니다.
아래와 같이 섹션과 색인을 정의한 검색 설정, 즉 [Schema](/docs/common-apidatatype-csschema)를 [Schema 검증](/docs/analytics-cloudsearch-checkschemavalidator) 요청에 보내면 정상 여부를 알 수 있습니다.
```
{
"document":{
"primarySectionName":"docid",
"sections":[
{
"name":"docid"
},
{
"name":"brand"
},
{
"name":"name"
},
{
"docProperties":[
{
"type":"uint32",
"name":"dp_price"
}
],
"name":"price"
},
{
"docProperties":[
{
"type":"string",
"name":"dp_type"
}
],
"name":"type"
}
],
"indexes":[
{
"documentTermWeight":"sum_wgt",
"buildInfos":[
{
"indexProcessors":[
{
"type":"hanaterm",
"method":"sgmt",
"option":"+korea +josacat +eomicat"
}
],
"sectionTermWeight":"1.0 * stw_2p(tf, 0.5, 0.25, 0., length / 128.0)",
"sections":[
"brand",
"name"
],
"name":"index_build"
}
],
"name":"brand_name"
}
]
}
}
```
아래와 같이 valid라는 응답이 오지 않는다면 Schema를 수정해야 합니다.
```
{
"status": "valid",
"message": "OK",
"response": "{\"status\":{\"code\":0,\"message\":\"ok\"}}\n"
}
```
위 요청에서 valid라는 응답을 받았다면, [Domain 생성](/docs/analytics-cloudsearch-createdomain) 요청 시 작성한 검색 설정을 설정해야 합니다.
## 도메인 생성
아직 포털 서비스를 개발하는 중이므로 car_dev라는 도메인을 생성하겠습니다. Cloud Search 사용자는 추후 stage, production 환경을 구축할 때에는 car_stage, car_production이라는 도메인을 생성하여 환경을 구분한다면 개발, 테스트, 운영이 용이할 것입니다. Cloud Search에서는 이와 같이 **도메인**이라는 개념을 이용하여 환경을 구분하고 있습니다.
위에서 사용한 검색 설정과 [Domain 생성](/docs/analytics-cloudsearch-createdomain) API를 참고하여 아래 예시와 같이 json으로 parameter를 정의하여 POST로 /v1/domain를 호출하면 car_dev라는 도메인이 생성됩니다.
```
{
"name": "car_dev",
"type": "small",
"indexerCount": 1,
"searcherCount": 1,
"description": "search engine for cars",
"schema":{
"document":{
"primarySectionName":"docid",
"sections":[
{
"name":"docid"
},
{
"name":"brand"
},
{
"name":"name"
},
{
"docProperties":[
{
"type":"uint32",
"name":"dp_price"
}
],
"name":"price"
},
{
"docProperties":[
{
"type":"string",
"name":"dp_type"
}
],
"name":"type"
}
],
"indexes":[
{
"documentTermWeight":"sum_wgt",
"buildInfos":[
{
"indexProcessors":[
{
"type":"hanaterm",
"method":"sgmt",
"option":"+english +revert +korea +josacat +eomicat"
}
],
"sectionTermWeight":"1.0 * stw_2p(tf, 0.5, 0.25, 0., length / 128.0)",
"sections":[
"brand",
"name"
],
"name":"index_build"
}
],
"name":"brand_name"
}
]
}
}
}
```
## 도메인 조회
도메인이 생성된 것을 확인하기 위해 [Domain 조회](/docs/analytics-cloudsearch-getdomain) API를 호출하면 아래와 같은 응답을 받을 수 있습니다. 이미 생성된 다른 도메인이 있다면 여러 개의 도메인에 대한 응답을 받습니다.
```
{
"name": "car_dev",
"description": "search engine for cars",
"domainStatus": "RUNNING",
"containerChangeable": "ENABLE",
"schemaChangeable": "ENABLE",
"autoCompleteChangeable": "ENABLE",
"type": "small",
"indexerCount": 1,
"searcherCount": 1,
"schema": {
"document": {
"primarySectionName": "docid",
"sections": [
{
"name": "docid"
},
{
"name": "brand"
},
{
"name": "name"
},
{
"docProperties": [
{
"type": "uint32",
"name": "dp_price"
}
],
"name": "price"
},
{
"docProperties": [
{
"type": "string",
"name": "dp_type"
}
],
"name": "type"
}
],
"indexes": [
{
"documentTermWeight": "sum_wgt",
"buildInfos": [
{
"indexProcessors": [
{
"type": "hanaterm",
"method": "sgmt",
"option": "+english +revert +korea +josacat +eomicat"
}
],
"sectionTermWeight": "1.0 * stw_2p(tf, 0.5, 0.25, 0., length / 128.0)",
"sections": [
"brand",
"name"
],
"name": "index_build"
}
],
"name": "brand_name"
}
]
}
},
"autocompleteSchema": null,
"createdDate": "2019-03-05T08:15:11.587Z",
"updatedDate": "2019-03-05T08:15:18.000Z"
}
```
## 문서 업로드
새로 생성한 도메인 car_dev에 문서를 추가하겠습니다. [예제 파일 다운로드](https://cdn.document360.io/da0368a0-4444-4862-a528-42f78876f9e6/Images/Documentation/cloudsearch-ex.json)를 참고하시기 바랍니다. 문서는 필요에 따라 insert, update, upsert, delete할 수 있으며 자세한 사용법은 [Document 관리](/docs/analytics-cloudsearch-managedocument)를 참고하시기 바랍니다. 하나의 요청으로 여러 개의 문서를 추가할 수 있으며, insert, update, upsert, delete 요청을 조합하여 한꺼번에 여러 가지 요청을 보낼 수도 있습니다.
[Document 관리](/docs/analytics-cloudsearch-managedocument)에 요청을 보내서 문서를 insert, update, upsert, delete할 수 있습니다.
다음은 3개의 문서를 추가하기 위한 요청입니다. car_dev 도메인에 추가할 것이므로 /v1/domain/car_dev/document/manage를 호출하면 됩니다.
```
{
"requests": [
{
"type": "insert",
"key": "car-10001",
"content": {
"docid": "car-10001",
"brand": "현대",
"name": "2018 싼타페",
"price": "2815",
"type": "중형"
}
},
{
"type": "insert",
"key": "car-10002",
"content": {
"docid": "car-10002",
"brand": "현대",
"name": "2018 그랜저",
"price": "2615",
"type": "중형"
}
},
{
"type": "insert",
"key": "car-3",
"content": {
"docid": "car-3",
"brand": "쉐보레",
"name": "2018 말리부",
"price": "2388",
"type": "중형"
}
}
]
}
```
## 검색
이제 car_dev에 추가된 문서를 검색할 수 있습니다. 검색 API에 대한 상세한 설명은 [Document 검색](/docs/analytics-cloudsearch-searchdocument)을 참고하시기 바랍니다.
간단히 brand명으로 검색을 해보겠습니다. 아래와 같이 요청을 만든 후 POST로 /v1/domain/car_dev/document/search를 호출하면 됩니다.
```
{
"search": {
"brand_name": {
"main": {
"query": "현대"
}
}
}
}
```
아래와 같은 결과를 얻을 수 있습니다.
```
{
"type": "response",
"version": "1.1.3",
"status": 200,
"time_zone": "+09:00",
"elapsed_time": 0.000787,
"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": "중형"
}
]
}
}
```
이에 추가적으로 [자동 완성 설정](/docs/analytics-cloudsearch-putautocomplete) 및 [불용어 정책 설정](/docs/analytics-cloudsearch-poststopword)을 지원합니다. 자세한 설명은 해당 페이지를 참조해 주십시오.