Document 관리

문서의 insert(색인), update, upsert, delete 요청을 수행합니다. 모든 요청은 POST 메서드를 사용하며, 해당 요청을 수행하기 이전에 Domain이 생성되어져 있어야 합니다.

  • 기본적으로 insert/upsert 요청은 기존에 문서가 존재하지 않거나 문서가 변경되거나, 사전이 변경되어서 색인이 변경되었을 경우에 색인 요청이 됩니다.
  • update_time을 명시한 경우에는 기존에 있는 문서의 update_time보다 같거나 최신일 경우에만 실제 변경이 승인됩니다.
  • 요청은 utf-8을 사용합니다.
  • 한 번의 요청에 insert/upsert/update/delete를 한꺼번에 요청할 수 있습니다.
  • 요청은 순차적으로 처리됩니다. (내부에서 primary key가 섞이지 않게 병행 처리)
  • 한 번에 업로드가 가능한 문서는 1000건/5MB이며, 대용량 업로드는 Object Storage Document 관리를 통해 할 수 있습니다.
  • 자동 완성 기능을 사용하고 있을 경우, 본 요청 이후 자동 완성 설정 및 수정 요청을 통해 자동 완성 색인을 갱신해야 합니다.
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인 요청은 서로 연관성이 없기 때문에 내부적으로 병렬 처리됩니다.

하나의 요청에 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
accept: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"
      }
    }
    ]
}

응답 예시 (공통)

{
  "request_id": "181226184658.967684",
  "status": {
    "code": 0,
    "message": ""
  },
  "total_document_count": 2
}