Tous les produits
Search
Centre de documentation

OpenSearch:Exemple de code pour implémenter les requêtes de défilement (scroll)

Dernière mise à jour :Aug 10, 2026

Les requêtes standard renvoient jusqu'à 5 000 documents. Lorsque l'ensemble des résultats dépasse cette limite, utilisez les requêtes de défilement pour récupérer tous les documents correspondants par lots.

Important

Les requêtes de défilement sont conçues pour la récupération massive de données et non pour la recherche en temps réel destinée aux utilisateurs finaux. Chaque lot est limité à 500 documents.

Limitations

  • Les requêtes de défilement ne prennent pas en charge les clauses aggregate, distinct ou rank.

  • Le paramètre start dans la clause config n'a aucun effet sur les requêtes de défilement. Le décalage (offset) est toujours égal à 0.

  • Chaque ensemble de résultats de défilement ne peut pas dépasser 500 documents.

  • Déterminez si une erreur s'est produite en vous basant sur le code d'erreur et le message, et non sur le champ status. Pour obtenir la liste complète des codes d'erreur, consultez la rubrique Codes d'erreur.

Prérequis

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

Important

Utilisez les identifiants de l'utilisateur RAM plutôt que ceux de votre compte Alibaba Cloud pour effectuer des appels API. N'intégrez jamais votre paire AccessKey dans le code source ou tout autre matériel accessible au public.

Définir les variables d'environnement

Définissez les variables d'environnement ALIBABA_CLOUD_ACCESS_KEY_ID et ALIBABA_CLOUD_ACCESS_KEY_SECRET avant d'exécuter l'exemple de code.

  • Linux et macOS — Exécutez les commandes suivantes. 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 — Créez un fichier de variable d'environnement, ajoutez-y ALIBABA_CLOUD_ACCESS_KEY_ID et ALIBABA_CLOUD_ACCESS_KEY_SECRET, définissez leurs valeurs avec votre ID AccessKey et votre secret AccessKey, puis redémarrez Windows pour prendre en compte les modifications.

Implémenter les requêtes de défilement à l'aide du SDK OpenSearch pour Java V3.1

Fonctionnement

  1. Soumettez une requête de recherche avec un objet DeepPaging joint. La première réponse inclut un ID de défilement (scroll ID) et le premier lot de résultats.

  2. Extrayez l'ID de défilement de la réponse et utilisez-le pour récupérer le lot suivant.

  3. Répétez l'opération jusqu'à ce que la réponse renvoie un ensemble de résultats vide.

Le paramètre d'expiration du défilement (par exemple, 3m ) spécifie la période de validité de l'ID de défilement utilisé par la prochaine requête de défilement. Valeur par défaut : 1m . Si vous ne souhaitez pas utiliser la valeur par défaut, vous devez définir une période de validité avant chaque exécution d'une requête de défilement.

Exemple de code

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,
    // but do support sorting by a single field.
    private static String appName = "The name of the OpenSearch application for which you want to implement scroll queries";
    private static String host = "The 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");

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

        // Create an OpenSearch object.
        OpenSearch openSearch = new OpenSearch(accesskey, secret, host);

        // Create an OpenSearchClient object.
        OpenSearchClient serviceClient = new OpenSearchClient(openSearch);

        // Create a SearcherClient object.
        SearcherClient searcherClient = new SearcherClient(serviceClient);

        // Configure the config clause: paging settings, data format, and application name.
        Config config = new Config(Lists.newArrayList(appName));

        // The start parameter has no effect on scroll queries. The offset is always 0.
        config.setStart(0);
        // Return 5 documents per batch.
        config.setHits(5);

        // Set the data format to FULLJSON. Supported formats: JSON, FULLJSON.
        config.setSearchFormat(SearchFormat.FULLJSON);

        // Specify the fields to return.
        config.setFetchFields(Lists.newArrayList("id", "name", "phone", "int_arr", "literal_arr", "float_arr", "cate_id"));
        // Note: Set rerank_size using the setReRankSize method of the Rank class.

        // Create a SearchParams object and set the search query.
        SearchParams searchParams = new SearchParams(config);

        // To query multiple index fields, specify all fields in a single setQuery call.
        // Separate setQuery calls overwrite each other.
        searchParams.setQuery("name:'opensearch'");

        // (Optional) Set a filter condition.
        // searchParams.setFilter("cate_id<=3");

        // Create a DeepPaging object to enable scroll queries.
        DeepPaging deep = new DeepPaging();
        // Specify a validity period for the scroll ID to be used by the next scroll query, in minutes.
        // Default value: 1m. In this example, the value is set to 3m.
        deep.setScrollExpire("3m");

        // Attach the DeepPaging object to the search parameters.
        searchParams.setDeepPaging(deep);

        // Create a SearchParamsBuilder for easier parameter configuration.
        SearchParamsBuilder paramsBuilder = SearchParamsBuilder.create(searchParams);

        // Run the scroll queries.
        // This example assumes 25 matching documents with 5 documents per batch,
        // so 5 batches return results and the 6th batch is empty.
        SearchResult searchResult;
        try {
            searchResult = searcherClient.execute(paramsBuilder);
            String result = searchResult.getResult();
            JSONObject obj = new JSONObject(result);

            for (int i = 1; i <= 6; i++) {
                // When you run the first scroll query, a scroll ID is returned.
                // To obtain document data, use this scroll ID to run the scroll query again.
                deep.setScrollId(new JSONObject(obj.get("result").toString()).get("scroll_id").toString());
                // Specify a validity period for the scroll ID to be used by the next scroll query, in minutes.
                // Default value: 1m. In this example, the value is set to 3m.
                // If you do not want to use the default value, you must set a validity period each time before you run a scroll query.
                deep.setScrollExpire("3m");

                searchResult = searcherClient.execute(paramsBuilder);
                result = searchResult.getResult();
                obj = new JSONObject(result);

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

                // Sleep for 1 second to avoid exceeding the queries per second (QPS) limit.
                try {
                    Thread.sleep(1000);
                } catch (InterruptedException e) {
                    e.printStackTrace();
                }
            }

        } catch (OpenSearchException e) {
            e.printStackTrace();
        } catch (OpenSearchClientException e) {
            e.printStackTrace();
        }
    }
}

Paramètres clés

Paramètre Description
appName Le nom de votre application OpenSearch
host L'endpoint de l'API OpenSearch pour votre région
config.setHits(n) Le nombre de documents par lot. Maximum : 500
deep.setScrollExpire("3m") La période de validité de l'ID de défilement utilisé par la prochaine requête de défilement. Par défaut : 1m. Définissez cette valeur avant chaque requête si vous ne souhaitez pas utiliser la valeur par défaut.
deep.setScrollId(id) L'ID de défilement renvoyé par la requête de défilement précédente

Étapes suivantes