全部产品
云市场

搜索处理

更新时间:2019-08-26 17:15:46

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

URL

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

  • $app_name:表示应用名(新高级版/标准版是多应用版本类型,需要指定应用名访问,主要针对服务中的应用版本)。
  • 以上 URL 省略了请求Header参数及编码等因素。
  • 以上 URL 中省略了访问应用的 host 地址。
  • 以上URL 中拼接的所有查询参数,请查看下方“查询参数”的参数定义、使用方式及样例。

请求协议

HTTP

请求方式

GET

支持格式

JSON

查询参数

查询参数具体拼接规则,详情请参见V3版API签名机制文档。

参数 类型 必需 取值范围 默认值 描述
query string 搜索主体,不能为空。主要支持子句有 config子句query子句sort子句filter子句aggregate子句distinct子句kvpairs子句
fetch_fields string 全部可展示字段。 表示本次查询需要召回哪些字段值,多个字段之间通过英文分号;分隔,对应控制台中的默认展示字段功能。
qp string 已上线规则 指定要使用的查询分析规则,多个规则使用英文逗号,分隔。
disable string 关闭指定已生效的参数功能。
first_rank_name string 系统中默认粗排表达式名字 设置粗排表达式名字。
second_rank_name string 系统中默认精排表达式名字 设置精排表达式名字。
user_id string 用来标识发起当前搜索请求的终端用户。该值可以设置为下列值,优先级从高到低:
1. 终端用户的长登录会员ID
2. 终端用户的移动设备imei标识
abtest string 使用A/B Test功能时需要设置该参数。
category_prediction string 通过类目预测功能搜索时需要设置该参数。
raw_query string 用于类目预测等算法训练使用,因此,建议所有查询都设置该参数;
re_search string 用来设置重查策略,当前只支持按照total hits的阈值来设置。
summary string 获取系统结果摘要配置 搜索结果摘要配置,可以指定某些字段进行飘红、截断等操作。
query子句 string 用于设置搜索条件
config子句 string 用于设置搜索召回数据格式,及召回文档数
filter子句 string 用于设置过滤条件
sort 子句 string 用于设置文档排序条件(仅支持单字段int类型,仅限v3版API及SDK)
fetch_fields参数 string 用于设置召回哪些应用字段内容

查询参数用法

  • query:可以通过若干子句的组合来实现多样的搜索需求,query参数中各子句之间通过&&进行连接。

  • fetch_fields:返回文本数据大小对查询性能影响较大,建议只获取需要的字段。如果SDK/API中有配置该参数会覆盖控制台中对应功能配置。

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

  • disable:目前仅支持禁用 qp、summary、first_rank、second_rank 等参数功能。

    功能说明

    • 控制查询过程中关闭某些功能
    • 目前仅支持禁用查询分析、summary、first_rank、second_rank, 重查等参数功能

    参数格式:

    1. disable=function[;function]
    2. function=function_name[:function_param]
    • 例如:
      • 关闭查询分析, disable=qp
      • 关闭查询分析中的spell_check功能,disable=qp:spell_check
      • 关闭重查, 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编码函数。

  • category_prediction参数格式:

    参数格式:

    category_prediction=query:请填写查询词,name:请填写类目预测名称

  • raw_query:

    功能说明

    • 用于类目预测查询;只有查询词和raw_query的内容一致时,查询时,才会去查查询分析中配置的类目预测;
    • 用于类目预测等算法训练使用,因此,建议所有查询都设置该参数;
    • 一般建议设置为终端用户输入的原始查询词。

    参数格式:

    1. raw_query=URL_ENCODE(content)
    • content: 原始查询词
  • re_search:

    功能说明

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

    参数格式:

    1. re_search=strategy:threshold,params:total_hits#${COUNT}
    • COUNT: 触发重查时的total_hits上限。即当total hits少于COUNT时,会进行重查
    • example:
      • re_search=url_encode(strategy:threshold,params:total_hits#6)
  • 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 string 实际返回结果,包括查询耗时searchtime、引擎总结果数total、本次请求返回结果数num、本次查询最大返回结果数viewtotal、查询结果items、统计结果facet等信息
errors string 错误内容,error_message代表错误信息。error_code 对应含义参考 错误码 文档
  • searchtime:指引擎耗时,单位为秒。
  • total、viewtotal、num区别:total为一次查询(不考虑config子句)引擎中符合条件的结果数(在结果数较多情况下,该值会做优化),但考虑到性能及相关性,引擎最多会返回viewtotal个结果。如果需要翻页的话,要求start+hit必需要小于viewtotal,total一般用来做展示。num为本次查询请求(受限于config子句的start及hit)实际返回的条目,不会超过hit值。
  • items:包含查询召回数据信息,其中fields为搜索召回内容。
  • variableValue:表示自定义参数返回结果,如获取distance距离值,variableValue 节点只有在config子句formatxml或者fulljson时才能展现出来,json格式默认不展示。
  • sortExprValues: 表示对应文档排序分。
  • facet:用于存放Aggregate子句返回的信息。
  • array字段类型:通过json和fulljson格式返回,数据之间通过\t分割,如果通过xml格式返回,通过空格分割

Search示例

温馨提示:

此处省略了请求Header参数及编码等因素,正常查询请求串需参考V3版API签名机制进行编码。

  1. http://host/v3/openapi/apps/app_schema_demo/search?query=config=start:0,hit:20,format:fulljson,rerank_size:200&&query=name:'文档'&&sort=-id;-RANK&&filter=id>0&&distinct=&&aggregate=group_key:cate_id,agg_fun:count(),range:1,max_group:10,agg_sampler_threshold:1,agg_sampler_step:10&first_rank_name=default&second_rank_name=default&fetch_fields=id;name;phone&summary=summary_field:name,summary_len:100,summary_ellipsis:。。。,summary_snippet:2,summary_element_prefix:<em>,summary_element_postfix:</em>&qp=qp&disable=qp

成功返回

  1. {
  2. "status": "OK",
  3. "request_id": "150149633919672397225629",
  4. "result": {
  5. "searchtime": 0.005112,
  6. "total": 1,
  7. "num": 1,
  8. "viewtotal": 1,
  9. "items": [
  10. {
  11. "fields": {
  12. "id": "10",
  13. "name": "我是一条新<em>文档</em>的标题",
  14. "phone": "18312345678",
  15. "index_name": "app_schema_demo"
  16. },
  17. "property": {},
  18. "attribute": {},
  19. "variableValue": {},
  20. "sortExprValues": [
  21. "10",
  22. "10000.1354238242"
  23. ]
  24. }
  25. ],
  26. "facet": [
  27. {
  28. "key": "cate_id",
  29. "items": [
  30. {
  31. "value": "-9223372036854775808:1",
  32. "count": "1"
  33. }
  34. ]
  35. }
  36. ]
  37. },
  38. "errors": [],
  39. "tracer": "",
  40. "ops_request_misc":"%7B%22request%5Fid%22%3A%22156680563319723149105067%22%2C%22scm%22%3A%2220140713.115106..%22%7D"
  41. }

错误返回

  1. {
  2. "status": "OK",
  3. "request_id": "150149648719953661651650",
  4. "result": {
  5. "searchtime": 0.402225,
  6. "total": 1,
  7. "num": 0,
  8. "viewtotal": 0,
  9. "items": [
  10. {
  11. "fields": {
  12. "id": "10",
  13. "name": "我是一条新<em>文档</em>的标题",
  14. "phone": "18312345678",
  15. "index_name": "app_schema_demo"
  16. },
  17. "property": {},
  18. "attribute": {},
  19. "variableValue": {},
  20. "sortExprValues": [
  21. "10",
  22. "10000.1354238242"
  23. ]
  24. }
  25. ],
  26. "facet": []
  27. },
  28. "errors": [
  29. {
  30. "code": 1000,
  31. "message": "Server error."
  32. }
  33. ],
  34. "tracer": "",
  35. "ops_request_misc":"%7B%22request%5Fid%22%3A%22156680563319723149105067%22%2C%22scm%22%3A%2220140713.115106..%22%7D"
  36. }
  • 说明:status为FAIL表示既有error又无结果返回;但可能会出现既有error,又会有结果返回,此时status就为OK. 如出现1000 server error(搜索超时);或者2112(未指定精排中设置的索引)等报错时,仍可能有结果返回。

多应用联合查询

  1. 查询:查询请求会往指定的各个应用分别发送,即各个应用收到的查询语句完全相同(各个应用结构可以不同),因此必须保证该查询条件在各个应用上都适用。如果个别应用出现问题会报错,并返回其它应用结果。

    注意:包括first_formula_name、second_rank_name、summary等参数。

  2. 排序:如果查询语句中有包含sort子句,在召回各个应用结果后会再按照指定的sort子句进行二次排序。如果没有包含sort子句,则会对各个应用召回结果进行交叉展示。如果期望召回结果按照相关性(排序表达式)分数进行降序,可以在查询语句中显式指定sort=-RANK
  3. 查询计算:对每个应用分别计算一次查询请求。
  4. 应用个数:最多支持6个应用查询,超过限制直接报错无结果。

多应用联合查询须知

  • v3版API多应用查询,应用列表必须配置为各个应用ID,如果配置为各个应用名会报错。
  • v3版API多应用查询,各个应用之间的分隔符为,,而v2版API各个应用之间的分隔符为;
  • 拼接canonicalized_resource签名字符串参数时,该应用分隔符,也必须进行urlencode编码变成%2C
  • 拼接最终用于发送http查询请求串时,应用分隔符,必须进行urldecode解码,如果还是urlencode编码后的%2C会报错。
  • v3版API支持多应用查询功能,用户可以自己通过实现v3版API多应用联合查询鉴权使用该功能。
  1. 拼接canonicalized_resource签名字符串时,逗号需要进行urlencode编码。
  2. /v3/openapi/apps/120009914%2C120015980/search?省略查询参数
  3. 拼接最终用于发送http查询请求串时,逗号需要进行urldecode解码。
  4. /v3/openapi/apps/120009914,120015980/search?省略查询参数

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参数及编码等因素。

  1. 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

成功返回

  1. {
  2. "status": "OK",
  3. "request_id": "150150574119953661605242",
  4. "result": {
  5. "searchtime": 0.005029,
  6. "total": 1,
  7. "num": 0,
  8. "viewtotal": 1,
  9. "scroll_id": "eJxtUMtuhDAM/BrvOYQC5cABdulvRFFIirsm2TpBavv1Ndut1EMlS36NZ0Y2ZHMxbueceAjIuWCMnrPjRITLyfzZm83y9V QVGT8x80U3PxQNUqieVZV1/an4ItbTUBPSx5wgXqKdvOSbmuKR8ZYjGWWirB4tvToAiX7u3G2eCNK77vnz8GlGPAV6suKBeqxAn0OiTd7NGEnesspyoyFLF6hecn4JUKjVgp0K3FnkfMfIyPoDuYWegX9GeYOpicY9TG8gwOSuBL04X1 MMg3ROwCesLlG6X7a2o=",
  10. "items": [],
  11. "facet": []
  12. },
  13. "errors": [],
  14. "tracer": ""
  15. }

后续请求

注意:

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

  1. 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=

返回结果

  1. {
  2. "status": "OK",
  3. "request_id": "150150574119952551519970",
  4. "result": {
  5. "searchtime": 0.006293,
  6. "total": 1,
  7. "num": 1,
  8. "viewtotal": 1,
  9. "scroll_id": "eJxNT9tugzAM/RrznIRC4YEHaNlvRFFIhteQtE6Qtn39TNdJk2z5dnx8rIPJRdudcqKhl60Uir2Vp06ISv8b6s3QbZCVzpaCdp93XXBzg2wEW9MJ2dWq8q7YVXt0YckDLlBP0WyOw31N8YgYizZEnAUsjkx4VT4k8zexpjiNS/XYHX0NNkWP71BfVyxQjxLUxSfazFH4PYSPnCL3iMniDZq3jN98aFRCgGrZniy8/itkBHWGuYVeQH+B+QzTCUZ1NJ9gj4FVMfrQPr8Y+Hk+dgU14fIDVhtfTw==",
  10. "items": [
  11. {
  12. "fields": {
  13. "cate_id": "0",
  14. "float_arr": "0",
  15. "id": "1",
  16. "int_arr": "0",
  17. "literal_arr": "搜索",
  18. "name": "搜索",
  19. "phone": "18312345678",
  20. "index_name": "app_schema_demo"
  21. },
  22. "property": {},
  23. "attribute": {},
  24. "variableValue": {},
  25. "sortExprValues": [
  26. "1"
  27. ]
  28. }
  29. ],
  30. "facet": []
  31. },
  32. "errors": [],
  33. "tracer": ""
  34. }