---
title: "Search documents"
slug: "analytics-cloudsearch-searchdocument"
updated: 2026-09-17T09:48:05Z
published: 2026-09-17T09:48:05Z
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.
# Search documents
**We are preparing a localization service for the content. We will do our best to provide the localization service as soon as possible.**
Searches documents created for each index. You need to create a [domain](/docs/en/analytics-cloudsearch-createdomain) and [document](/docs/en/analytics-cloudsearch-managedocument) first to use this operation.
- You need basic knowledge in search in order to configure a search service.
- You can perform searches with the [Schema](/docs/en/common-apidatatype-csschema) set when creating your service.
- Use queryDSL in JSON.
```
POST https://cloudsearch.apigw.ntruss.com/CloudSearch/real/v1/domain/{name}/document/search
```
## Request
### Request Parameters
| Parameter | Required | Type | Limitations | Description |
| --- | --- | --- | --- | --- |
| name | Y | string | | Domain name |
### Overview
For examples regarding Search Query, refer to [How to Use Cloud Search - Search Query Manual](https://guide.ncloud-docs.com/docs/cloudsearch-overview).
```
{
"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),
}
}
```
### Request Body
| Field | Required | Type | Limitations | Description |
| --- | --- | --- | --- | --- |
| start | N | String, Integer | Default: 1 | Start ranking of search results |
| display | N | String, Integer | Default: 20 | Number of search results |
| result_format | N | String | JSON | Search result format. Currently, only JSON format is available. |
| index_name | Y | String | Select one of the indexes previously created. | Name of the index to search |
| queryList | Y | List<[SearchQuery](/docs/en/common-apidatatype-cssearchquery)> | The SearchQuery for which SearchQuery.query_method is "main" must be included. | Search request query |
| sort | N | Object | | Map type object which has a sorting order of search resultskey: Section to sort results byvalue: Sorting method (desc, asc) |
| scope | N | List<[SearchScope](/docs/en/common-apidatatype-cssearchscope)> | | List of limited search settings |
| key_scope | N | Object | | Map type object to set limited searcheskey: Limited search methodvalue: Value that matches the limited search methodkey option type - exist, nexist: It limits search results to document properties where the specified values exist. |
| user_scope | N | String | Scope expression in the ranking code form | This parameter is used for users to directly specify a scope expression, which is added with the “scope” parameter by using the “and” condition. Example) If you search for documents for which the price is over 2000 and under 5000: "(dp_price > '2000') and (dp_price < '5000')" |
| highlighting | N | [SearchHighlighting](/docs/en/common-apidatatype-cssearchhighlighting) | Default: true | Syntax highlighting in search results |
| display_section | N | String, Array | Select sections from those previously created. | Specify sections to show as search results. (If it is not specified, data of all sections will be displayed) Example: If you want to display the price and name sections only, "price, name"You can combine multiple sections. Example: If you want to display the brand and name as one result, "brand+name" |
| passage | N | List<[SearchPassage](/docs/en/common-apidatatype-cssearchpassage)> | | Extraction method of search results |
| aggregate | N | List<[SearchAggregate](/docs/en/common-apidatatype-cssearchaggregate)> | | List of aggregate search result settings |
| result_processing | N | [SearchResultProcessing](/docs/en/common-apidatatype-cssearchresultprocessing) | | Post-processing of search results |
| setting | N | [SearchSetting](/docs/en/common-apidatatype-cssearchsetting) | | Other preferences for search |
## Response
| Field | Type | Description | Note |
| --- | --- | --- | --- |
| type | string | Response type | |
| version | string | | |
| status | number | Response status | |
| message | string | Error message | It is displayed when the response result is an error. |
| time_zone | string | Timezone | |
| elapsed_time | number | Time taken for search | |
| term | object | Query contents | Object in which index_name and [SearhchQuery](/docs/en/common-apidatatype-cssearchquery) are mapped. |
| result | object | Search result | |
| result.start | number | Start ranking of search results | Default: 1 |
| result.display | number | Number of search results | Default: 20 |
| result.ranking | string | Ranking method | "clous" |
| result.sort_by | string | Sort by | Default: "qds" |
| result.total_count | number | Total number of search results | |
| result.removed_count | number | Number of removed search results | |
| result.item_count | number | Number of search results | |
| result.items | Array | Searched documents | List containing request[].content data created when you [create a document](/docs/en/analytics-cloudsearch-managedocument), and search information |
| result.items[]._rank | number | Search ranking | |
| result.items[]._key | string | Document’s primary key | |
| result.items[]._qds | number | Indicates how well the search query and the document match. | |
### Response status
| HTTP status | Description |
| --- | --- |
| 200 | OK (Successfully completed) |
| 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 |
## Request Example
The following example uses the same document as [Example of creating a search service](/docs/en/analytics-cloudsearch-index).
### Example of general search (search term: "Hyundai")
```
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
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": "Hyundai"
}
}
}
}
```
### Example Response
```
{
"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": [
"Hyundai"
]
}
}
},
"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": "Hyundai",
"docid": "car-10001",
"name": "2018 Santa Fe",
"price": 2815,
"type": "Medium"
},
{
"_rank": 2,
"_key": "car-10002",
"_qds": 0.8729686141014099,
"brand": "Hyundai",
"docid": "car-10002",
"name": "2018 Grandeur",
"price": 2615,
"type": "Medium"
}
]
}
}
```
### Example of stop word search (search term: "Hyundai and Chevrolet")
#### Example of stop words (rule name: "josa")
```
{
"type": "filter",
"word_list": [
"The", "this", "end", "of", "To", "of", "with"
]
}
```
The "or" option is needed to search all words that match the search term.
```
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
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": "Hyundai and Chevrolet",
"option":"or",
"stopword":"josa"
}
}
}
}
```
### Example Response
```
{
"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": [
"Chevrolet",
"Hyundai"
]
}
}
},
"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": "Hyundai",
"docid": "car-10001",
"name": "2018 Santa Fe",
"price": 2815,
"type": "Medium"
},
{
"_rank": 2,
"_key": "car-10002",
"_qds": 0.8729686141014099,
"brand": "Hyundai",
"docid": "car-10002",
"name": "2018 Grandeur",
"price": 2615,
"type": "Medium"
},
{
"_rank": 3,
"_key": "car-3",
"_qds": 0.8707408308982849,
"brand": "Chevrolet",
"docid": "car-3",
"name": "2018 Malibu",
"price": 2388,
"type": "Medium"
}
]
}
}
```