Todos los productos
Search
Centro de documentos

OpenSearch:Código de ejemplo para implementar consultas con desplazamiento

Última actualización: Sep 04, 2026

Utilice las consultas con desplazamiento (scroll) para recuperar conjuntos de resultados grandes en lotes desde OpenSearch Industry Algorithm Edition. Cada consulta devuelve un ID de desplazamiento que se transmite a la siguiente solicitud, lo cual permite recorrer todos los documentos coincidentes sin omitir ni duplicar resultados.

Requisitos previos

Antes de empezar, asegúrese de contar con lo siguiente:

Configurar variables de entorno

Almacene sus credenciales como variables de entorno en lugar de insertarlas directamente en el código fuente.

Importante

Utilice un usuario de Resource Access Management (RAM) para llamar a las operaciones de la API en lugar de usar su cuenta raíz de Alibaba Cloud. El par de AccessKey de la cuenta raíz tiene acceso a todas las operaciones de la API, lo que genera un riesgo innecesario. Para crear un usuario de RAM y generar un par de AccessKey, consulte Create a RAM user y Create an AccessKey pair. Se recomienda no incluir su par de AccessKey en materiales fácilmente accesibles para otros, como el código del proyecto. De lo contrario, su par de AccessKey podría filtrarse y comprometer la seguridad de los recursos de su cuenta.

Linux y macOS

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

Reemplace <access_key_id> y <access_key_secret> con el ID de AccessKey y el secreto de AccessKey de su usuario de RAM.

Windows

  1. Cree un archivo de variables de entorno y agregue ALIBABA_CLOUD_ACCESS_KEY_ID y ALIBABA_CLOUD_ACCESS_KEY_SECRET con su ID de AccessKey y su secreto de AccessKey como valores.

  2. Reinicie Windows para que los cambios surtan efecto.

Crear el archivo de configuración

Cree un archivo de encabezado (Config.inc.php) que inicialice el cliente de OpenSearch. Todo el código de consulta con desplazamiento importa este archivo.

<?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);

Reemplace los siguientes marcadores de posición:

Marcador de posición

Descripción

<region endPoint>

Endpoint de la API para su región. Encuéntrelo en la página de detalles de la aplicación en la consola de OpenSearch.

<app name>

Nombre de su aplicación de OpenSearch.

<suggest name>

Nombre de su modelo de sugerencias desplegables.

Ejecutar consultas con desplazamiento

El flujo completo de una consulta con desplazamiento consta de dos etapas:

  • Etapa 1: Iniciar el desplazamiento — Envíe la consulta inicial con un tiempo de expiración del desplazamiento. La respuesta incluye un scroll_id e inicializa el contexto de desplazamiento. Utilice viewtotal de esta respuesta para determinar cuántos lotes posteriores recuperar.

  • Etapa 2: Recuperar lotes — Pase el scroll_id de la respuesta anterior para obtener el siguiente lote de resultados. Repita este proceso hasta recuperar todos los documentos coincidentes.

En OpenSearch SDK for PHP V3, las consultas con desplazamiento solo admiten ordenamiento por un único campo, y dicho campo debe ser de tipo INT. Ordene por la clave principal para evitar resultados duplicados u omitidos cuando se actualizan datos durante el desplazamiento.

A continuación se muestra el código que implementa un bucle completo de consulta con desplazamiento:

<?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/>');
}

Parámetros clave

Parámetro

Método

Valor en el ejemplo

Descripción

Tamaño del lote

setHits()

1

Número de documentos por lote. No se requiere desplazamiento (offset).

Consulta de búsqueda

setQuery()

"name: 'Search'"

Expresión de la consulta de búsqueda.

Formato de respuesta

setFormat()

"fulljson"

Formato de la respuesta. Valores compatibles: JSON, FULLJSON.

Campo de ordenamiento

addSort()

'id', SORT_INCREASE

Debe ser un único campo de tipo INT. Utilice la clave principal para evitar duplicados.

Filtro

setFilter()

'id>0'

Expresión de filtro aplicada a la consulta.

Campos a recuperar

setFetchFields()

array('id', 'name', ...)

Campos que se devolverán en cada documento.

Expiración del desplazamiento

setScrollExpire()

'3m'

Periodo de validez del ID de desplazamiento para la siguiente consulta, en minutos.

Pasos siguientes