Cloud Search overview

Cloud Search provides API through API Gateway of NAVER Cloud Platform.
Access Key and Secret Key are required for API authentication,
see API Gateway User Guide - Making API Calls for API key creation and usage instructions.
See Common Guide - API Overview regarding Access Key and Secret Key.

Cloud Search provides various APIs, and you can check the API specifications and perform simple tests through the Swagger page. Cloud Search's Swagger documentation can be accessed through the following steps.

1. Console access
2. Select Services > API Gateway service
3. Select Published APIs > CloudSearch > Catalog
4. After selecting CloudSearch, select API Documentation at the bottom.
   The screen that appears at this time is Cloud Search's Swagger page, and the link displayed at the top of the page as https://cloudsearch.apigw.ntruss.com/CloudSearch/real is the API address of Cloud Search.

Common settings

Cloud Search API URL

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

Request header

Search service creation example

In this example, we can explain 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) that can be configured when creating the domain.

Search settings creation

Let's assume that each car model has the following information. In the search engine, a bundle of information that represents the subject of a search is referred to as a Document.
Thus, the bundle of information below becomes one document:

• docid: the item that becomes the key for individual documents
• brand: car brand
• name: car name
• price: price
• type: car model

Section

In Cloud Search, each item here is referred to as a section. And among them, the section that can identify this document,
in other words, the section that becomes the key, is called the main section. For example, the following JSON file is one document, and the key for this document is "car-10001".

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

To insert a document like this, you need to add "docid, brand, name, price, and type" as sections.

You can omit the data type of the section if strings are regular. However, if it's not, you must specify one of the following data types: float, uint8, uint16, uint32, uint64, int8, int16, int32, int64, string, mstring, muint8, and muint32.

You can give various attributes to each section, and if you assign the name dp_price to the section named price, you can utilize it for additional search features in Document search.

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

Index

When searching for cars, there are cases where you search only by brand name and cases where you search by brand name, car name, and car type together. When you want to search with different sections that serve as the target for searching or with different search characteristics depending on the purpose, you need to create indexes for each purpose. If you don't want to make a special distinction, you can create an index by including all sections.

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

You can configure various language morphological analyzers when creating an index. In this example, a Korean morphological analyzer is specified for the brand_name index. The support for morphological analysis in other languages can be checked through Morphological analysis option inquiry - list of supported languages.

When you define sections and indexes as shown below in the search settings, i.e., Schema, you can send it to the Schema validation request to check its validity.

{
   "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 response like "valid" as shown below, you need to modify the Schema.

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

If you received a response like "valid" in the above request, you need to configure the search settings you created when making the create Domain request.

Create domain

Since we are still in the process of developing the portal service, let's create a domain named "car_dev". Cloud Search users
can easily manage development, testing, and production environments by creating domains named "car_stage" and "car_production" when setting up stage and production environments in the future. In Cloud Search, the concept of domain is used to distinguish environments in this way.

Referring to the search settings used above and Create domain API, if you define parameters in JSON file as shown in the example below and make a POST request to /v1/domain, a domain named "car_dev" is created.

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

View domain

To confirm that the domain has been created, you can make View domain API call and receive a response like the one below.
If there are already other domains created, you can receive responses for 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

Add documents to the newly created domain "car_dev". See download example file.
Able to insert, update, upsert, or delete documents as needed, and for detailed usage, see Document management.
Able to add multiple documents in one request, and you can also combine insert, update, upsert, and delete requests to send multiple requests at once.

Able to send requests to Document management to insert, update, upsert, or delete documents.

Next, request to add 3 documents.
Since it is for adding to the "car_dev" domain, you can make a call to /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": "Mid-size"
      }
    },
    {
      "type": "insert",
      "key": "car-10002",
      "content": {
        "docid": "car-10002",
        "brand": "Hyundai",
        "name": "2018 Grandeur",
        "price": "2615",
        "type": "Mid-size"
      }
    },
    {
      "type": "insert",
      "key": "car-3",
      "content": {
        "docid": "car-3",
        "brand": "Chevrolet",
        "name": "2018 Malibu",
        "price": "2388",
        "type": "Mid-size"
      }
    }
  ]
}

Search

Now, you can search documents added to car_dev. For detailed information on search API, see Document Search.

Perform a simple brand name search. Create the request as shown below and then make a POST call to /v1/domain/car_dev/document/search.

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

Results like the ones shown below can be obtained:

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

In addition, auto complete settings and stop word policy settings are supported. For detailed information, see the respective page.