Scroll searches - OpenSearch - Alibaba Cloud Documentation Center

Scenarios

For regular searches, the purpose is to retrieve the most matched results in the shortest period of time possible. Therefore, the number of documents that can be contained in return results is limited. For example, the return results of a regular search cannot contain more than 5,000 documents. However, in some scenarios, you may need more results for analysis. In this case, you can use scroll searches to obtain more results.

Parameters

Request parameters

Parameter	Type	Required	Valid value	Description
scroll	STRING	Yes	You can set a value in units of weeks, days, hours, minutes, or seconds.	The validity period of the scroll ID to be returned for the next execution of the scroll search, in units of weeks (w), days (d), hours (h), minutes (m), or seconds (s). Example: 1m.
search_type	STRING	Yes	scan	The type of the scroll search. You need to specify this parameter only for the first execution of the scroll search. For the subsequent executions of the scroll search, you can specify the scroll_id parameter.
scroll_id	STRING	Yes		The ID that is returned for the scroll search. When you execute a scroll search for the first time, only a scroll ID is returned. To obtain search results, use this ID to execute the scroll search again. For subsequent executions of the scroll search, this ID is both required as a request parameter and returned as a response parameter.
fetch_fields	STRING			The fields to be returned in search results.

Response parameters

Parameter	Type	Description
status	STRING	The execution result of the request. Valid values: OK and FAIL. A value of OK indicates that the request is successful. A value of FAIL indicates that the request failed. In this case, troubleshoot errors based on the error code.
request_id	STRING	The ID of the request, which is used for troubleshooting.
result	STRING	The return results, which include the searchtime, total, num, viewtotal, items, facet, and scroll_id parameters.
errors	STRING	The error information, in which the error_message parameter indicates the error message. For more information about error codes, see Error codes.

Note

Return results of scroll searches support only the fullJSON and JSON formats.

Sample responses

Response for the first execution of a scroll search:

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

Response for a subsequent execution of the scroll search:

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

Usage notes

Scroll searches support sorting based on a single field of the INT type. To implement this feature, the version of the OpenSearch API and OpenSearch SDKs must be V3.
Scrolling is used to obtain all matched results of a search and does not support the aggregate and distinct clauses, rank clauses, and query analysis.
When you execute a scroll search, the start parameter that you specify in the config clause does not take effect. In this case, the default value 0 is used, which indicates you cannot skip any page. For scroll queries, the number of documents in each result set cannot exceed 500.
When you execute a scroll search for the first time, you need to specify the hit parameter. The number of documents returned in each result set is determined based on the hit parameter that you specify for the first time. If you modify the value of the hit parameter in subsequent scroll searches, the modification does not take effect.
When you run the first scroll query, a scroll ID is returned. To obtain document data, use this scroll ID to run the scroll query again.
To determine whether an error has occurred, use the error code and message instead of the status information. For more information, see Error codes.
If the error message of a returned scroll search is, the validity period of the scroll request expires. Modify the scroll parameter.

SDK demo code

Note

Note:

1. When you execute a scroll search, the start parameter that you specify in the config clause does not take effect. You can use the hit parameter in the config clause to specify the number of documents in each result set.

2. Scroll searches do not support the aggregate, distinct, and rank clauses. Scroll searches support sorting based on a single field of the INT type.

3. Scroll searches across applications are not supported.

4. If the value of the scroll_id parameter in a request is invalid, an error occurs.

5. Return results of scroll searches support only the fullJSON and JSON formats.

6. When you execute a scroll search for the first time, only a scroll ID is returned. To obtain document data, use this ID to execute the scroll search again.