---
title: "Document検索"
slug: "analytics-cloudsearch-searchdocument"
updated: 2026-09-17T09:57:26Z
published: 2026-09-17T09:57:26Z
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検索

インデックス別に作成したDocumentに対して検索を実行します。 該当リクエストを実行する前に[Domain作成](/docs/ja/analytics-cloudsearch-createdomain)及び[Document作成](/docs/ja/analytics-cloudsearch-managedocument)が必要です。

- 検索サービス構成のためには検索基本知識が必要です。
- サービスを作成する時に設定した[Schema](/docs/ja/common-apidatatype-csschema)で検索実行
- JSON形式のqueryDSLを使用

```
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)をご参考ください。

```
{
  "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 | 検索結果の開始Ranking |
| display | No | String, Integer | default : 20 | 検索結果の個数 |
| result_format | No | String | json | 検索結果のフォーマット指定、現在はjsonフォーマットのみサポートします。 |
| index_name | Yes | String | 既存作成されたインデックス の中で選択 | 検索するインデックス名 |
| queryList | Yes | List<[SearchQuery](/docs/ja/common-apidatatype-cssearchquery)> | SearchQuery.query_methodが"main"であるSearchQueryを必ず含む | 検索リクエストクエリ |
| sort | No | Object |  | 検索結果のソート基準を持つMap形式のObjectkey : ソート基準セクションvalue : ソート方式指定(desc, asc) |
| scope | No | List<[SearchScope](/docs/ja/common-apidatatype-cssearchscope)> |  | 制限検索設定リスト |
| key_scope | No | Object |  | 制限検索を設定するMap形式のObjectkey : 制限検索方式選択value : 制限検索方式による値設定keyオプション種類 - exist, nexist: 指定した値が存在するDocument属性で検索結果を制限します。 |
| user_scope | No | String | Rankingコード形式の数式 | ユーザが直接scope数式を入力、入力された数式は'scope'パラメータの内容とand条件で追加されます。ex) priceが 2000超過、5000未満であるDocumentを探す場合、"(dp_price > '2000') and (dp_price < '5000')" |
| highlighting | No | [SearchHighlighting](/docs/ja/common-apidatatype-cssearchhighlighting) | Default: true | 検索結果構文強調設定 |
| display_section | No | String, Array | 既存作成したセクションの中で選択 | 検索結果として見せるセクションを指定(指定しない場合、すべてのセクションデータ出力) 例 : 価格と名称のみを結果として出力したい場合、 "price, name"多くのセクションの組み合わせ可能 例 : ブランドと名称を一つの結果として出力したい場合、 "brand+name" |
| passage | No | List<[SearchPassage](/docs/ja/common-apidatatype-cssearchpassage)> |  | 検索結果抽出方式設定 |
| aggregate | No | List<[SearchAggregate](/docs/ja/common-apidatatype-cssearchaggregate)> |  | 検索結果要約設定リスト |
| result_processing | No | [SearchResultProcessing](/docs/ja/common-apidatatype-cssearchresultprocessing) |  | 検索結果の後処理設定 |
| setting | No | [SearchSetting](/docs/ja/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/ja/common-apidatatype-cssearchquery)の内容がmappingされたobject |
| result | object | 検索結果 |  |
| result.start | number | 検索結果の開始Ranking | default : 1 |
| result.display | number | 検索結果の個数 | default : 20 |
| result.ranking | string | Ranking方式 | "clous" |
| result.sort_by | string | Ranking基準 | default : "qds" |
| result.total_count | number | 全体検索結果 |  |
| result.removed_count | number | 削除された検索結果 |  |
| result.item_count | number | 検索結果数 |  |
| result.items | Array | 検索されたDocument | [Document作成](/docs/ja/analytics-cloudsearch-managedocument)時に作成したrequest[].contentデータと検索情報を含むlist |
| result.items[]._rank | number | 検索Ranking |  |
| result.items[]._key | string | Documentのprimary key |  |
| result.items[]._qds | number | 検索queryと該当Documentの一致程度 |  |

### レスポンス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 |

## リクエスト例示

例示で使われるDocumentは[検索サービス作成例題](/docs/ja/analytics-cloudsearch)と同じです。

### 一般検索リクエスト例示(検索語"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"
      }
    }
  },
  "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": [
          "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": "<b>Hyundai</b>",
        "docid": "car-10001",
        "name": "2018 Santafe",
        "price": 2815,
        "type": "中型"
      },
      {
        "_rank": 2,
        "_key": "car-10002",
        "_qds": 0.8729686141014099,
        "brand": "<b>Hyundai</b>",
        "docid": "car-10002",
        "name": "2018 Grandure",
        "price": 2615,
        "type": "中型"
      }
    ]
  }
}
```

### ストップワード検索 リクエスト例示(検索語"Hyundaiとchevrolet")

#### ストップワード例示(rule name: "josa")

```
{
  "type": "filter",
  "word_list": [
    "은", "는", "이", "가", "을", "를", "의", "와"
    
   // 上記の文字は韓国語の助詞と接続詞であり、その意味は以下のようである。
   // 은(は), 는(は), 이(が), 가(が), 을(を), 를(を), 의(の), 와(と)
   // もし、日本語の助詞と接続詞を活用するのであれば、上記の内容を以下の内容に入れ替えれば活用可能
   // "は", "が", "を", "の", "と"
      
  ]
}
```

検索語とマッチングされるすべての単語を探すためには "or" optionが必要です。

```
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とchevrolet",
        "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": [
          "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": "<b>Hyundai</b>",
        "docid": "car-10001",
        "name": "2018 Santafe",
        "price": 2815,
        "type": "中型"
      },
      {
        "_rank": 2,
        "_key": "car-10002",
        "_qds": 0.8729686141014099,
        "brand": "<b>Hyundai</b>",
        "docid": "car-10002",
        "name": "2018 Grandure",
        "price": 2615,
        "type": "中型"
      },
      {
        "_rank": 3,
        "_key": "car-3",
        "_qds": 0.8707408308982849,
        "brand": "<b>chevrolet</b>",
        "docid": "car-3",
        "name": "2018 Malibu",
        "price": 2388,
        "type": "中型"
      }
    ]
  }
}
```