---
title: "Document 管理"
slug: "analytics-cloudsearch-managedocument"
updated: 2026-09-17T09:57:26Z
published: 2026-09-17T09:57:26Z
canonical: "api.ncloud-docs.com/analytics-cloudsearch-managedocument"
---

> ## 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 管理

文書の insert(インデックス)、update、upsert、deleteリクエストを実行します。すべてのリクエストは POSTメソッドを使用し、そのリクエストを実行する前に [Domainが作成](/docs/ja/analytics-cloudsearch-createdomain)されている必要があります。

- 基本的に insert/upsertリクエストは、既存の文書が存在しないか、文書や辞書が変更されてインデックスが変更された場合にインデックスリクエストになります。
- update *timeを指定した場合は、既存の文書の update* timeと同じか、最新の場合のみ実際の変更が承認されます。
- **リクエストは utf-8を使用します。**
- 1回のリクエストで insert/upsert/update/deleteを同時にリクエストできます。
- リクエストは順次処理されます(内部で primary keyが混ざらないように並列処理)。
- 一度にアップロード可能な文書は1000件/5MBで、大容量のアップロードは [Object Storage Document管理](/docs/ja/analytics-cloudsearch-manageobjectstoragedocument)を通じて実行できます。
- **自動補完機能を使用している場合は、本リクエスト後に[自動補完設定と修正リクエスト](/docs/ja/analytics-cloudsearch-putautocomplete)を行い、自動補完インデックスを更新する必要があります。**

```
POST https://cloudsearch.apigw.ntruss.com/CloudSearch/real/v1/domain/{name}/document/manage
```

## リクエスト

### リクエストパラメータ

| パラメータ名 | 必須有無 | タイプ | 制限事項 | 説明 |
| --- | --- | --- | --- | --- |
| name | Yes | string |  | 作成されている Domain名 |

### リクエストボディ

| フィールド名 | 必須有無 | タイプ | 制限事項 | 説明 |
| --- | --- | --- | --- | --- |
| requests[] | Yes | Array |  | 文書リクエストリスト |
| requests[].type | Yes | string | insert、upsert、update、deleteのいずれかを選択 | リクエストタイプの定義 |
| requests[].update_time | No | string | yymmddHHMMSS.ssssss 例: 170807133300.000000 | 文書が変更された時間をリクエストに明記することを推奨 |
| requests[].force | No | bool | true, false | インデックスされた文書との変更や update_timeと比較せずに無条件でリクエストを処理 |
| requests[].force_hash | No | bool | true, false | インデックスされた文書との変更は無視して update_timeのみ比較し、既存文書に比べて update_timeが同じまたは最新の場合にリクエストを処理 |
| requests[].key | No(update、deleteリクエスト時に必須) | string |  | 文書の primary key |
| requests[].content | No(insert、upsert、updateリクエスト時に必須) | object | メインセクションに該当する keyを必ず含む | リクエストに使用する文書(セクション名を key、その keyにマッピングされる値を valueとする Map形式の Object) |

## レスポンス

| フィールド名 | タイプ | 説明 | 備考 |
| --- | --- | --- | --- |
| request_id | string | indexerが返す update_time値 | yymmddHHMMSS.ssssss 例: 170807133300.000000 |
| status.code | number | リクエスト状態 | 0: 成功、-1: 失敗 |
| status.message | string | 失敗時のエラーメッセージ |  |
| total_document_count | number | リクエストに含まれる個々のリクエスト数 |  |

### レスポンス Status

| HTTP Status | Desc |
| --- | --- |
| 200 | OK(リクエスト完了) |
| 200 | status.code: -1(リクエスト失敗) |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 500 | Internal Server Error |

## リクエストタイプ

以下の例で primary keyは KEYセクションであり、KEYが1であるリクエストは順次処理され、KEYが1であるリクエストと2であるリクエストは互いに関連性がないため、内部的に並列処理されます。

1つのリクエストに insert/upsert/delete/updateリクエストをまとめて送ることができ、リクエスト JSONの **requests[x].contentの key、valueペアはすべて文字列で構成** します(検索エンジンで数値型で使用する場合、内部的に文字列から数値型に変換されます)。

### insertリクエスト

文書が存在する場合、文書が変更されるとインデックスリクエストを行います。文書が存在しない場合、インデックスリクエストを行います。辞書の変更により形態素解析が変わったり、term/document weightが変更された場合にも文書が変更されたと判断されます。

インデックスリクエスト時に定義された文書全体を contentに提供するのが原則ですが、primary keyで定義された keyを除いて省略する場合は空の文字列が使用されます。

primary keyで定義された sectionは contentの中に含まれている必要があります。

```
{
   "requests" : [
      {
         "type" : "insert",
         "key": "1",
         "content" :
          {
            "URL": "http://naver.com/bbs/abc.php?bo_table=QnA&wr_id=321651",
            "KEY": "1",
            "ROOT_ID": "732303375144529937",
            "TITLE": "JSONJSONJSONJSONJSONJSONJSONJSONテスト中です。",
            "DATE": "2012-01-01T00:00:00+0900",
            "BODY_TEXT": "JSONJSONJSONJSONJSONJSONJSONJSON"
          }
      }
  ]
}
```

### upsertリクエスト

リクエストした文書が既に存在する場合、存在する文書とリクエスト文書が mergeされた後、insertと同じように動作します。リクエストされた文書が新しい文書の場合、そのままインデックスされます。

primary keyは別の keyに設定するか、contentの中に必ず含まれている必要があります。

```
{
   "requests" : [
      {
         "type" : "upsert",
         "key" : "1",
         "content" :
          {
            "URL": "http://naver.com/bbs/abc.php?bo_table=QnA&wr_id=321651",
            "KEY": "1",
            "ROOT_ID": "732303375144529937",
            "TITLE": "JSONJSONJSONJSONJSONJSONJSONJSONテスト中です。",
            "DATE": "2012-01-01T00:00:00+0900",
            "BODY_TEXT": "JSONJSONJSONJSONJSONJSONJSONJSON"
          }
      }
  ]
}
```

### updateリクエスト

既存の文書を一部アップデートします。リクエストした文書が存在しない場合は何も起こりません。

```
{
   "requests" : [
      {
         "type" : "update",
         "key" : "2",
         "content" :
          {
            "ROOT_ID": "223",
            "DATE": "2017-01-01T00:00:00+0900"
          }
      }
  ]
}
```

### deleteリクエスト

リクエストした文書を削除します。リクエストした文書が存在しない場合は何も起こりません。

```
{
   "requests" : [
      {
         "type" : "delete",
         "key" : "2"
      }
  ]
}
```

## 例

### リクエスト例 - insert

```
POST https://cloudsearch.apigw.ntruss.com/CloudSearch/real/v1/domain/car_dev/document/manage

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

{
  "requests": [
    {
      "type": "insert",
      "content": {
        "docid": "car-10001",
        "brand": "現代",
        "name": "2018サンタフェ",
        "color": "black",
        "price": "2817",
        "type": "中型"
      }
    },
    {
      "type": "insert",
      "content": {
        "docid": "car-10002",
        "brand": "現代",
        "name": "2018グレンジャー",
        "color": "white",
        "price": "2618"
      }
    }
    ]
}
```

### レスポンス例(共通)

```
{
  "result": "ok"
}
```