Tous les produits
Search
Centre de documentation

OpenSearch:Exemple de requête par défilement

Dernière mise à jour :Aug 10, 2026

Une recherche classique renvoie au maximum 5 000 documents. Pour récupérer des jeux de résultats plus volumineux, par exemple pour l'exportation de données par lots, les pipelines d'analyse ou les tâches d'apprentissage automatique, utilisez plutôt les requêtes par défilement (scroll).

Prérequis

Avant de commencer, assurez-vous de disposer des éléments suivants :

  • Une application OpenSearch contenant des données indexées

  • Une paire AccessKey associée à un utilisateur RAM disposant des autorisations requises. Consultez les rubriques Create a RAM user et Access authorization rules.

  • Le SDK OpenSearch pour Java v4.0.0 ajouté aux dépendances de votre projet

Important

Utilisez la paire AccessKey d'un utilisateur RAM, et non les identifiants racine de votre compte Alibaba Cloud. La paire AccessKey racine offre un accès illimité à toutes les API. Ne stockez pas votre paire AccessKey dans le code source ni dans le système de contrôle de version. Pour plus de détails sur la configuration, consultez la rubrique AliyunServiceRoleForOpenSearch.

Limites

Contrainte Détail
Formats de retour pris en charge fullJSON et JSON uniquement
Clauses non prises en charge aggregate, distinct et rank
Nombre maximal de documents par page de défilement 500
Comportement du paramètre start Ignoré : la position de départ est toujours 0

Configuration des variables d'environnement

Stockez votre paire AccessKey sous forme de variables d'environnement avant d'exécuter l'exemple de code.

Linux et macOS

Remplacez <access_key_id> et <access_key_secret> par l'ID AccessKey et le secret AccessKey de votre utilisateur RAM.

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

Windows

  1. Créez un fichier de variables d'environnement et ajoutez-y les variables ALIBABA_CLOUD_ACCESS_KEY_ID et ALIBABA_CLOUD_ACCESS_KEY_SECRET en leur attribuant respectivement votre ID AccessKey et votre secret AccessKey comme valeurs.

  2. Redémarrez Windows pour que les modifications prennent effet.

Pour plus d'informations sur la création d'une paire AccessKey, consultez la rubrique Create an AccessKey pair.

Fonctionnement des requêtes par défilement

Une requête par défilement s'exécute en trois phases :

  1. Requête initiale : envoyez une requête incluant un objet DeepPaging afin d'obtenir le premier lot de résultats ainsi qu'un ID de défilement (scroll ID).

  2. Requêtes suivantes : transmettez l'ID de défilement reçu dans la réponse précédente pour récupérer le lot suivant. Répétez l'opération jusqu'à ce que le jeu de résultats soit vide.

  3. Expiration : chaque ID de défilement possède une durée de validité (par défaut, 1 minute). Réinitialisez cette durée avant chaque requête si vous avez besoin de plus de temps.

Exemple de code

L'exemple ci-dessous récupère tous les documents correspondant à name:'opensearch' avec cate_id<=3, triés par id dans l'ordre décroissant. Avec 5 documents par page et un total de 25 documents, la boucle s'exécute 6 fois ; la dernière itération renvoie un jeu de résultats vide.

Toutes les requêtes utilisent l'objet DeepPaging pour transmettre l'ID de défilement et définir la période de validité.

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();
    }
  }
}
Vérifiez la présence d'erreurs en examinant le code d'erreur et le message figurant dans la réponse, et non le champ status. Pour plus de détails sur les erreurs, consultez la rubrique Codes d'erreur .

Étapes suivantes