/v3/openapi/apps/$app_name/search?fetch_fields=name&query=config=format:fulljson&&query=name:'zhangsan'&&sort=id

• $app_name：表示應用名（高級版/標準版是多應用版本類型，需要指定應用名訪問，主要針對服務中的應用版本，如填寫線下應用ID可訪問線下應用搜索服務）。

• 以上 URL 省略了請求Header參數及編碼等因素。

• 以上 URL 中省略了訪問應用的 host 地址。

• 以上URL 中拼接的所有查詢參數，請查看下方“查詢參數”的參數定義、使用方式及樣例。

HTTP

GET

JSON

查詢參數具體拼接規則，詳情請參見V3版API簽名機制文檔。

查詢參數用法

• query：可以通過若干子句的組合來實現多樣的搜索需求，query參數中各子句之間通過&&進行連接。

• fetch_fields：返回文本數據大小對查詢性能影響較大，建議只獲取需要的字段。如果SDK/API中有配置該參數會覆蓋控制臺中對應功能配置。

• qp：如果SDK/API中有配置該參數會覆蓋控制臺中對應功能配置。

注意事項：qp的生效過程以及結果可以在控制臺搜索測試頁面查看，API/SDK暫不支持透出。

• disable：目前支持禁用qp、summary、first_rank、second_rank、re_search等參數功能。

  功能說明

  • 控制查詢過程中關閉某些功能

  • 目前支持禁用查詢分析、飄紅、粗精排, 重查等參數功能

  參數格式：

  disable=function[;function]
  function=function_name[:function_param]

  • 例如：

    • 關閉查詢分析， disable=qp

    • 關閉查詢分析中的spell_check功能，disable=qp:spell_check，格式：disable=qp:$qp_processor_name，參考：QueryProcessor

    • 關閉重查, disable=re_search

• first_rank_name：如果SDK/API中有配置該參數會覆蓋控制臺中對應功能配置。

• second_rank_name：如果SDK/API中有配置該參數會覆蓋控制臺中對應功能配置。

• user_id：

  • 在搜索請求中設置時候，user_id的值需要做urlencode。

  • 數據統計功能在統計UV信息時依賴該參數做統計。

  • 如果有對接數據采集，盡量讓上報行為數據時候的user_id和查詢請求中的user_id保持設置規則一致。

• abtest參數格式：abtest=urlencode(scene_tag:urlencode(\$scene),flow_divider:urlencode(\$value))，其中urlencode為URL編碼函數。

  • flow_divider推薦為最終用戶的ID，如果沒有的話可以用最終用戶的設備ID或者IP地址，該參數必須指定。

  • scene_tag：場景標識，如果用戶在控制臺上沒有設置表示對所有場景下的流量都會做實驗，查詢中就不用設置scene_tag。

• raw_query：

  功能說明

  • 用于類目預測查詢；只有查詢詞和raw_query的內容一致時，查詢時，才會去查查詢分析中配置的類目預測；

  • 用于類目預測等算法訓練使用，因此，建議所有查詢都設置該參數；

  • 一般建議設置為終端用戶輸入的原始查詢詞。

  參數格式：

  raw_query=content

  • content: 原始查詢詞

• re_search：

  功能說明

  • 用來設置重查策略，當前只支持按照total hits的閾值來設置。

  • 需配置查詢分析功能。

  • 若query中的查詢詞分詞后的term實體識別權重都一樣，則不會觸發重查，需干預實體識別類別權重。

  參數格式：

  re_search=strategy:threshold,params:total_hits#${COUNT}

  • COUNT: 觸發重查時的total_hits上限。即當total hits少于COUNT時，會進行重查

  • 樣例：

    • re_search=url_encode(strategy:threshold,params:total_hits#6)

• biz：

  功能說明

  • 用來描述本次請求的相關業務信息。比如本次請求來源的業務類型。

    參數格式：

    biz=type:$TYPE

  • type: 用戶用來設置流量的類型，取值用戶自己確定，后續可以在報表中區分不同的來源統計

  • 樣例：

    • biz=type:home_page

• vector_threshold：

• summary：

  • summary_element_prefix 與 summary_element_postfix 必須同時設定。

  • summary_element 與 （summary_element_prefix、summary_element_postfix）是相互影響的，出現在后面的配置會覆蓋前面。

  • 目前不支持摘要和飄紅單獨設置。

  • 如果SDK/API中有配置該參數會覆蓋控制臺中對應功能配置。

返回結果

• searchtime：指引擎耗時，單位為秒。

• total、viewtotal、num區別：total為一次查詢（不考慮config子句）引擎中符合條件的結果數（在結果數較多情況下，該值會做優化），但考慮到性能及相關性，引擎最多會返回viewtotal個結果。如果需要翻頁的話，要求start+hit必須要小于viewtotal，total一般用來做展示。num為本次查詢請求（受限于config子句的start及hit）實際返回的條目，不會超過hit值。

• compute_cost：是一個只有一個map元素的數組，其中index_name表示應用ID，value表示本次查詢消耗的LCU。

• items：包含查詢召回數據信息，其中fields為搜索召回內容。

• variableValue：表示自定義參數返回結果，如獲取distance距離值，variableValue 節點只有在config子句的format為xml或者fulljson時才能展現出來，json格式默認不展示。

• sortExprValues： 表示對應文檔排序分。

• facet：用于存放Aggregate子句返回的信息。

• array字段類型：通過JSON和fulljson格式返回，數據之間通過\t分割，如果通過xml格式返回，通過空格分割

Search示例

返回結果JSON

{
 "result": {
  "searchtime": 0.009554,
  "total": 1,
  "compute_cost": [
   {
    "index_name": "110247758",
    "value": 0.304
   }
  ],
  "num": 1,
  "viewtotal": 1,
  "items": [
   {
    "variableValue": {

    },
    "sortExprValues": [
     "10000"
    ],
    "property": {

    },
    "attribute": {

    },
    "fields": {
     "size": "XL",
     "discount_price": "9.9",
     "pid": "950",
     "range_age": "18\t25",
     "detail": "男士夾克翻領2021春秋新款青年薄款上衣休閑拉鏈外套",
     "index_name": "110247758"
    }
   }
  ],
  "facet": []
 },
 "ops_request_misc": "%7B%22request%5Fid%22%3A%22162642700916781929257960%22%2C%22scm%22%3A%2220140713.110229359..%22%7D",
 "tracer": "",
 "request_id": "162642700916781929257960",
 "errors": [],
 "status": "OK"
}

錯誤返回

{
 "result": {
  "searchtime": 0.003999,
  "total": 0,
  "compute_cost": [
   {
    "index_name": "110247758",
    "value": 0.232
   }
  ],
  "num": 0,
  "viewtotal": 0,
  "items": [],
  "facet": []
 },
 "ops_request_misc": "%7B%22request%5Fid%22%3A%22162642716516781913069826%22%2C%22scm%22%3A%2220140713.110229359..%22%7D",
 "tracer": "",
 "request_id": "162642716516781913069826",
 "errors": [
  {
   "code": 6127,
   "message": "Attribute not exist."
  }
 ],
 "status": "FAIL"
}

• 說明：status為FAIL表示既有error又無結果返回；但可能會出現既有error，又會有結果返回，此時status就為OK. 如出現1000 server error（搜索超時）；或者2112（未指定精排中設置的索引）等報錯時，仍可能有結果返回。

傳統搜索場景的主要目的是為了盡量短的時間內召回最符合的結果，所以對搜索結果進行了限制，例如 search方法最多只能召回5000條文檔。在某些場景下需要提供更多的結果來進行分析工作，可以使用scroll接口來獲取更多的結果。

支持子句

• query子句。

• config子句（start參數無效）。

• filter子句。

• sort子句（只支持單字段INT類型，僅限v3版API及SDK）。

URL

首次查詢

/v3/openapi/apps/$app_name/search?search_type=scan&scroll=1m&查詢參數

后續查詢

/v3/openapi/apps/$app_name/search?scroll_id=$scroll_id&scroll=1m&查詢參數

• $app_name：表示應用名。

• 以上 URL 中省略了訪問應用的 host 地址。

• 以上2次 scroll請求 URL 省略了請求Header參數，查詢參數對應內容，及編碼等因素，完整scroll 請求 URL 參考下面示例描述。

• scroll 方法支持的功能較少，大部分功能都不支持，具體功能限制參考底部注意事項。

HTTP

GET

JSON

第一次請求

http://$host/v3/openapi/apps/app_schema_demo/search?query=config=start:0,hit:1,format:fulljson,rerank_size:200&&query=name:'搜索'&&sort=+id&&filter=id>0&search_type=scan&scroll=1m&fetch_fields=id;name;phone;int_arr;literal_arr;float_arr;cate_id

成功返回

{
  "status": "OK",
  "request_id": "150150574119953661605242",
  "result": {
    "searchtime": 0.005029,
    "total": 1,
    "num": 0,
    "viewtotal": 1,
    "scroll_id": "eJxtUMtuhDAM/BrvOYQC5cABdulvRFFIirsm2TpBavv1Ndut1EMlS36NZ0Y2ZHMxbueceAjIuWCMnrPjRITLyfzZm83y9V QVGT8x80U3PxQNUqieVZV1/an4ItbTUBPSx5wgXqKdvOSbmuKR8ZYjGWWirB4tvToAiX7u3G2eCNK77vnz8GlGPAV6suKBeqxAn0OiTd7NGEnesspyoyFLF6hecn4JUKjVgp0K3FnkfMfIyPoDuYWegX9GeYOpicY9TG8gwOSuBL04X1 MMg3ROwCesLlG6X7a2o=",
    "items": [],
    "facet": []
  },
  "errors": [],
  "tracer": ""
}

后續請求

http://$host/v3/openapi/apps/app_schema_demo/search?fetch_fields=id;name;phone;int_arr;literal_arr;float_arr;cate_id&query=config=start:0,hit:1,format:fulljson,rerank_size:200&&query=name:'搜索'&&sort=+id&&filter=id>0&scroll=1m&scroll_id=eJxtUMtuhDAM/BrvOYQC5cABdulvRFFIirsm2TpBavv1Ndut1EMlS36NZ0Y2ZHMxbueceAjIuWCMnrPjRITLyfzZm83y9V+QVGT8x80U3PxQNUqieVZV1/an4ItbTUBPSx5wgXqKdvOSbmuKR8ZYjGWWirB4tvToAiX7u3G2eCNK77vnz8GlGPAV6suKBeqxAn0OiTd7NGEnesspyoyFLF6hecn4JUKjVgp0K3FnkfMfIyPoDuYWegX9GeYOpicY9TG8gwOSuBL04X1+MMg3ROwCesLlG6X7a2o=

返回結果

{
  "status": "OK",
  "request_id": "150150574119952551519970",
  "result": {
    "searchtime": 0.006293,
    "total": 1,
    "num": 1,
    "viewtotal": 1,
    "scroll_id": "eJxNT9tugzAM/RrznIRC4YEHaNlvRFFIhteQtE6Qtn39TNdJk2z5dnx8rIPJRdudcqKhl60Uir2Vp06ISv8b6s3QbZCVzpaCdp93XXBzg2wEW9MJ2dWq8q7YVXt0YckDLlBP0WyOw31N8YgYizZEnAUsjkx4VT4k8zexpjiNS/XYHX0NNkWP71BfVyxQjxLUxSfazFH4PYSPnCL3iMniDZq3jN98aFRCgGrZniy8/itkBHWGuYVeQH+B+QzTCUZ1NJ9gj4FVMfrQPr8Y+Hk+dgU14fIDVhtfTw==",
    "items": [
      {
        "fields": {
          "cate_id": "0",
          "float_arr": "0",
          "id": "1",
          "int_arr": "0",
          "literal_arr": "搜索",
          "name": "搜索",
          "phone": "123****5678",
          "index_name": "app_schema_demo"
        },
        "property": {},
        "attribute": {},
        "variableValue": {},
        "sortExprValues": [
          "1"
        ]
      }
    ],
    "facet": []
  },
  "errors": [],
  "tracer": ""
}