All Products
Search
Document Center

Scroll searches

Last Updated: Sep 09, 2021

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 search results.

Parameters

Request parameters

Parameter

Type

Required

Valid value

Default 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 first 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 search. Valid values: OK and FAIL. The value of OK indicates that the search is successfully executed. The value of FAIL indicates that the search fails to be executed. In this case, perform troubleshooting 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": "18312345678",
                    "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, distinct, and rank clauses.

  • 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 that the offset of return results is 0. For scroll searches, the number of documents in each result set must be in the range of [0,500].

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

  • To determine whether an error has occurred, use the error code and message instead of the status information. For more information, see the "Error codes" topic.

SDK demo code

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

Demo code related to scroll searches in OpenSearch SDK for Java:

Demo code for implementing regular scroll searches

Demo code for implementing iterative scroll searches

Demo code for implementing scroll searches in OpenSearch SDK for PHP:

Php Demo

API operations related to scroll searches

Initiate search requests