Agrégation - Tablestore - Centre de documentation Alibaba Cloud

Configuration de la recherche

Le type de request.searchQuery est SearchQuery. Le tableau suivant décrit les paramètres liés à l'agrégation.

Nom

Type

Description

query (obligatoire)

Query

Condition de recherche qui détermine la portée de l'agrégation. Pour agréger toutes les lignes d'un index de recherche, utilisez MatchAllQuery.

aggregationList (facultatif)

List<Aggregation>

Configurations d'agrégation de métriques. Configurez au moins l'un de ces paramètres ou groupByList.

groupByList (facultatif)

List<GroupBy>

Configurations de regroupement. Configurez au moins l'un de ces paramètres ou aggregationList.

limit (facultatif)

Integer

Nombre maximal de lignes à renvoyer. Valeur par défaut : 10. Définissez ce paramètre sur 0 si vous avez uniquement besoin des résultats d'agrégation.

offset (facultatif)

Integer

Position de la ligne à partir de laquelle la recherche commence. Valeur par défaut : 0.

sort (facultatif)

Sort

Ordre de tri des résultats de la recherche. Ce paramètre ne modifie pas la portée des agrégations de métriques ni des regroupements standards.

trackTotalCount (facultatif)

int

Nombre maximal attendu de correspondances à compter. Si ce paramètre est défini sur TRACK_TOTAL_COUNT, vous pouvez obtenir le nombre total de correspondances de la recherche depuis SearchResponse.totalCount.

filter (facultatif)

SearchFilter

Filtre appliqué aux résultats de query. Les agrégations s'effectuent sur les résultats filtrés.

Agrégations de métriques

Ajoutez les objets de paramètres suivants à request.searchQuery.aggregationList[]. aggName identifie le résultat correspondant et doit être unique dans une requête.

MinAggregation, MaxAggregation et AvgAggregation

Nom

Type

Description

aggName (obligatoire)

String

Nom de l'agrégation.

fieldName (obligatoire)

String

Nom du champ d'agrégation. Les champs Long, Double et Date sont pris en charge.

missing (facultatif)

ColumnValue

Valeur utilisée si fieldName est absent. Si ce paramètre n'est pas configuré, les lignes où le champ est manquant sont ignorées.

SumAggregation

Nom

Type

Description

aggName (obligatoire)

String

Nom de l'agrégation.

fieldName (obligatoire)

String

Nom du champ d'agrégation. Les champs Long et Double sont pris en charge.

missing (facultatif)

ColumnValue

Valeur utilisée dans la somme si fieldName est absent. Si ce paramètre n'est pas configuré, les lignes où le champ est manquant sont ignorées.

CountAggregation

Nom

Type

Description

aggName (obligatoire)

String

Nom de l'agrégation.

fieldName (obligatoire)

String

Champ dont les valeurs non nulles sont comptées. Les champs Long, Double, Boolean, Keyword, Date, IP et Geo-point sont pris en charge. Les lignes d'une colonne sparse ne contenant pas le champ ne sont pas comptées.

Pour compter toutes les correspondances de la recherche, configurez trackTotalCount dans SearchQuery et lisez SearchResponse.totalCount. Pour compter toutes les lignes d'un index de recherche, utilisez MatchAllQuery.

DistinctCountAggregation

Nom

Type

Description

aggName (obligatoire)

String

Nom de l'agrégation.

fieldName (obligatoire)

String

Champ dont les valeurs distinctes sont comptées. Les champs Long, Double, Boolean, Keyword, Date, IP et Geo-point sont pris en charge.

missing (facultatif)

ColumnValue

Valeur utilisée pour le compte distinct si fieldName est absent. Si ce paramètre n'est pas configuré, les lignes où le champ est manquant sont ignorées.

PercentilesAggregation

Nom

Type

Description

aggName (obligatoire)

String

Nom de l'agrégation.

fieldName (obligatoire)

String

Nom du champ d'agrégation. Les champs Long, Double et Date sont pris en charge.

percentiles (obligatoire)

List<Double>

Percentiles à calculer, tels que 25.0, 50.0, 90.0 et 99.0.

missing (facultatif)

ColumnValue

Valeur utilisée dans le calcul des percentiles si fieldName est absent. Si ce paramètre n'est pas configuré, les lignes où le champ est manquant sont ignorées.

TopRowsAggregation

Utilisez TopRowsAggregation comme sous-agrégation d'un regroupement.

Nom

Type

Description

aggName (obligatoire)

String

Nom de l'agrégation.

limit (facultatif)

Integer

Nombre maximal de lignes à renvoyer pour chaque groupe. Valeur par défaut : 1.

sort (facultatif)

Sort

Ordre de tri des lignes dans un groupe.

Le paramètre request.columnsToGet contrôle les colonnes d'attribut renvoyées. Pour renvoyer directement les colonnes d'attribut depuis l'index de recherche, stockez les champs lors de la création de l'index. Si aucune colonne n'est spécifiée, seules les clés primaires sont renvoyées.

Regroupements

Ajoutez les objets de paramètres suivants à request.searchQuery.groupByList[]. groupByName identifie le résultat correspondant et doit être unique dans une requête.

GroupByField

Nom

Type

Description

groupByName (obligatoire)

String

Nom du regroupement.

fieldName (obligatoire)

String

Nom du champ de regroupement. Les champs Long, Double, Boolean, Keyword, Date et IP sont pris en charge.

size (facultatif)

Integer

Nombre de groupes à renvoyer. Valeur par défaut : 10. Valeur maximale : 2000.

minDocCount (facultatif)

Long

Nombre minimal de lignes dans un groupe. Les groupes contenant moins de lignes ne sont pas renvoyés.

groupBySorters (facultatif)

List<GroupBySorter>

Règles de tri des groupes. Par défaut, les groupes sont triés par nombre de lignes dans l'ordre décroissant. Plusieurs règles s'appliquent dans l'ordre dans lequel elles sont ajoutées.

subAggregations (facultatif)

List<Aggregation>

Agrégations de métriques calculées au sein de chaque groupe.

subGroupBys (facultatif)

List<GroupBy>

Regroupements appliqués au sein de chaque groupe parent.

groupBySorters[] prend en charge les valeurs suivantes.

Valeur

Description

groupKeySortInAsc

Trie les groupes par clé dans l'ordre lexicographique croissant.

groupKeySortInDesc

Trie les groupes par clé dans l'ordre lexicographique décroissant.

rowCountSortInAsc

Trie les groupes par nombre de lignes dans l'ordre croissant.

rowCountSortInDesc

Trie les groupes par nombre de lignes dans l'ordre décroissant. Il s'agit de la valeur par défaut.

subAggSortInAsc

Trie les groupes par la valeur d'une sous-agrégation spécifiée dans l'ordre croissant.

subAggSortInDesc

Trie les groupes par la valeur d'une sous-agrégation spécifiée dans l'ordre décroissant.

GroupByComposite

Nom

Type

Description

groupByName (obligatoire)

String

Nom du regroupement.

sources (obligatoire)

List<GroupBy>

Sources de regroupement pour plusieurs champs. Jusqu'à 32 champs sont pris en charge. Les sources peuvent être GroupByField, GroupByHistogram ou GroupByDateHistogram. Une source de champ peut spécifier son nom, son champ et son ordre de tri. Une source d'histogramme numérique peut également spécifier un intervalle, et une source d'histogramme de date peut spécifier un fuseau horaire. Une source ne peut être triée que par clé. L'ordre par défaut est décroissant. Si un champ est absent, la clé correspondante est null.

nextToken (facultatif)

String

Jeton de pagination pour la page suivante de groupes. Omettez ce paramètre dans la première requête. Si nextToken dans la réponse n'est pas vide, utilisez la valeur telle quelle dans la requête suivante.

size (facultatif)

Integer

Nombre de groupes à renvoyer. Valeur par défaut : 10. Valeur maximale : 2000. Dans la plupart des cas, utilisez ce paramètre pour limiter le nombre de groupes.

suggestedSize (facultatif)

Integer

Limite souple pour les intégrations à haut débit avec des moteurs de calcul tels que Spark et Presto. Vous pouvez définir ce paramètre sur -1 ou sur une valeur supérieure à la limite du serveur. Le nombre réel renvoyé est min(suggestedSize, server-side group limit, total groups). Ne configurez pas ce paramètre et size dans la même requête.

subAggregations (facultatif)

List<Aggregation>

Sous-agrégations.

subGroupBys (facultatif)

List<GroupBy>

Sous-regroupements. GroupByComposite ne peut pas lui-même être utilisé comme sous-regroupement.

Remarque

Le SDK Tablestore pour Java représente nextToken sous forme de chaîne. Si vous persistez ou transférez le jeton, ne modifiez pas son contenu.

GroupByRange

Nom

Type

Description

groupByName (obligatoire)

String

Nom du regroupement.

fieldName (obligatoire)

String

Nom du champ de regroupement. Les champs Long et Double sont pris en charge.

ranges (obligatoire)

List<Range>

Plages. Chaque plage est fermée à gauche et ouverte à droite : [from, to). Vous pouvez utiliser Double.MIN_VALUE et Double.MAX_VALUE comme limites.

subAggregations (facultatif)

List<Aggregation>

Sous-agrégations.

subGroupBys (facultatif)

List<GroupBy>

Sous-regroupements.

GroupByGeoDistance

Nom

Type

Description

groupByName (obligatoire)

String

Nom du regroupement.

fieldName (obligatoire)

String

Nom du champ de regroupement. Seuls les champs Geo-point sont pris en charge.

origin (obligatoire)

GeoPoint

Point central. Les paramètres du constructeur sont la latitude suivie de la longitude. La plage de latitude est [-90,+90] et la plage de longitude est [-180,+180].

ranges (obligatoire)

List<Range>

Plages de distance en mètres. Chaque plage est fermée à gauche et ouverte à droite : [from, to).

subAggregations (facultatif)

List<Aggregation>

Sous-agrégations.

subGroupBys (facultatif)

List<GroupBy>

Sous-regroupements.

GroupByFilter

Nom

Type

Description

groupByName (obligatoire)

String

Nom du regroupement.

filters (obligatoire)

List<Query>

Filtres. Les résultats sont renvoyés dans l'ordre dans lequel les filtres sont ajoutés.

subAggregations (facultatif)

List<Aggregation>

Sous-agrégations.

subGroupBys (facultatif)

List<GroupBy>

Sous-regroupements.

GroupByHistogram

Nom

Type

Description

groupByName (obligatoire)

String

Nom du regroupement.

fieldName (obligatoire)

String

Nom du champ de regroupement. Les champs Long et Double sont pris en charge.

interval (obligatoire)

ColumnValue

Intervalle de l'histogramme.

fieldRange (facultatif)

FieldRange

Plage d'agrégation, qui contient min et max. La valeur de (max-min)/interval ne peut pas dépasser 2000.

offset (facultatif)

ColumnValue

Décalage des limites des compartiments par rapport au point de départ par défaut.

minDocCount (facultatif)

Long

Nombre minimal de lignes dans un compartiment. Les compartiments contenant moins de lignes ne sont pas renvoyés.

missing (facultatif)

ColumnValue

Valeur utilisée dans l'histogramme si fieldName est absent. Si ce paramètre n'est pas configuré, les lignes où le champ est manquant sont ignorées.

groupBySorters (facultatif)

List<GroupBySorter>

Règles de tri des compartiments.

subAggregations (facultatif)

List<Aggregation>

Sous-agrégations.

subGroupBys (facultatif)

List<GroupBy>

Sous-regroupements.

GroupByDateHistogram

Important

L'agrégation par histogramme de date est prise en charge par le SDK Tablestore pour Java 5.16.1 et versions ultérieures. Le type de champ Date pour les index de recherche est pris en charge par le SDK Tablestore pour Java 5.13.9 et versions ultérieures. Pour plus d'informations sur les versions, consultez Historique des versions du SDK Tablestore pour Java.

Nom

Type

Description

groupByName (obligatoire)

String

Nom du regroupement.

fieldName (obligatoire)

String

Nom du champ de regroupement. Seuls les champs Date sont pris en charge.

interval (obligatoire)

DateTimeValue

Intervalle de date ou d'heure, composé d'une valeur et d'un DateTimeUnit.

fieldRange (facultatif)

FieldRange

Plage d'agrégation, qui contient min et max. La valeur de (max-min)/interval ne peut pas dépasser 2000.

minDocCount (facultatif)

Long

Nombre minimal de lignes dans un compartiment. Les compartiments contenant moins de lignes ne sont pas renvoyés.

missing (facultatif)

ColumnValue

Valeur de date utilisée dans l'histogramme si fieldName est absent. Si ce paramètre n'est pas configuré, les lignes où le champ est manquant sont ignorées.

timeZone (facultatif)

String

Fuseau horaire au format +hh:mm ou -hh:mm, tel que +08:00. Si le format du champ Date n'inclut pas d'informations sur le fuseau horaire, configurez ce paramètre pour éviter un décalage horaire dans les résultats d'agrégation.

groupBySorters (facultatif)

List<GroupBySorter>

Règles de tri des compartiments.

subAggregations (facultatif)

List<Aggregation>

Sous-agrégations.

subGroupBys (facultatif)

List<GroupBy>

Sous-regroupements.

GroupByGeoGrid

Nom

Type

Description

groupByName (obligatoire)

String

Nom du regroupement.

fieldName (obligatoire)

String

Nom du champ de regroupement. Seuls les champs Geo-point sont pris en charge.

precision (obligatoire)

GeoHashPrecision

Précision de la grille GeoHash. Les valeurs vont de GHP_5009KM_4992KM_1, soit environ 5 009 km × 4 992 km, à GHP_37MM_19MM_12, soit environ 37 mm × 19 mm. Un suffixe plus grand spécifie une grille plus petite.

size (facultatif)

Integer

Nombre de groupes de grille à renvoyer.

subAggregations (facultatif)

List<Aggregation>

Sous-agrégations.

subGroupBys (facultatif)

List<GroupBy>

Sous-regroupements.

Prérequis

Installez le SDK Tablestore pour Java et initialisez un client.

Fonctionnement

Une fois la recherche d'index terminée, l'agrégation calcule des métriques ou regroupe toutes les lignes correspondantes. Les agrégations de métriques calculent le minimum, le maximum, la somme, la moyenne, le nombre, le nombre distinct ou les percentiles des champs. Les regroupements classent les lignes par valeurs de champ, par plusieurs champs, par plages numériques, par distances géographiques, par filtres, par intervalles numériques, par intervalles de date ou par grilles géographiques. Vous pouvez également ajouter des agrégations de métriques ou des regroupements au sein d'un groupe.

Catégorie

Type de configuration

Description

Agrégation de métriques

MinAggregation

Renvoie la valeur minimale d'un champ, similaire à MIN en SQL.

Agrégation de métriques

MaxAggregation

Renvoie la valeur maximale d'un champ, similaire à MAX en SQL.

Agrégation de métriques

SumAggregation

Renvoie la somme d'un champ numérique, similaire à SUM en SQL.

Agrégation de métriques

AvgAggregation

Renvoie la valeur moyenne d'un champ, similaire à AVG en SQL.

Agrégation de métriques

CountAggregation

Renvoie le nombre de lignes dans lesquelles un champ spécifié a une valeur, similaire à COUNT(field) en SQL.

Agrégation de métriques

DistinctCountAggregation

Renvoie le nombre de valeurs distinctes dans un champ, similaire à COUNT(DISTINCT field) en SQL.

Agrégation de métriques

PercentilesAggregation

Renvoie un ou plusieurs percentiles d'un champ.

Agrégation de métriques

TopRowsAggregation

Renvoie les premières lignes de chaque groupe selon un ordre spécifié.

Regroupement

GroupByField

Regroupe les lignes par la valeur d'un champ.

Regroupement

GroupByComposite

Regroupe les lignes par plusieurs champs et prend en charge les jetons de pagination.

Regroupement

GroupByRange

Regroupe les lignes par plages numériques.

Regroupement

GroupByGeoDistance

Regroupe les lignes par plages de distance à partir d'un point central.

Regroupement

GroupByFilter

Regroupe les lignes par plusieurs filtres.

Regroupement

GroupByHistogram

Crée un histogramme en utilisant des intervalles numériques fixes.

Regroupement

GroupByDateHistogram

Crée un histogramme en utilisant des intervalles de date ou d'heure fixes.

Regroupement

GroupByGeoGrid

Regroupe les lignes par grille GeoHash.

Important

Le tri et l'agrégation doivent être activés pour un champ d'index de recherche utilisé dans une agrégation. Les types de champs pris en charge varient selon le type d'agrégation. Pour plus d'informations sur les types de champs d'index de recherche et leurs mappages avec les types de champs de table de données, consultez Types de données.
Les agrégations s'effectuent sur les correspondances de la recherche. Une requête contenant des agrégations est plus complexe qu'une requête interrogeant uniquement des lignes. Si vous n'avez pas besoin de lignes dans la réponse, définissez limit sur 0.
Le compte distinct, les percentiles et les regroupements par champ utilisent des calculs approximatifs. Un compte distinct inférieur à 10 000 est proche d'une valeur exacte. Pour un compte distinct de 100 millions, l'erreur est d'environ 2 %. Les percentiles proches des extrémités sont généralement plus précis. Par exemple, P1 et P99 sont généralement plus précis que P50. Le calcul parallèle des regroupements par champ peut également introduire une petite erreur.
Vous pouvez combiner plusieurs agrégations. Un grand nombre d'agrégations ou un nesting profond augmente la complexité de la requête et peut augmenter la latence. Pour connaître les limites de nesting, consultez Limites des index de recherche.

Appelez search pour interroger les données. Configurez SearchQuery.aggregationList pour les agrégations de métriques et SearchQuery.groupByList pour les regroupements.

SearchResponse search(SearchRequest request)

L'exemple suivant interroge toutes les lignes d'un index de recherche, calcule le minimum, le maximum, la somme, la moyenne, le nombre, le nombre de catégories distinctes et le P50 des prix, et regroupe les lignes par catégorie.

SearchQuery searchQuery = SearchQuery.newBuilder()
        .query(QueryBuilders.matchAll())
        .limit(0)
        .addAggregation(AggregationBuilders.min("min_price", "price"))
        .addAggregation(AggregationBuilders.max("max_price", "price"))
        .addAggregation(AggregationBuilders.sum("sum_price", "price"))
        .addAggregation(AggregationBuilders.avg("avg_price", "price"))
        .addAggregation(AggregationBuilders.count("price_count", "price"))
        .addAggregation(AggregationBuilders.distinctCount(
                "category_count", "category"))
        .addAggregation(AggregationBuilders.percentiles(
                "price_percentiles", "price")
                .percentiles(Arrays.asList(50.0)))
        .addGroupBy(GroupByBuilders.groupByField(
                "category_group", "category").size(10))
        .build();

SearchRequest request =
        new SearchRequest("example_table", "example_index", searchQuery);
SearchResponse response = client.search(request);

AggregationResults aggregationResults = response.getAggregationResults();
System.out.println(aggregationResults
        .getAsMinAggregationResult("min_price").getValue());
System.out.println(aggregationResults
        .getAsMaxAggregationResult("max_price").getValue());
System.out.println(aggregationResults
        .getAsSumAggregationResult("sum_price").getValue());
System.out.println(aggregationResults
        .getAsAvgAggregationResult("avg_price").getValue());
System.out.println(aggregationResults
        .getAsCountAggregationResult("price_count").getValue());
System.out.println(aggregationResults
        .getAsDistinctCountAggregationResult("category_count").getValue());
System.out.println(aggregationResults
        .getAsPercentilesAggregationResult("price_percentiles")
        .getPercentilesAggregationItems());

GroupByFieldResult groupResult = response.getGroupByResults()
        .getAsGroupByFieldResult("category_group");
for (GroupByFieldResultItem item :
        groupResult.getGroupByFieldResultItems()) {
    System.out.println(item.getKey() + ": " + item.getRowCount());
}

Réponse

La méthode search renvoie SearchResponse. Le tableau suivant décrit les champs liés à l'agrégation.

Nom

Type

Description

aggregationResults

AggregationResults

Résultats de l'agrégation de métriques. Appelez getAggregationResults() pour obtenir la valeur, et utilisez un nom d'agrégation pour obtenir un type de résultat spécifique.

groupByResults

GroupByResults

Résultats du regroupement. Appelez getGroupByResults() pour obtenir la valeur, et utilisez un nom de regroupement pour obtenir un type de résultat spécifique.

totalCount

long

Nombre de correspondances de la recherche. Appelez getTotalCount() pour obtenir la valeur. La valeur dépend de trackTotalCount.

isAllSuccess

boolean

Indique si toutes les partitions d'index ont été interrogées. Appelez isAllSuccess() pour obtenir la valeur. Si ce champ est false, les résultats d'agrégation peuvent être incomplets.

Résultats d'agrégation de métriques

Type de configuration

Type de résultat

Champ de résultat et accesseur

MinAggregation

MinAggregationResult

value est un double. Appelez getAsMinAggregationResult(aggName).getValue().

MaxAggregation

MaxAggregationResult

value est un double. Appelez getAsMaxAggregationResult(aggName).getValue().

SumAggregation

SumAggregationResult

value est un double. Appelez getAsSumAggregationResult(aggName).getValue().

AvgAggregation

AvgAggregationResult

value est un double. Appelez getAsAvgAggregationResult(aggName).getValue().

CountAggregation

CountAggregationResult

value est un long. Appelez getAsCountAggregationResult(aggName).getValue().

DistinctCountAggregation

DistinctCountAggregationResult

value est un long. Appelez getAsDistinctCountAggregationResult(aggName).getValue().

PercentilesAggregation

PercentilesAggregationResult

percentilesAggregationItems est une List<PercentilesAggregationItem>. Appelez getAsPercentilesAggregationResult(aggName).getPercentilesAggregationItems(). Chaque élément contient key et value.

TopRowsAggregation

TopRowsAggregationResult

rows est une List<Row>. Appelez getAsTopRowsAggregationResult(aggName).getRows().

Résultats de regroupement

Type de configuration

Type de résultat

Champs de résultat principaux

GroupByField

GroupByFieldResult

groupByFieldResultItems. Chaque élément contient key, rowCount, subAggregationResults et subGroupByResults.

GroupByComposite

GroupByCompositeResult

sourceNames, groupByCompositeResultItems et nextToken. Les positions des keys dans chaque élément correspondent à sourceNames.

GroupByRange

GroupByRangeResult

groupByRangeResultItems. Chaque élément contient from, to et rowCount.

GroupByGeoDistance

GroupByGeoDistanceResult

groupByGeoDistanceResultItems. Chaque élément contient la distance from, to et rowCount.

GroupByFilter

GroupByFilterResult

groupByFilterResultItems. Chaque élément contient rowCount, et l'ordre des éléments correspond à l'ordre des filtres.

GroupByHistogram

GroupByHistogramResult

groupByHistogramItems. Chaque élément contient le début du compartiment key et le nombre de lignes value.

GroupByDateHistogram

GroupByDateHistogramResult

groupByDateHistogramItems. Chaque élément contient l'horodatage en millisecondes timestamp et rowCount.

GroupByGeoGrid

GroupByGeoGridResult

groupByGeoGridResultItems. Chaque élément contient le GeoHash key, geoGrid avec les coordonnées en haut à gauche et en bas à droite, et rowCount.

Exemples

Utiliser des sous-agrégations et des sous-regroupements

L'exemple suivant regroupe les lignes par catégorie, calcule le prix le plus élevé dans chaque catégorie, puis regroupe les lignes de chaque catégorie par ville. Les règles de tri des groupes s'appliquent dans l'ordre dans lequel elles sont ajoutées.

SearchQuery searchQuery = SearchQuery.newBuilder()
        .query(QueryBuilders.matchAll())
        .limit(0)
        .addGroupBy(GroupByBuilders.groupByField(
                "category_group", "category")
                .size(10)
                .addGroupBySorter(GroupBySorter.groupKeySortInAsc())
                .addSubAggregation(AggregationBuilders.max(
                        "max_price", "price"))
                .addSubGroupBy(GroupByBuilders.groupByField(
                        "city_group", "city").size(10)))
        .build();

SearchRequest request =
        new SearchRequest("example_table", "example_index", searchQuery);
SearchResponse response = client.search(request);

GroupByFieldResult result = response.getGroupByResults()
        .getAsGroupByFieldResult("category_group");
for (GroupByFieldResultItem item :
        result.getGroupByFieldResultItems()) {
    double maxPrice = item.getSubAggregationResults()
            .getAsMaxAggregationResult("max_price")
            .getValue();
    GroupByFieldResult cityResult = item.getSubGroupByResults()
            .getAsGroupByFieldResult("city_group");
    System.out.println(item.getKey() + ": " + maxPrice);
    System.out.println(cityResult.getGroupByFieldResultItems());
}

Paginer un regroupement multi-champs

GroupByComposite renvoie des clés multi-colonnes dans une structure plate et prend en charge la pagination via nextToken.

GroupByComposite.Builder compositeBuilder = GroupByBuilders
        .groupByComposite("category_city_group")
        .addSources(GroupByBuilders.groupByField(
                "category", "category")
                .addGroupBySorter(GroupBySorter.groupKeySortInAsc()))
        .addSources(GroupByBuilders.groupByField(
                "city", "city")
                .addGroupBySorter(GroupBySorter.groupKeySortInAsc()))
        .size(100);

String nextToken = null;
do {
    GroupByComposite groupBy = nextToken == null
            ? compositeBuilder.build()
            : compositeBuilder.nextToken(nextToken).build();
    SearchQuery searchQuery = SearchQuery.newBuilder()
            .query(QueryBuilders.matchAll())
            .limit(0)
            .addGroupBy(groupBy)
            .build();
    SearchRequest request = new SearchRequest(
            "example_table", "example_index", searchQuery);
    SearchResponse response = client.search(request);

    GroupByCompositeResult result = response.getGroupByResults()
            .getAsGroupByCompositeResult("category_city_group");
    for (GroupByCompositeResultItem item :
            result.getGroupByCompositeResultItems()) {
        System.out.println(item.getKeys() + ": " + item.getRowCount());
    }
    nextToken = result.getNextToken();
} while (nextToken != null);

Regrouper par plage, distance et filtre

Le code suivant montre les configurations principales de trois types de regroupement. Vous pouvez les combiner dans la même SearchQuery.

GroupByRange priceRanges = GroupByBuilders
        .groupByRange("price_ranges", "price")
        .addRange(0, 100)
        .addRange(100, 500)
        .build();

GroupByGeoDistance distanceRanges = GroupByBuilders
        .groupByGeoDistance("distance_ranges", "location")
        .origin(30.2741, 120.1551)
        .addRange(0, 10000)
        .addRange(10000, 100000)
        .build();

GroupByFilter categoryFilters = GroupByBuilders
        .groupByFilter("category_filters")
        .addFilter(QueryBuilders.term("category", "books"))
        .addFilter(QueryBuilders.term("category", "games"))
        .build();

Créer des histogrammes numériques et de date

L'exemple suivant regroupe les lignes par un intervalle numérique de 20 et un intervalle de date d'un mois.

GroupByHistogram priceHistogram = GroupByBuilders
        .groupByHistogram("price_histogram", "price")
        .interval(20)
        .offset(0)
        .minDocCount(1L)
        .addFieldRange(0, 100)
        .addGroupBySorter(GroupBySorter.groupKeySortInAsc())
        .build();

GroupByDateHistogram dateHistogram = GroupByBuilders
        .groupByDateHistogram("date_histogram", "event_date")
        .interval(1, DateTimeUnit.MONTH)
        .fieldRange("2026-01-01", "2026-06-01")
        .timeZone("+08:00")
        .minDocCount(1L)
        .addGroupBySorter(GroupBySorter.groupKeySortInAsc())
        .build();

SearchQuery searchQuery = SearchQuery.newBuilder()
        .query(QueryBuilders.matchAll())
        .limit(0)
        .addGroupBy(priceHistogram)
        .addGroupBy(dateHistogram)
        .build();
SearchResponse response = client.search(new SearchRequest(
        "example_table", "example_index", searchQuery));

Regrouper par grille géographique

L'exemple suivant regroupe un champ géographique en grilles GeoHash d'environ 39 km × 19 km.

SearchQuery searchQuery = SearchQuery.newBuilder()
        .query(QueryBuilders.matchAll())
        .limit(0)
        .addGroupBy(GroupByBuilders.groupByGeoGrid(
                "geo_grid", "location")
                .precision(GeoHashPrecision.GHP_39KM_19KM_4)
                .size(100))
        .build();

SearchResponse response = client.search(new SearchRequest(
        "example_table", "example_index", searchQuery));
GroupByGeoGridResult result = response.getGroupByResults()
        .getAsGroupByGeoGridResult("geo_grid");
System.out.println(result.getGroupByGeoGridResultItems());

Renvoyer des lignes depuis les groupes

L'exemple suivant regroupe les lignes par catégorie et renvoie la ligne ayant le prix le plus élevé dans chaque catégorie.

SearchQuery searchQuery = SearchQuery.newBuilder()
        .query(QueryBuilders.matchAll())
        .limit(0)
        .addGroupBy(GroupByBuilders.groupByField(
                "category_group", "category")
                .size(10)
                .addSubAggregation(AggregationBuilders.topRows(
                        "top_price")
                        .limit(1)
                        .sort(new Sort(Arrays.asList(
                                new FieldSort(
                                        "price", SortOrder.DESC))))))
        .build();

SearchRequest.ColumnsToGet columnsToGet =
        new SearchRequest.ColumnsToGet();
columnsToGet.setColumns(Arrays.asList("category", "price"));

SearchRequest request =
        new SearchRequest("example_table", "example_index", searchQuery);
request.setColumnsToGet(columnsToGet);
SearchResponse response = client.search(request);

GroupByFieldResult result = response.getGroupByResults()
        .getAsGroupByFieldResult("category_group");
for (GroupByFieldResultItem item :
        result.getGroupByFieldResultItems()) {
    List<Row> rows = item.getSubAggregationResults()
            .getAsTopRowsAggregationResult("top_price")
            .getRows();
    System.out.println(item.getKey() + ": " + rows);
}

Comparaison des regroupements multi-champs

Pour regrouper par plusieurs champs, imbriquez plusieurs configurations GroupByField ou utilisez directement GroupByComposite. Choisissez en fonction des exigences de pagination, de la structure de la réponse et des règles de tri.

Élément

Regroupements de champs imbriqués

Regroupement composite

Configuration

Ajoutez subGroupBys à un GroupByField parent.

Ajoutez plusieurs sources de regroupement à GroupByComposite.sources.

Nombre de groupes

Jusqu'à 2 000 groupes à chaque niveau.

Jusqu'à 2 000 groupes par page.

Nombre de champs

Jusqu'à trois niveaux d'imbrication.

Jusqu'à 32 champs.

Structure de la réponse

Imbriquée par niveaux parent et enfant.

Les clés multi-colonnes sont renvoyées sous forme de liste plate.

Pagination

Non prise en charge.

Prise en charge via nextToken.

Tri

Prend en charge le tri par clé de groupe, nombre de lignes ou valeur de sous-agrégation.

Chaque source de regroupement prend en charge uniquement le tri lexicographique par clé. L'ordre par défaut est décroissant.

Sous-agrégations

Prises en charge.

Compatibilité des champs de date

Les clés de groupe utilisent le format de date défini pour le champ.

Les clés de groupe de date sont renvoyées sous forme de chaînes d'horodatage.