系统提供了丰富的搜索语法以满足用户各种场景下的搜索需求。
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 | 是 | 搜索主体,不能为空。主要支持子句有 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可以赋给这个参数,通过关联这个引导事件,可以计算上游功能的各项指标,衡量使用效果,为优化功能提供依据。详见下拉提示产品文档。 | ||
query子句 | string | 是 | 用于设置搜索条件 | ||
config子句 | string | 否 | 用于设置搜索召回数据格式,及召回文档数 | ||
filter子句 | string | 否 | 用于设置过滤条件 | ||
sort 子句 | string | 否 | 用于设置文档排序条件(仅支持单字段int类型,仅限v3版API及SDK) |
查询参数用法
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:
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:
功能说明
控制向量召回文档的向量分数阈值,表示只召回向量分小于该值的文档。
参数格式:
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": ""
}