OpenSearch:Demo code for implementing scroll queries

Prerequisites

Before you begin, ensure that you have:

• An OpenSearch Industry Algorithm Edition application

• A RAM user with the required permissions granted to the AliyunServiceRoleForOpenSearch role. See AliyunServiceRoleForOpenSearch and Access authorization rules

• OpenSearch SDK for PHP V3 installed

Set up environment variables

Store your credentials as environment variables instead of hardcoding them in your source code.

Linux and macOS

export ALIBABA_CLOUD_ACCESS_KEY_ID=<access_key_id>
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<access_key_secret>

Replace <access_key_id> and <access_key_secret> with the AccessKey ID and AccessKey secret of your RAM user.

Windows

1. Create an environment variable file and add ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET with your AccessKey ID and AccessKey secret as values.

2. Restart Windows for the changes to take effect.

Create the configuration file

Create a header file (Config.inc.php) that initializes the OpenSearch client. All scroll query code imports this file.

<?php
// Import the autoloader.
require_once("../OpenSearch/Autoloader/Autoloader.php");
use OpenSearch\Client\OpenSearchClient;

// Read credentials from environment variables.
// Set these variables before running the code. See "Set up environment variables".
$accessKeyId = getenv('ALIBABA_CLOUD_ACCESS_KEY_ID');
$secret = getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET');

// The API endpoint for your region. Find this on the application details page in the OpenSearch console.
$endPoint = '<region endPoint>';

// The name of your OpenSearch application.
$appName = '<app name>';

// The name of your drop-down suggestion model.
$suggestName = '<suggest name>';

// Enable debug mode to log request and response details.
$options = array('debug' => true);

// Create the client.
$client = new OpenSearchClient($accessKeyId, $secret, $endPoint, $options);

Replace the following placeholders:

Run scroll queries

A complete scroll query flow has two stages:

• Stage 1: Start the scroll — Submit the initial query with a scroll expiry time. The response includes a scroll_id and initializes the scroll context. Use viewtotal from this response to determine how many subsequent batches to retrieve.

• Stage 2: Retrieve batches — Pass the scroll_id from the previous response to fetch the next batch of results. Repeat until you have retrieved all matching documents.

In OpenSearch SDK for PHP V3, scroll queries support sorting by a single field only, and that field must be of INT type. Sort by the primary key to prevent duplicate or skipped results when data is updated during the scroll.

The following code implements a complete scroll query loop:

<?php
header("Content-Type:text/html;charset=utf-8");

// Import the configuration file created in the previous step.
require_once("Config.inc.php");
use OpenSearch\Client\SearchClient;
use OpenSearch\Util\SearchParamsBuilder;

$searchClient = new SearchClient($client);

// Build the initial query parameters.
$params = new SearchParamsBuilder();

// Number of documents to return per scroll batch. No offset is required.
$params->setHits(1);

// The name of your OpenSearch application.
$params->setAppName('The application name');

// The search query.
$params->setQuery("name: 'Search'");

// Response format. Supported values: JSON, FULLJSON.
$params->setFormat("fulljson");

// Sort by the primary key (INT type, ascending).
// Sorting by the primary key prevents duplicate results when data is updated during the scroll.
$params->addSort('id', SearchParamsBuilder::SORT_INCREASE);

// Filter condition.
$params->setFilter('id>0');

// Fields to include in the response.
$params->setFetchFields(array('id', 'name', 'phone', 'int_arr', 'literal_arr', 'float_arr', 'cate_id'));

// Stage 1: Submit the initial query.
// Set the scroll expiry to 3 minutes. The first query does not require a scroll ID.
// The response returns a scroll_id for subsequent queries and viewtotal (total matching documents).
$params->setScrollExpire('3m');
$ret = $searchClient->execute($params->build())->result;

// Stage 2: Retrieve subsequent batches using the scroll ID from each previous response.
// viewtotal is the total number of matching documents returned by the initial query.
for ($i = 0; $i < json_decode($ret)->result->viewtotal; $i++) {
    // Pass the scroll ID from the previous response.
    $params->setScrollId(json_decode($ret)->result->scroll_id);

    // Fetch the next batch.
    $ret = $searchClient->execute($params->build())->result;

    // Display the results.
    print_r($ret . '<br/><br/>');
}

What's next

• AliyunServiceRoleForOpenSearch — Review the permissions required for the OpenSearch service role.

• Access authorization rules — Configure access control for your application.