Document 검색

색인별로 생성한 문서에 대해 검색을 수행합니다.
해당 요청을 수행하기 이전에 Domain 생성Document 생성이 되어져 있어야 합니다.

  • 검색 서비스 구성을 위해서는 검색 기본 지식이 필요합니다.
  • 서비스 생성 시 설정한 Schema로 검색 수행
  • JSON 형태의 queryDSL 사용
POST https://cloudsearch.apigw.gov-ntruss.com/CloudSearch/real/v1/domain/{name}/document/search

요청

요청 파라미터

파라미터 명 필수 여부 타입 제약사항 설명
name Yes string 생성되어져 있는 Domain 이름

overview

Search Query에 대한 자세한 예제는 Cloud Search 사용가이드 - Search Query 사용 가이드를 참고하시기 바랍니다.

{
  "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 검색 결과의 시작 랭킹
display No String, Integer default : 20 검색 결과의 개수
result_format No String json 검색 결과 포맷 지정, 현재는 json 포맷만 지원합니다.
index_name Yes String 기존에 생성된 색인 중 선택 검색 할 색인의 이름
queryList Yes List<SearchQuery> SearchQuery.query_method가 “main”인 SearchQuery를 반드시 포함 검색 요청 쿼리
sort No Object 검색 결과 정렬 기준을 가지는 Map 형태의 Object
  • key : 정렬 기준 섹션
  • value : 정렬 방식 지정(desc, asc)
  • scope No List<SearchScope> 제한 검색 설정 목록
    key_scope No Object 제한 검색을 설정하는 Map 형태의 Object
  • key : 제한 검색 방식 선택
  • value : 제한 검색 방식에 따른 값 설정
  • key 옵션 종류
  • - exist, nexist: 지정한 값이 존재하는 문서 속성으로 검색 결과를 제한합니다.
    user_scope No String 랭킹 코드 형태의 수식 사용자가 직접 scope 수식을 입력, 입력된 수식은 ‘scope’ 파라미터의 내용과 and 조건으로 추가됩니다.
  • ex) price가 2000 초과 5000 미인 문서를 찾을 때,“(dp_price > ‘2000’) and (dp_price < ‘5000’)”
  • highlighting No SearchHighlighting Default: true 검색 결과 구문 강조 설정
    display_section No String, Array 기존에 생성한 섹션 중 선택 검색 결과로 보여줄 섹션을 지정(지정하지 않으면 모든 섹션 데이터 출력)
    예 : 가격과 이름만 결과로 출력하고 싶을 때, “price, name”
  • 여러 섹션 조합 가능
    예 : 브랜드와 이름을 하나의 결과로 출력하고 싶을 때, “brand+name”
  • passage No List<SearchPassage> 검색 결과 추출 방식 설정
    aggregate No List<SearchAggregate> 검색 결과 요약 설정 목록
    result_processing No SearchResultProcessing 검색 결과 후처리 설정
    setting No SearchSetting 검색 시 기타 환경 설정
    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 및 SearchQuery의 내용이 mapping 된 object
    result object 검색 결과
    result.start number 검색 결과의 시작 랭킹 default : 1
    result.display number 검색 결과의 개수 default : 20
    result.ranking string 랭킹 방식 “clous”
    result.sort_by string 랭킹 기준 default : “qds”
    result.total_count number 총 검색 결과
    result.removed_count number 삭제된 검색 결과
    result.item_count number 검색 결과 갯수
    result.items Array 검색된 문서 Document 생성시 작성한 request[].content 데이터와 검색 정보를 포함하는 list
    result.items[]._rank number 검색 랭킹
    result.items[]._key string 문서의 primary key
    result.items[]._qds number 검색 query와 해당 문서의 일치 정도

    응답 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

    요청 예시

    예시에서 사용되는 문서는, 검색 서비스 생성 예제와 동일합니다.

    일반 검색 요청 예시(검색어 “현대”)

    POST https://cloudsearch.apigw.gov-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.gov-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": "현대"
          }
        }
      },
      "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": [
              "현대"
            ]
          }
        }
      },
      "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>현대</b>",
            "docid": "car-10001",
            "name": "2018 싼타페",
            "price": 2815,
            "type": "중형"
          },
          {
            "_rank": 2,
            "_key": "car-10002",
            "_qds": 0.8729686141014099,
            "brand": "<b>현대</b>",
            "docid": "car-10002",
            "name": "2018 그랜저",
            "price": 2615,
            "type": "중형"
          }
        ]
      }
    }
    
    

    불용어 검색 요청 예시(검색어 “현대와 쉐보레”)

    불용어 예시(rule name: “josa”)

    {
      "type": "filter",
      "word_list": [
        "은", "는", "이", "가", "을", "를", "의", "와"
      ]
    }
    

    검색어와 매칭되는 모든 단어를 찾기 위해서는 “or” option이 필요합니다.

    POST https://cloudsearch.apigw.gov-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.gov-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": "현대와 쉐보레",
            "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": [
              "쉐보레",
              "현대"
            ]
          }
        }
      },
      "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>현대</b>",
            "docid": "car-10001",
            "name": "2018 싼타페",
            "price": 2815,
            "type": "중형"
          },
          {
            "_rank": 2,
            "_key": "car-10002",
            "_qds": 0.8729686141014099,
            "brand": "<b>현대</b>",
            "docid": "car-10002",
            "name": "2018 그랜저",
            "price": 2615,
            "type": "중형"
          },
          {
            "_rank": 3,
            "_key": "car-3",
            "_qds": 0.8707408308982849,
            "brand": "<b>쉐보레</b>",
            "docid": "car-3",
            "name": "2018 말리부",
            "price": 2388,
            "type": "중형"
          }
        ]
      }
    }
    
    아쉬운 점이 있다면 이야기해 주세요.
    0/5000
    내용을 입력해 주세요
    의견 보내기