OpenSearch:Search processing

URL

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

• $app_name: The application name. The Advanced and Standard Editions support multiple applications, so you must specify an application name to target a specific version. For example, you can use an application ID to access the search service of an offline application.

• The preceding URL does not include details such as request headers and encoding.

• The preceding URL omits the host address.

• For details about the query parameters in the preceding URL, including their definitions, usage, and examples, see the "Query parameters" section below.

Request protocol

HTTP

Request method

GET

Supported formats

JSON

Query parameters

For details on how to concatenate query parameters, see the V3 API signature mechanism.

Parameter	Type	Required	Default	Description
query	string	Yes		The search query. This parameter cannot be empty. The Industry Algorithm Edition supports empty search, which lets you search without specifying a search term in the query clause. To do this, pass an empty string'' as the search term. In empty search scenarios, a 2112 error is a display issue and does not affect the full result set. The query string is composed of clauses such as the config clause, query clause, sort clause, filter clause, aggregate clause, distinct clause, and kvpairs clause.
fetch_fields	string	No	All displayable fields.	Specifies which fields to return in the search results. Separate multiple fields with a semicolon;. This parameter corresponds to the default display fields feature in the console.
qp	string	No	Active rules	Specifies the query analysis rules to use. Separate multiple rules with a comma,.
disable	string	No		Disables the specified parameters.
first_rank_name	string	No	The default basic sort expression name	Specifies the name of the basic sort expression. You can specify only one name.
second_rank_name	string	No	The default service sort expression name	Specifies the name of the service sort expression. You can specify only one name.
user_id	string	No		A unique identifier for the end user. Set this parameter to one of the following, in descending order of priority: 1. The end user's persistent login ID. 2. The end user's mobile device IMEI.
abtest	string	No		This parameter is required to use the A/B test feature.
raw_query	string	No		Used for algorithm training, such as for category prediction. We recommend that you set this parameter for all queries.
search_strategy	string	No		Specifies the name of the query strategy for multi-path search.
re_search	string	No		Specifies the retry policy. Currently, policies can only be based on a total hits threshold.
biz	string	No		Describes the business context of the request, such as its origin or purpose.
summary	string	No	The default summary configuration	Configures the search result summary. You can specify fields for operations such as highlighting and truncation.
from_request_id	string	No		Specifies the source of the search request. If the query originates from a feature like search suggestions, popular queries, or query suggestions, set this parameter to the request_id of the original recommendation request. Linking this referral event allows you to calculate metrics, measure effectiveness, and gather data for optimizing these upstream features. For more information, see the Search Suggestions documentation.
vector_search	string	No
query clause	string	Yes		Specifies the search criteria.
config clause	string	No		Specifies the response format and the number of documents to return.
filter clause	string	No		Specifies the filtering criteria.
sort clause	string	No		Specifies the sorting conditions for documents. Only integer fields are supported. This clause is available only for the V3 API and SDKs.

Query parameter

• query: You can combine multiple clauses to meet various search requirements. Clauses in the query parameter are connected by &&. The Industry Algorithm Edition supports empty searches. If you pass an empty string '' as the search term in a query clause, the system returns the full results. A 2112 error may occur during an empty search, but this is a display issue and does not affect the actual search results.

• fetch_fields: To avoid impacting query performance, retrieve only necessary fields. If you configure this parameter in the SDK/API, it overrides the corresponding settings in the console.

• qp: If you configure this parameter in the SDK/API, it overrides the corresponding settings in the console.

Note: The Search Test page in the console shows the effect of qp and its results. This information is currently unavailable through the API or SDK.

• disable: Disables specified features during queries. You can disable features such as query analysis (qp), highlighting (summary), coarse-to-fine ranking (first_rank, second_rank), and re-search (re_search).

  Description

  • Specifies which features to disable during a query.

  • Currently supports disabling query analysis, highlighting, coarse-to-fine ranking, and re-search.

  Format:

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

  • Examples:

    • To disable query analysis, set disable=qp.

    • To disable the spell_check feature within query analysis, set disable=qp:spell_check. The format is disable=qp:$qp_processor_name. For more information, see QueryProcessor.

    • To disable re-search, set disable=re_search.

• first_rank_name: When set in an SDK or API call, this parameter overrides the corresponding setting in the console.

• second_rank_name: When set in an SDK or API call, this parameter overrides the corresponding setting in the console.

• user_id:

  • The user_id value must be URL-encoded in search requests.

  • The data statistics feature uses this parameter to calculate unique visitors (UVs).

  • If you have integrated data collection, ensure that the user_id used for reporting behavioral data matches the user_id in search requests.

• abtest: abtest=urlencode(scene_tag:urlencode(\$scene),flow_divider:urlencode(\$value)), where urlencode is the URL encoding function.

  • Set flow_divider to the end user's ID. If an ID is not available, you can use the end user's device ID or IP address. This parameter is required.

  • scene_tag: If you do not configure a scene tag in the console, the A/B test applies to traffic from all scenes, and you do not need to set scene_tag in the query.

• raw_query:

  Description

  • This parameter is used for category prediction. Category prediction, which is configured in query analysis, runs only when the query and raw_query parameters are identical.

  • This parameter is also used for algorithm training, such as for category prediction. For this reason, set this parameter in all queries.

  • Set this parameter to the original query entered by the end user.

  Format:

  raw_query=content

  • content: The original query.

• re_search:

  Description

  • Specifies the re-search strategy. Currently, only total_hits threshold-based strategies are supported.

  • This feature requires query analysis to be configured.

  • Re-search is not triggered if all terms from the tokenized query have the same entity recognition weight. To trigger a re-search, you must adjust the category weights in entity recognition.

  Format:

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

  • COUNT: The total_hits threshold. The system triggers a re-search if the number of total hits is less than COUNT.

  • Example:

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

• biz:

  Description

  • Specifies business information for the request, such as the business type of the traffic source.

    Format:

    biz=type:$TYPE

  • type: The type of traffic, which you can define. Use this value to distinguish traffic from different sources in reports.

  • Example:

    • biz=type:home_page

• vector_search:

  Parameter	Type	Default	Description
  namespace	list<string>		The namespace to search within.
  threshold	float		The minimum score threshold for vector retrieval.
  top_n	uint32		The number of top results to return from vector retrieval.
  search_params.qc_scan_ratio	float	0.01	A ratio used to calculate max_scan_num. The formula is: total number of documents * scan_ratio.
  search_params.hnsw_ef	uint32	500	Specifies the search precision. A larger value increases the number of scanned documents and improves the recall rate.

• vector_threshold:

• Description

  • Controls the vector score threshold for vector recall. The system returns only documents with a vector score lower than this threshold.

• Format

  vector_threshold=14.0

  • The value must be a float.

  • This parameter is optional. If omitted, the system uses a built-in threshold.

• Summary:

  • The summary_element_prefix and summary_element_postfix parameters must be set together.

  • The summary_element parameter interacts with the summary_element_prefix and summary_element_postfix parameters. The last one specified takes precedence.

  • Summary and highlighting cannot be configured separately.

  • Parameter settings made via the SDK or API override corresponding settings in the console.

Parameter	Type	Required	Value	Default	Description
summary_field	string	Yes			The field used to generate the summary.
summary_element	string	No		em	The highlight tag, specified as an HTML tag name without angle brackets.
summary_ellipsis	string	No		…	The ellipsis to append to truncated summaries.
summary_snippets	int	No		1	The number of summary snippets to return.
summary_len	string	No			The approximate length of each summary snippet.
summary_element_prefix	string	No			The prefix for highlighted terms. This must be a complete HTML tag, such as <em>.
summary_element_postfix	string	No			The suffix for highlighted terms. This must be a complete HTML tag, such as </em>.

Results

Parameter	Type	Description
status	string	The execution result. OK indicates success, and FAIL indicates failure. If the request fails, use the returned error code for troubleshooting.
request_id	string	The unique request ID for this query. Use it for troubleshooting.
result	JSON	Contains the search results and metadata. This object includes the search time (searchtime), the total matches found (total), the number of results returned (num), the maximum number of results that can be returned (viewtotal), the list of result items (items), and the facet results (facet).
errors	list	A list of errors. Each error object contains a code and a message. For descriptions of the error codes, see the Error Code document.

• searchtime: The engine's processing time for the query, in seconds.

• Differences between total, viewtotal, and num: total is the number of results in the engine that match a query, ignoring the config clause. This value is optimized for large result sets. However, for performance and relevance reasons, the engine returns a maximum of viewtotal results. For pagination, start+hit must be less than viewtotal. total is generally used for display. num is the actual number of items returned for the current query request, which is constrained by the start and hit parameters in the config clause, and will not exceed the hit value.

• compute_cost: An array that contains a single object. In this object, index_name represents the application ID, and value represents the LCUs consumed by the query.

• items: Contains the retrieved documents. Within each document object, the fields object contains the retrieved content.

• variableValue: Represents the result of a custom parameter, such as the distance value. This node is returned only when the format parameter in the config clause is set to xml or fulljson. The json format does not return this node by default.

• sortExprValues: Represents the document sorting score.

• facet: Contains the information returned by the aggregate clause.

• Array field type: In JSON and fulljson formats, values in an array are separated by a tab character (\t). In XML format, these values are separated by a space.

Search example

JSON response

{
 "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": "Men's Lapel Jacket, New 2021 Spring & Fall Style, Lightweight Casual Zip-Up Youth Outerwear",
     "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"
}

Error response

{
 "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 does not exist."
  }
 ],
 "status": "FAIL"
}

• Note: A status of FAIL indicates that an error occurred and no result was returned. However, an error can still occur even when the status is OK and results are returned. For example, you might still receive results despite a 1000 server error (search timeout) or a 2112 error (no index specified for fine ranking).

Query results troubleshooting

If the results returned by a search API call are not what you expect, such as inconsistent results, no results, or an unexpected result count, use the following methods to troubleshoot:

• Compare the query statements used by the API and the Search Test page: If the results from an API call differ from the results shown on the Search Test page in the console, compare the query statements actually sent by each, and check for differences in the query clause.

• Verify that the data exists: Query the data directly by its primary key id to confirm whether the data exists. This helps you rule out issues caused by data synchronization delays.

• Troubleshoot tokenization issues: If you suspect that tokenization is causing unexpected results, you can add custom tokenization intervention to optimize the results.

• Adjust vector query precision: For vector queries, if the results are not as expected, try rounding the query value to 5 decimal places and retry the query.

• Troubleshooting order when no results are returned:

  1. First check whether total in the response is 0. total represents the total number of results in the engine that match the query criteria. This value is optimized when the result count is large (see the description of the differences between total, viewtotal, and num in the "Response" section of this document).

  2. If total is not 0 but no items are returned, check the start and hit parameters in the config clause.

Scroll search

To optimize for speed, traditional search returns a limited number of the most relevant results. For example, the search method can recall a maximum of 5,000 documents. When you need more results for analysis, use the scroll API to retrieve a larger result set.

Supported clauses

• query clause

• config clause (the start parameter has no effect)

• filter clause

• sort clause (supports only a single INT type field; v3 API and SDK only)

URL

Initial query

/v3/openapi/apps/$app_name/search?search_type=scan&scroll=1m&[query parameters]

Subsequent query

/v3/openapi/apps/$app_name/search?scroll_id=$scroll_id&scroll=1m&[query-parameters]

• $app_name: The application name.

• The preceding URLs omit the application's host address.

• The two preceding scroll request URLs omit request headers, query parameters, and encoding. For a complete URL example, see the description below.

• The scroll method has limited support for many features. For a detailed list of limitations, see the notes below.

Request protocol

HTTP

HTTP request method

GET

Supported formats

JSON

Query parameters

Parameter	Type	Required	Value	Default	Description
scroll	string	Yes	week, day, hour, minute, second		Specifies how long to keep the search context alive for the next scroll request. You must set this parameter for each request. For example, use 1m for 1 minute. Supported time units: w (week), d (day), h (hour), m (minute), and s (second).
search_type	string	Yes	scan		Required for the initial query. For subsequent queries, omit this parameter and use the scroll_id to retrieve the next batch of results.
scroll_id	string	Yes			The initial request returns a scroll_id but no documents. For subsequent requests, pass the scroll_id from the previous response. Each subsequent response returns a new scroll_id and the next batch of matching documents.
query clause	string	Yes			Specifies the search criteria.
config clause	string	Yes			Specifies the response format and the number of documents to return.
filter clause	string	No			Specifies the filtering criteria.
sort clause	string	No			Specifies the sorting conditions for the documents. Supports sorting on a single integer field only. This clause is available only in the V3 API and SDKs.
fetch_fields parameter	string	No			Specifies which application fields to return in the results.

Response

Parameter	Type	Description
status	string	The request status. OK indicates success, and FAIL indicates failure. If a request fails, refer to the returned error code to troubleshoot the issue.
request_id	string	The request ID for the query, used primarily for troubleshooting.
result	string	The response payload, which includes the search time (searchtime), the total count (total), the number of results in this response (num), the maximum number of results for the query (viewtotal), the list of search results (items), facet results (facet), and the scroll ID (scroll_id).
errors	string	Contains error information, including the error message in the error_message field. For an explanation of each error_code, refer to the Error Codes documentation.

Scroll

First request

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

Successful response

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

Subsequent requests

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:'search'&&sort=+id&&filter=id>0&scroll=1m&scroll_id=eJxtUMtuhDAM/BrvOYQC5cABdulvRFFIirsm2TpBavv1Ndut1EMlS36NZ0Y2ZHMxbueceAjIuWCMnrPjRITLyfzZm83y9V+QVGT8x80U3PxQNUqieVZV1/an4ItbTUBPSx5wgXqKdvOSbmuKR8ZYjGWWirB4tvToAiX7u3G2eCNK77vnz8GlGPAV6suKBeqxAn0OiTd7NGEnesspyoyFLF6hecn4JUKjVgp0K3FnkfMfIyPoDuYWegX9GeYOpicY9TG8gwOSuBL04X1+MMg3ROwCesLlG6X7a2o=

Result

{
  "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": "search",
          "name": "search",
          "phone": "123****5678",
          "index_name": "app_schema_demo"
        },
        "property": {},
        "attribute": {},
        "variableValue": {},
        "sortExprValues": [
          "1"
        ]
      }
    ],
    "facet": []
  },
  "errors": [],
  "tracer": ""
}