OpenSearch:Search processing

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

• $app_name: The name of the application. The Premium and Standard Editions are multi-application versions. You must specify an application name to access an application that is in service.

• The preceding URL omits request headers, encoding, and other factors.

• The preceding URL omits the host address for accessing the application.

• For the definitions, usage, and examples of the query parameters in the preceding URL, see the **Query parameters** section below.

HTTP

GET

JSON

For details about how to concatenate query parameters, see the v3 API signing mechanism document.

Query parameter usage

• query: The `query` parameter can combine several clauses to meet diverse search requirements. Clauses within the `query` parameter are connected by &&.

• fetch_fields: The size of the returned text data has a significant performance impact. Retrieve only the required fields. If this parameter is configured in the SDK or API, it overwrites the corresponding configuration in the console.

• qp: If this parameter is configured in the SDK or API, it overwrites the corresponding configuration in the console.

Note: You can view the effects and results of `qp` on the search test page in the console. The API and SDKs do not currently expose this information.

• disable: You can use this parameter to disable features for parameters such as `qp`, `summary`, `first_rank`, `second_rank`, and `re_search`.

  Feature description

  • This parameter controls whether to disable certain features during a query.

  • You can disable features such as query analysis, highlighting, rough and fine sorting, and re-search.

  Parameter format:

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

  • Examples:

    • To disable query analysis, set `disable=qp`.

    • To disable the `spell_check` feature in query analysis, set `disable=qp:spell_check`.

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

• first_rank_name: If this parameter is configured in the SDK or API, it overwrites the corresponding configuration in the console.

• second_rank_name: If this parameter is configured in the SDK or API, it overwrites the corresponding configuration in the console.

• user_id:

  • When you set this parameter in a search request, the value of `user_id` must be URL-encoded.

• raw_query:

  Feature description

  • This parameter specifies the original search query entered by the end user.

  Parameter format:

  raw_query=content

  • content: The original search query.

• re_search:

  Feature description

  • This parameter sets the re-search policy. Currently, you can only set a policy based on the total hits threshold.

  Parameter format:

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

  • COUNT: The upper limit for `total_hits` that triggers a re-search. A re-search is performed if `total_hits` is less than COUNT.

  • Example:

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

• biz:

  Feature description

  • This parameter describes business information related to the request, such as the business type from which the request originated.

    Parameter format:

    biz=type:$TYPE

  • type: The type of traffic. You can define the value. You can later use this value to distinguish between different traffic sources in reports.

  • Example:

    • biz=type:home_page

• vector_threshold:

• summary:

  • The `summary_element_prefix` and `summary_element_postfix` parameters must be set at the same time.

  • The `summary_element` parameter and the (`summary_element_prefix`, `summary_element_postfix`) pair affect each other. A configuration that appears later overwrites one that appears earlier.

  • Currently, you cannot configure summary and highlighting separately.

  • If this parameter is configured in the SDK or API, it overwrites the corresponding configuration in the console.

Return result

• searchtime: The time, in seconds, that the engine consumed to process the request.

• Differences between `total`, `viewtotal`, and `num`: `total` is the number of results that meet the query conditions in the engine, without considering the `config` clause. This value is an estimate when there are many results and is generally used for display purposes. `viewtotal` is the maximum number of results that the engine returns for performance and relevance reasons. To page through results, `start` + `hit` must be less than `viewtotal`. `num` is the actual number of items returned for the current request. This value is limited by the `start` and `hit` parameters in the `config` clause and does not exceed the `hit` value.

• compute_cost: An array that contains a single map element. `index_name` is the application ID, and `value` is the number of Logic Compute Units (LCUs) consumed by the query.

• items: Contains the retrieved data. The fields parameter contains the content of the search results.

• variableValue: The return result of a custom parameter, such as a distance value. The `variableValue` node is displayed only if the format in the config clause is set to xml or fulljson. By default, this node is not displayed in `json` format.

• sortExprValues: The sorting score of the corresponding document.

• facet: Stores the information returned by the Aggregate clause.

• Array field type: If an array field is returned in `json` or `fulljson` format, the data is separated by `\t`. If it is returned in `xml` format, the data is separated by spaces.

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 jacket lapel 2021 spring and autumn new youth thin top casual zipper jacket",
     "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 not exist."
  }
 ],
 "status": "FAIL"
}

• Note: A `status` of `FAIL` indicates that an error occurred and no results are returned. However, in some cases, both an error and results can be returned. In these cases, the `status` is `OK`. For example, if a `1000 server error` (search timeout) or a `2112` error (index for fine sort not specified) occurs, results may still be returned.

A traditional search is designed to retrieve the most relevant results in the shortest possible time. Therefore, the number of search results is limited. For example, the search method can retrieve a maximum of 5,000 documents. In some scenarios, you may need to retrieve more results for analysis. You can use the scroll API to retrieve a larger number of results.

Supported clauses

• `query` clause.

• `config` clause. The `start` parameter is invalid in this clause.

• `filter` clause.

• `sort` clause. This clause only supports sorting by a single field of the `int` type and is limited to the v3 API and SDKs.

URL

Initial query

/v3/openapi/apps/$app_name/search?search_type=scan&scroll=1m&query_parameters

Subsequent queries

/v3/openapi/apps/$app_name/search?scroll_id=$scroll_id&scroll=1m&query_parameters

• $app_name: The name of the application.

• The preceding URL omits the host address for accessing the application.

• The preceding scroll request URLs omit request headers, query parameter content, encoding, and other factors. For a complete scroll request URL, see the example below.

• The scroll method has limited functionality and does not support most features. For more information about specific limitations, see the notes at the bottom.

HTTP

GET

JSON

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=

Return value

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