Lors du traitement de grands ensembles de résultats pour des tâches volumineuses, telles que l'exportation de données, la reconstruction d'index ou l'exécution de jobs de machine learning par lots, les requêtes de défilement (scroll) vous permettent de récupérer tous les documents correspondants sans avoir à suivre manuellement les identifiants de défilement. La classe DeepPageingIterator du SDK OpenSearch pour Java V4.0.0 gère la rotation des identifiants de défilement en interne. Vous pouvez ainsi parcourir les pages à l'aide d'une boucle while standard.
Les requêtes de défilement sont conçues pour le traitement massif de données et non pour les requêtes utilisateur en temps réel. Elles ne prennent pas en charge les clauses aggregate, distinct ni rank, et n'autorisent le tri que sur un seul champ. Pour vérifier les erreurs, utilisez le code d'erreur et le message associé plutôt que les informations de statut. Pour obtenir la liste complète des codes d'erreur, consultez Codes d'erreur.
Prérequis
Avant de commencer, assurez-vous de disposer des éléments suivants :
Une application OpenSearch contenant au moins une table
L'endpoint de l'API OpenSearch dans votre région
Une paire AccessKey (AccessKey ID et AccessKey secret) pour l'authentification. Utilisez un utilisateur RAM plutôt que le compte racine. Consultez Créer un utilisateur RAM et Créer une paire AccessKey
Les permissions requises accordées au rôle
AliyunServiceRoleForOpenSearch. Consultez AliyunServiceRoleForOpenSearch et Règles d'autorisation d'accès
N'incluez pas votre paire AccessKey dans le code source ou tout autre document accessible à des tiers. Stockez vos identifiants dans des variables d'environnement.
Définir les variables d'environnement
Définissez 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'AccessKey ID et l'AccessKey secret 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 variables d'environnement, ajoutez les deux variables avec leurs valeurs, puis redémarrez Windows pour que les modifications prennent effet.
Implémenter des requêtes de défilement itératives
L'exemple suivant utilise DeepPageingIterator pour parcourir tous les résultats de la requête name:'opensearch', triés par id dans l'ordre décroissant. Chaque page renvoie 5 documents au format FULLJSON.
Le paramètre config.setStart() n'a aucun effet lors des requêtes de défilement. La position de départ par défaut 0 est toujours utilisée.
package com.aliyun.opensearch;
import com.aliyun.opensearch.sdk.dependencies.com.google.common.collect.Lists;
import com.aliyun.opensearch.sdk.generated.OpenSearch;
import com.aliyun.opensearch.sdk.generated.search.*;
import com.aliyun.opensearch.search.DeepPageingIterator;
import java.nio.charset.Charset;
public class testScrollIterator {
// Replace these values with your actual OpenSearch application details.
private static String appName = "<your-app-name>";
private static String tableName = "<your-table-name>";
private static String host = "<your-opensearch-api-endpoint>";
public static void main(String[] args) {
// Read credentials from environment variables — never hardcode them.
String accesskey = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
String secret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
// Log the file encoding for debugging purposes.
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 chain: OpenSearch → OpenSearchClient → SearcherClient.
OpenSearch openSearch = new OpenSearch(accesskey, secret, host);
OpenSearchClient serviceClient = new OpenSearchClient(openSearch);
SearcherClient searcherClient = new SearcherClient(serviceClient);
// Configure the config clause: application name, page size, response format, and fetch fields.
Config config = new Config(Lists.newArrayList(appName));
config.setStart(0); // Has no effect in scroll queries; the default value 0 is always used.
config.setHits(5); // Number of documents per page.
config.setSearchFormat(SearchFormat.FULLJSON); // Supported formats: JSON and FULLJSON.
config.setFetchFields(Lists.newArrayList("id", "name", "phone", "int_arr", "literal_arr", "float_arr", "cate_id"));
// Build the search query. Specifying multiple index fields in separate setQuery calls
// overwrites the previous query — include all index fields in a single setQuery call.
SearchParams searchParams = new SearchParams(config);
searchParams.setQuery("name:'opensearch'");
// Optional: add a filter condition.
// searchParams.setFilter("cate_id<=3");
// Scroll queries support sorting on a single field only.
Sort sorter = new Sort();
sorter.addToSortFields(new SortField("id", Order.DECREASE));
searchParams.setSort(sorter);
// Enable deep paging.
DeepPaging deep = new DeepPaging();
searchParams.setDeepPaging(deep);
// DeepPageingIterator manages scroll IDs automatically — no manual tracking needed.
DeepPageingIterator pagesIterator = new DeepPageingIterator(searcherClient, searchParams);
// Optional: set a custom iteration interval in milliseconds (default: 100 ms).
// Increase this value to reduce pressure on the OpenSearch service.
// pagesIterator.setPagingIntervals(80);
// Check for errors using the error code and message, not the status field.
try {
System.out.println("Starting iterative scroll query...");
while (pagesIterator.hasNext()) {
System.out.println(pagesIterator.next());
}
} catch (Exception ex) {
System.out.println("Error: " + ex.getMessage());
}
}
}
Espaces réservés
Remplacez les espaces réservés suivants par des valeurs réelles avant d'exécuter le code.
| Espace réservé | Description |
|---|---|
<your-app-name> |
Nom de votre application OpenSearch |
<your-table-name> |
Nom de la table à interroger |
<your-opensearch-api-endpoint> |
Endpoint de l'API OpenSearch pour votre région |
Étapes suivantes
Codes d'erreur — Recherchez les codes d'erreur renvoyés lors des requêtes de défilement.
AliyunServiceRoleForOpenSearch — Consultez le rôle de service et ses permissions requises.
Règles d'autorisation d'accès — Configurez les permissions pour les utilisateurs RAM.