AI 助理
文档备案控制台
官方文档
首页

搜索处理

更新时间：
复制 MD 格式
产品详情
我的收藏

系统提供了丰富的搜索语法以满足用户各种场景下的搜索需求。

URL

/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

string

是

搜索主体，不能为空。行业算法版支持空搜（即不指定query子句中的查询词），可通过传入空字符串''作为query子句的查询词实现。空搜场景下，2112报错为展示问题，不影响全量结果返回。主要支持子句有 config子句、query子句、sort子句、filter子句、aggregate子句、distinct子句、kvpairs子句。

fetch_fields

string

否

全部可展示字段。

表示本次查询需要召回哪些字段值，多个字段之间通过英文分号;分隔，对应控制台中的默认展示字段功能。

qp

string

否

已上线规则

指定要使用的查询分析规则，多个规则使用英文逗号,分隔。

disable

string

否

关闭指定已生效的参数功能。

first_rank_name

string

否

系统中默认基础排序表达式名字

设置基础排序表达式名字，最多仅支持1个基础排序名称。

second_rank_name

string

否

系统中默认业务排序表达式名字

设置业务排序表达式名称，最多仅支持1个业务排序名称。

user_id

string

否

用来标识发起当前搜索请求的终端用户。该值可以设置为下列值，优先级从高到低：1. 终端用户的长登录会员ID². 终端用户的移动设备imei标识

abtest

string

否

使用A/B Test功能时需要设置该参数。

raw_query

string

否

用于类目预测等算法训练使用，因此，建议所有查询都设置该参数；

search_strategy

string

否

用于多路搜索时配置查询策略名称

re_search

string

否

用来设置重查策略，当前只支持按照total hits的阈值来设置。

biz

string

否

用来描述本次请求的相关业务信息 。比如本次请求来源的业务类型。

summary

string

否

获取系统结果摘要配置

搜索结果摘要配置，可以指定某些字段进行飘红、截断等操作。

from_request_id

string

否

本搜索请求从哪里引导而来，如果当前的query来自下拉提示、热词、底纹等功能的推荐列表，那么请求这个推荐列表的request_id可以赋给这个参数，通过关联这个引导事件，可以计算上游功能的各项指标，衡量使用效果，为优化功能提供依据。详见下拉提示产品文档。

vector_search

string

否

query子句

string

是

用于设置搜索条件

config子句

string

否

用于设置搜索召回数据格式，及召回文档数

filter子句

string

否

用于设置过滤条件

sort 子句

string

否

用于设置文档排序条件（仅支持单字段int类型，仅限v3版API及SDK）

查询参数用法

  • query：可以通过若干子句的组合来实现多样的搜索需求，query参数中各子句之间通过&&进行连接。行业算法版支持空搜，即query子句的查询词传入空字符串''，系统将返回全量结果。空搜时可能出现2112报错，该报错为展示问题，不影响实际搜索结果。

  • 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_search：

    参数名

    类型

    默认值

    说明

    namespace

    list<string>

    查询类目。

    threshold

    float

    向量召回最低分阈值。

    top_n

    uint32

    向量召回topN。

    search_params.qc_scan_ratio

    float

    0.01

    用于计算max_scan_num数量，总doc数量 * scan_ratio。

    search_params.hnsw_ef

    uint32

    500

    用于检索时，考察精度。该值越大，扫描doc数越多，召回率越高。

  • vector_threshold：

  • 功能说明

    • 控制向量召回文档的向量分数阈值，表示只召回向量分小于该值的文档。

  • 参数格式：

      vector_threshold=14.0

    • 取值类型为浮点型；

    • 可选参数，如没有设置，系统会使用内置的阈值。

  • summary：

    • summary_element_prefix 与 summary_element_postfix 必须同时设定。

    • summary_element 与 （summary_element_prefix、summary_element_postfix）是相互影响的，出现在后面的配置会覆盖前面。

    • 目前不支持摘要和飘红单独设置。

    • 如果SDK/API中有配置该参数会覆盖控制台中对应功能配置。

参数

类型

必需

取值范围

默认值

描述

summary_field

string

是

要做摘要的字段

summary_element

string

否

em

飘红标签，html标签去掉左右尖括号

summary_ellipsis

string

否

…

摘要的结尾省略符

summary_snipped

int

否

1

选取的摘要片段个数

summary_len

string

否

摘要要展示的片段长度

summary_element_prefix

string

否

飘红的前缀，必须是完整的html标签，如<em>

summary_element_postfix

string

否

飘红的后缀，必须是完整的html标签，如</em>

返回结果

参数

类型

描述

status

string

执行结果，OK为成功，FAIL为失败，请根据返回错误码进行排查

request_id

string

该条查询的记录ID，主要用于排查问题使用

result

JSON

实际返回结果，包括查询耗时searchtime、引擎总结果数total、本次请求返回结果数num、本次查询最大返回结果数viewtotal、查询结果items、统计结果facet等信息

errors

list

错误码和错误内容，message代表错误信息；code 对应含义参考 错误码文档

  • 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（未指定精排中设置的索引）等报错时，仍可能有结果返回。

Scroll 扫描

传统搜索场景的主要目的是为了尽量短的时间内召回最符合的结果，所以对搜索结果进行了限制，例如 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

HTTP请求方式

GET

支持格式

JSON

查询参数

参数

类型

必需

取值范围

默认值

描述

scroll

STRING

是

周，日，时，分，秒

表示下一次 scroll请求的有效期，每次请求都必须设置该参数，可以用1m表示1min；支持的时间单位包括：w=Week, d=Day, h=Hour, m=minute, s=second

search_type

STRING

是

scan

第一次查询的时必须填写，后续无需填写，后续通过指定 scroll_id 实现下一次查询

scroll_id

string

是

第一次调用scroll方法会返回scroll_id 但并不包含数据，后续每次搜索都必须指定上一次返回scroll_id，并且后续搜索结果中都会返回scroll_id及对应匹配的数据，后续查询该参数必填

query子句

string

是

用于设置搜索条件

config子句

string

是

用于设置搜索召回数据格式，及召回文档数

filter子句

string

否

用于设置过滤条件

sort 子句

string

否

用于设置文档排序条件（仅支持单字段int类型，仅限v3版API及SDK）

fetch_fields参数

string

否

用于设置召回哪些应用字段内容

返回结果

参数

类型

描述

status

string

执行结果，OK为成功，FAIL为失败，请根据返回错误码进行排查

request_id

string

该条查询的记录ID，主要用于排查问题使用

result

string

实际返回结果，包括查询耗时searchtime、引擎总结果数total、本次请求返回结果数num、本次查询最大返回结果数viewtotal、查询结果items、统计结果 facet、scorllid 等信息

errors

string

错误内容，error_message代表错误信息。error_code 对应含义参考 错误码文档
说明

注意： scroll 返回结果格式，目前只支持返回为fulljson，JSON格式。

Scroll示例

说明

注意： config子句中start无效，通过hit值设置每次召回文档数。 aggregate、distinct、粗精排表达式等都无效，sort子句只支持单字段INT类型排序。 不支持多应用scroll查询。 如果传入的scroll_id非法，查询时会报错。 召回结果格式只支持fulljson，JSON。 第一次查询只返回scroll_id，不返回文档数据，需要再次查询并设置上一次查询返回的scroll_id才能召回数据。

第一次请求

说明

注意： 此处省略了请求Header参数及编码等因素。

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

后续请求

说明

注意： 此处省略了请求Header参数及编码等因素。

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

上一篇：推送采集数据下一篇：检索增强生成