Cloud Search overview

Cloud Search provides an API through NAVER Cloud Platform's API Gateway.
An access key and secret key are required to authenticate the API.
For information on how to generate and use API keys, see API Gateway user guide - Call API.
For information on access keys and secret keys, see Common guide - API overview.

Cloud Search is providing various APIs and you can check the API's specifications and perform a simple test through Swagger page. You can access the Cloud Search's Swagger document as follows:

1. After logging in to the console, select the All Services > API Gateway service.
2. Select Published APIs > CloudSearch > Catalog.
3. Select CloudSearch, then the API guide at the bottom.
   The screen you'll see is the Cloud Search's Swagger page, and the link at the top of the page, https://cloudsearch.apigw.ntruss.com/CloudSearch/real, is the Cloud Search's API address.

Common settings

Cloud Search API URL

https://cloudsearch.apigw.ntruss.com/CloudSearch/real

Request headers

Search service creation example

In this example, we’ll describe how to use the API by creating a search portal service that provides information on various car models from around the world.
Before creating a domain, let’s define the search settings (schema) to be configured when creating the domain.

Create search settings

Let’s assume that each car model has the following information. In a search engine, a collection of information that represents the subject of a search is referred to as a document.
In other words, the collection of information below constitutes a single document.

• docid: The key for each individual document
• brand: Car brand
• name: Car name
• price: Price
• type: Vehicle type

Section

In Cloud Search, each of these items is called a section. Among them, the section that identifies this document—that is,
the section that serves as the key—is called the main section. For example, the JSON below represents a single document, and the key for this document is "car-10001."

{
  "docid": "car-10001",
  "brand": "Hyundai",
  "name": "2018 Santa Fe",
  "price": "2815",
  "type": "Midsize"
}

To include a document like this, you must add the following sections: docid, brand, name, price, and type.

For general strings, you can omit the section’s data type; otherwise, you must specify one of the following: float, uint8, uint16, uint32, uint64, int8, int16, int32, int64, string, mstring, muint8, or muint32.

You can assign various attributes to each section; for example, if you assign the name "dp_price" to the "price" section, it can be used for additional search features in Document search.

{
  "docProperties":[
    {
      "type":"uint32",
      "name":"dp_price"
    }
  ],
  "name":"price"
}

Index

When searching for cars, users may search using only the brand name, or they may search using a combination of the brand name, car name, and vehicle type. When you want to vary the sections included in the search or the search characteristics depending on the purpose, you must create separate indexes tailored to each specific purpose. If you do not want to make this distinction, you can simply create an index that includes all sections.

The example below creates an index named "brand_name" for the "brand" and "name" sections.

When creating an index, you can configure morphological analyzers for various languages. In this example, we specify a Korean morphological analyzer for the "brand_name" index. You can check whether morphological analysis is supported for other languages via Get morphological analysis options - List of supported languages.

You can verify whether your search configuration, which defines sections and indexes, Schema, is valid by sending it to Schema validation request, as shown below.

{
   "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"
         }
      ]
   }
}

If you do not receive a "valid" response as shown below, you must revise the schema.

{
  "status": "valid",
  "message": "OK",
  "response": "{\"status\":{\"code\":0,\"message\":\"ok\"}}\n"
}

If you received a "valid" response to the above request, you must configure the search settings you specified when making the Create domain request.

Create domain

Since we are still developing the portal service, we will create a domain named car_dev. Cloud Search users
should create domains such as "car_stage" and "car_production" when setting up stage and production environments in the future to distinguish between environments, as this will facilitate development, testing, and operations. Cloud Search uses the concept of domains to distinguish between environments in this way.

Referring to the search settings used above and the Create domain API, define the parameters in JSON as shown in the example below and make a POST request to /v1/domain to create a domain named "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"
         }
      ]
   }
  }
}

Get domain

If you call the Get domain API to verify that a domain has been created, you will receive a response like the one shown below.
If other domains have already been created, you will receive a response listing multiple domains.

{
    "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"
  }

Upload document

We will add a document to the newly created domain, "car_dev." See Download sample file.
You can insert, update, upsert, or delete documents as needed. For detailed instructions, see Manage document.
You can add multiple documents in a single request, and you can also combine insert, update, upsert, and delete requests to send multiple types of requests at once.

You can insert, update, upsert, or delete documents by sending requests to Manage document.

The following is a request to add three documents.
Since you are adding them to the "car_dev" domain, simply call /v1/domain/car_dev/document/manage.

{
  "requests": [
    {
      "type": "insert",
      "key": "car-10001",
      "content": {
        "docid": "car-10001",
        "brand": "Hyundai",
        "name": "2018 Santa Fe",
        "price": "2815",
        "type": "Midsize"
      }
    },
    {
      "type": "insert",
      "key": "car-10002",
      "content": {
        "docid": "car-10002",
        "brand": "Hyundai",
        "name": "2018 Grandeur",
        "price": "2615",
        "type": "Midsize"
      }
    },
    {
      "type": "insert",
      "key": "car-3",
      "content": {
        "docid": "car-3",
        "brand": "Chevrolet",
        "name": "2018 Malibu",
        "price": "2388",
        "type": "Midsize"
      }
    }
  ]
}

Search

You can now search for documents added to "car_dev." For a detailed description of the search API. see Search document.

Let’s try a simple search by brand name. Just create a request as shown below and send a POST request to /v1/domain/car_dev/document/search.

{
  "search": {
    "brand_name": {
      "main": {
        "query": "Hyundai"
      }
    }
  }
}

You can obtain the following results.

{
  "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": [
          "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 Santa Fe",
        "price": 2815,
        "type": "Midsize"
      },
      {
        "_rank": 2,
        "_key": "car-10002",
        "_qds": 0.8729686141014099,
        "brand": "<b>Hyundai</b>",
        "docid": "car-10002",
        "name": "2018 Grandeur",
        "price": 2615,
        "type": "Midsize"
      }
    ]
  }
}

In addition, we support Autocomplete settings and Stopword policy settings. See respective pages for detailed information.