Todos los productos
Search
Centro de documentos

OpenSearch:Demostración de consulta scroll

Última actualización: Sep 05, 2026

Las búsquedas regulares devuelven un máximo de 5,000 documentos. Para recuperar conjuntos de resultados más grandes (por ejemplo, para exportación masiva de datos, pipelines de análisis o tareas de aprendizaje automático), utilice consultas scroll.

Requisitos previos

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

  • Una aplicación de OpenSearch con datos indexados

  • Un par de AccessKey de un usuario de Resource Access Management (RAM) con los permisos necesarios. Consulte Create a RAM user y Access authorization rules

  • El SDK de OpenSearch para Java V4.0.0 agregado a las dependencias de su proyecto

Importante

Utilice el par de AccessKey de un usuario de RAM, no las credenciales raíz de su cuenta de Alibaba Cloud. El par de AccessKey raíz tiene acceso sin restricciones a todas las API. Mantenga su par de AccessKey fuera del código fuente y del control de versiones. Para obtener detalles sobre la configuración, consulte AliyunServiceRoleForOpenSearch.

Límites

Restricción

Detalle

Formatos de retorno compatibles

Únicamente fullJSON y JSON

Cláusulas no compatibles

aggregate, distinct y rank

Máximo de documentos por página scroll

500

Comportamiento del parámetro start

Se ignora; siempre comienza desde la posición 0

Configure variables de entorno

Almacene su par de AccessKey como variables de entorno antes de ejecutar el código de demostración.

Linux y macOS

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

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

Windows

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

  2. Reinicie Windows para que los cambios surtan efecto.

Para obtener detalles sobre cómo crear un par de AccessKey, consulte Create an AccessKey pair.

Funcionamiento de las consultas scroll

Una consulta scroll se ejecuta en tres fases:

  1. Solicitud inicial: envíe una consulta con un objeto DeepPaging para obtener el primer lote de resultados y un scroll ID.

  2. Solicitudes posteriores: pase el scroll ID de la respuesta anterior para recuperar el siguiente lote. Repita este proceso hasta que el conjunto de resultados esté vacío.

  3. Vencimiento: cada scroll ID tiene un periodo de validez (valor predeterminado: 1 minuto). Restablezca la vigencia antes de cada solicitud si necesita más tiempo.

Código de demostración

El siguiente ejemplo recupera todos los documentos que coinciden con name:'opensearch' y cate_id<=3, ordenados por id en orden descendente. Con 5 documentos por página y 25 documentos en total, el bucle se ejecuta 6 veces; la última iteración devuelve un conjunto de resultados vacío.

Todas las solicitudes utilizan el objeto DeepPaging para pasar el scroll ID y establecer el periodo de validez.

package com.aliyun.opensearch;

import com.aliyun.opensearch.OpenSearchClient;
import com.aliyun.opensearch.SearcherClient;
import com.aliyun.opensearch.sdk.dependencies.com.google.common.collect.Lists;
import com.aliyun.opensearch.sdk.dependencies.org.json.JSONObject;
import com.aliyun.opensearch.sdk.generated.OpenSearch;
import com.aliyun.opensearch.sdk.generated.commons.OpenSearchClientException;
import com.aliyun.opensearch.sdk.generated.commons.OpenSearchException;
import com.aliyun.opensearch.sdk.generated.search.*;
import com.aliyun.opensearch.sdk.generated.search.general.SearchResult;
import com.aliyun.opensearch.search.SearchParamsBuilder;
import java.nio.charset.Charset;

public class testScroll {

  // Scroll queries do not support the aggregate, distinct, or rank clause,
  // and support sorting by a single field only.
  private static String appName = "Name of the OpenSearch application that you want to manage";
  private static String host = "Endpoint of the OpenSearch API in your region";

  public static void main(String[] args) {
    // Read credentials from environment variables.
    // Configure the environment variables before running this code.
    String accesskey = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
    String secret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");

    System.out.println(
      String.format("file.encoding: %s", System.getProperty("file.encoding"))
    );
    System.out.println(
      String.format("defaultCharset: %s", Charset.defaultCharset().name())
    );

    // Initialize the client.
    OpenSearch openSearch = new OpenSearch(accesskey, secret, host);
    OpenSearchClient serviceClient = new OpenSearchClient(openSearch);
    SearcherClient searcherClient = new SearcherClient(serviceClient);

    // Configure the query: application name, page size, return format, and fields.
    Config config = new Config(Lists.newArrayList(appName));
    config.setStart(start); // The start parameter is ignored for scroll queries; position always starts at 0.
    config.setHits(5);      // Return 5 documents per page.
    config.setSearchFormat(SearchFormat.FULLJSON);
    config.setFetchFields(
      Lists.newArrayList("id", "name", "phone", "int_arr", "literal_arr", "float_arr", "cate_id")
    );

    SearchParams searchParams = new SearchParams(config);
    searchParams.setQuery("name:'opensearch'");
    searchParams.setFilter("cate_id<=3");

    Sort sorter = new Sort();
    sorter.addToSortFields(new SortField("id", Order.DECREASE)); // Sort by id, descending.
    searchParams.setSort(sorter);

    // Create a DeepPaging object to enable scroll queries.
    // Set the scroll ID validity period to 3 minutes (default: 1 minute).
    DeepPaging deep = new DeepPaging();
    deep.setScrollExpire("3m");
    searchParams.setDeepPaging(deep);

    SearchParamsBuilder paramsBuilder = SearchParamsBuilder.create(searchParams);

    // Step 1: Send the initial scroll query to get the first scroll ID.
    SearchResult searchResult;
    try {
      searchResult = searcherClient.execute(paramsBuilder);
      String result = searchResult.getResult();
      JSONObject obj = new JSONObject(result);

      // Step 2: Use the scroll ID from each response to fetch the next batch.
      // With 25 documents and 5 per page, the 6th iteration returns an empty result set.
      for (int i = 1; i <= 6; i++) {
        // When you run the first scroll query, a scroll ID is returned. Use this scroll ID to run the scroll query again.
        deep.setScrollId(
          new JSONObject(obj.get("result").toString())
            .get("scroll_id")
            .toString()
        );
        deep.setScrollExpire("3m"); // Reset the validity period before each request.
        searchResult = searcherClient.execute(paramsBuilder);
        result = searchResult.getResult();
        obj = new JSONObject(result);

        System.out.println("Results for Query No." + i + ": " + obj.get("result"));

        // Sleep 1 second between requests to stay within QPS limits.
        try {
          Thread.sleep(1000);
        } catch (InterruptedException e) {
          e.printStackTrace();
        }
      }
    } catch (OpenSearchException e) {
      e.printStackTrace();
    } catch (OpenSearchClientException e) {
      e.printStackTrace();
    }
  }
}
Compruebe los errores mediante el código y el mensaje de error en la respuesta, no mediante el campo de estado. Para obtener detalles sobre los errores, consulte Error codes .

Pasos siguientes