Aggregation - Tablestore SDK for Java - Tablestore - Centro de documentación de Alibaba Cloud

El Tablestore SDK para Java permite calcular métricas o agrupar los resultados de consultas de índices de búsqueda, incluso mediante histogramas, group-bys anidados y filas principales dentro de grupos.

Requisitos previos

Instale Tablestore SDK for Java e inicialice un cliente.

Funcionamiento

Una vez completada la consulta del índice de búsqueda, la agregación calcula métricas o agrupa todas las filas coincidentes. Las agregaciones de métricas calculan el valor mínimo, máximo, suma, promedio, conteo, conteo distinto o percentiles de los campos. Los group-bys agrupan filas por valores de campo, varios campos, rangos numéricos, distancias geográficas, filtros, intervalos numéricos, intervalos de fecha o cuadrículas geográficas. También es posible agregar agregaciones de métricas o group-bys dentro de un grupo.

Categoría	Tipo de configuración	Descripción
Agregación de métrica	MinAggregation	Devuelve el valor mínimo de un campo, similar a `MIN` en SQL.
Agregación de métrica	MaxAggregation	Devuelve el valor máximo de un campo, similar a `MAX` en SQL.
Agregación de métrica	SumAggregation	Devuelve la suma de un campo numérico, similar a `SUM` en SQL.
Agregación de métrica	AvgAggregation	Devuelve el valor promedio de un campo, similar a `AVG` en SQL.
Agregación de métrica	CountAggregation	Devuelve el número de filas en las que un campo especificado tiene valor, similar a `COUNT(field)` en SQL.
Agregación de métrica	DistinctCountAggregation	Devuelve el número de valores distintos en un campo, similar a `COUNT(DISTINCT field)` en SQL.
Agregación de métrica	PercentilesAggregation	Devuelve uno o más percentiles de un campo.
Agregación de métrica	TopRowsAggregation	Devuelve las primeras filas de cada grupo según un orden especificado.
Group-by	GroupByField	Agrupa filas por el valor de un solo campo.
Group-by	GroupByComposite	Agrupa filas por varios campos y admite tokens de paginación.
Group-by	GroupByRange	Agrupa filas por rangos numéricos.
Group-by	GroupByGeoDistance	Agrupa filas por rangos de distancia desde un punto central.
Group-by	GroupByFilter	Agrupa filas por varios filtros.
Group-by	GroupByHistogram	Crea un histograma con intervalos numéricos fijos.
Group-by	GroupByDateHistogram	Crea un histograma con intervalos de fecha u hora fijos.
Group-by	GroupByGeoGrid	Agrupa filas por cuadrícula GeoHash.

Importante

La ordenación y la agregación deben estar habilitadas para cualquier campo del índice de búsqueda utilizado en una agregación. Los tipos de campo compatibles varían según el tipo de agregación. Para obtener información sobre los tipos de campo del índice de búsqueda y sus asignaciones con los tipos de campo de la tabla de datos, consulte Data types.
Las agregaciones operan sobre las coincidencias de la consulta. Una solicitud que incluye agregaciones es más compleja que una que solo consulta filas. Si no necesita filas en la respuesta, establezca limit en 0.
El conteo distinto, los percentiles y los group-bys de campo utilizan cálculos aproximados. Un conteo distinto inferior a 10,000 se aproxima al valor exacto. Con un conteo distinto de 100 millones, el error es de aproximadamente 2%. Los percentiles cercanos a los extremos suelen ser más precisos; por ejemplo, P1 y P99 generalmente son más precisos que P50. El cálculo paralelo de group-bys de campo también puede introducir un pequeño margen de error.
Es posible combinar varias agregaciones. Un gran número de agregaciones o un anidamiento profundo aumenta la complejidad de la solicitud y puede incrementar la latencia. Para consultar los límites de anidamiento, consulte Search index limits.

Llame a search para consultar datos. Configure SearchQuery.aggregationList para agregaciones de métricas y SearchQuery.groupByList para group-bys.

SearchResponse search(SearchRequest request)

En el siguiente ejemplo se consultan todas las filas de un índice de búsqueda, se calculan el mínimo, máximo, suma, promedio, conteo, número de categorías distintas y P50 de los precios, y se agrupan las filas por categoría.

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());
}

Parámetros

Solicitud de consulta

El tipo de request es SearchRequest. La siguiente tabla describe sus parámetros.

Nombre	Tipo	Descripción
tableName (obligatorio)	String	Nombre de la tabla de datos.
indexName (obligatorio)	String	Nombre del índice de búsqueda.
searchQuery (obligatorio)	SearchQuery	Condición de consulta y configuraciones de agregación.
columnsToGet (opcional)	SearchRequest.ColumnsToGet	Columnas que se devolverán. Este parámetro solo aplica cuando `TopRowsAggregation` devuelve filas dentro de grupos. Si no se configura este parámetro, solo se devuelven las columnas de clave principal.
timeoutInMillisecond (opcional)	int	Tiempo de espera de la consulta a nivel de solicitud, en milisegundos. Valor predeterminado: `-1`, lo que indica que no se configura un tiempo de espera de consulta independiente.
routingValues (opcional)	`List<PrimaryKey>`	Valores de clave principal de los campos de enrutamiento personalizado. No es necesario configurar este parámetro si no se utiliza enrutamiento personalizado.

Configuración de consulta

El tipo de request.searchQuery es SearchQuery. La siguiente tabla describe los parámetros relacionados con la agregación.

Nombre	Tipo	Descripción
query (obligatorio)	Query	Condición de consulta que determina el alcance de la agregación. Para agregar todas las filas de un índice de búsqueda, utilice `MatchAllQuery`.
aggregationList (opcional)	`List<Aggregation>`	Configuraciones de agregación de métricas. Configure como mínimo este parámetro o `groupByList`.
groupByList (opcional)	`List<GroupBy>`	Configuraciones de group-by. Configure como mínimo este parámetro o `aggregationList`.
limit (opcional)	Integer	Número máximo de filas que se devolverán. Valor predeterminado: `10`. Establezca este parámetro en `0` si solo necesita los resultados de la agregación.
offset (opcional)	Integer	Posición de fila desde la cual comienza la consulta. Valor predeterminado: `0`.
sort (opcional)	Sort	Orden de clasificación de los resultados de la consulta. Este parámetro no modifica el alcance de las agregaciones de métricas ni de los group-bys regulares.
trackTotalCount (opcional)	int	Número máximo esperado de filas coincidentes que se contarán. Si este parámetro se establece en `TRACK_TOTAL_COUNT`, podrá obtener el número total de coincidencias de la consulta desde `SearchResponse.totalCount`.
filter (opcional)	SearchFilter	Filtro aplicado a los resultados de `query`. Las agregaciones operan sobre los resultados filtrados.

Agregaciones de métricas

Agregue los siguientes objetos de parámetro a request.searchQuery.aggregationList[]. aggName identifica el resultado correspondiente y debe ser único dentro de una solicitud.

MinAggregation, MaxAggregation y AvgAggregation

Nombre	Tipo	Descripción
aggName (obligatorio)	String	Nombre de la agregación.
fieldName (obligatorio)	String	Nombre del campo de agregación. Se admiten campos Long, Double y Date.
missing (opcional)	ColumnValue	Valor que se utiliza si falta `fieldName`. Si no se configura este parámetro, se ignoran las filas donde falta el campo.

SumAggregation

Nombre	Tipo	Descripción
aggName (obligatorio)	String	Nombre de la agregación.
fieldName (obligatorio)	String	Nombre del campo de agregación. Se admiten campos Long y Double.
missing (opcional)	ColumnValue	Valor que se utiliza en la suma si falta `fieldName`. Si no se configura este parámetro, se ignoran las filas donde falta el campo.

CountAggregation

Nombre	Tipo	Descripción
aggName (obligatorio)	String	Nombre de la agregación.
fieldName (obligatorio)	String	Campo cuyos valores no nulos se contarán. Se admiten campos Long, Double, Boolean, Keyword, Date, IP y Geo-point. No se cuentan las filas de una columna dispersa que no contengan el campo.

Para contar todas las coincidencias de la consulta, configure trackTotalCount en SearchQuery y lea SearchResponse.totalCount. Para contar todas las filas de un índice de búsqueda, utilice MatchAllQuery.

DistinctCountAggregation

Nombre	Tipo	Descripción
aggName (obligatorio)	String	Nombre de la agregación.
fieldName (obligatorio)	String	Campo cuyos valores distintos se contarán. Se admiten campos Long, Double, Boolean, Keyword, Date, IP y Geo-point.
missing (opcional)	ColumnValue	Valor que se utiliza para el conteo distinto si falta `fieldName`. Si no se configura este parámetro, se ignoran las filas donde falta el campo.

PercentilesAggregation

Nombre	Tipo	Descripción
aggName (obligatorio)	String	Nombre de la agregación.
fieldName (obligatorio)	String	Nombre del campo de agregación. Se admiten campos Long, Double y Date.
percentiles (obligatorio)	`List<Double>`	Percentiles que se calcularán, como `25.0`, `50.0`, `90.0` y `99.0`.
missing (opcional)	ColumnValue	Valor que se utiliza en el cálculo de percentiles si falta `fieldName`. Si no se configura este parámetro, se ignoran las filas donde falta el campo.

TopRowsAggregation

Utilice TopRowsAggregation como subagregación de un group-by.

Nombre	Tipo	Descripción
aggName (obligatorio)	String	Nombre de la agregación.
limit (opcional)	Integer	Número máximo de filas que se devolverán de cada grupo. Valor predeterminado: `1`.
sort (opcional)	Sort	Orden de clasificación de las filas dentro de un grupo.

El parámetro request.columnsToGet controla las columnas de atributos que se devuelven. Para devolver columnas de atributos directamente desde el índice de búsqueda, almacene los campos al crear el índice. Si no se especifican columnas, solo se devuelven las claves principales.

Group-bys

Agregue los siguientes objetos de parámetro a request.searchQuery.groupByList[]. groupByName identifica el resultado correspondiente y debe ser único dentro de una solicitud.

GroupByField

Nombre	Tipo	Descripción
groupByName (obligatorio)	String	Nombre del group-by.
fieldName (obligatorio)	String	Nombre del campo de agrupación. Se admiten campos Long, Double, Boolean, Keyword, Date e IP.
size (opcional)	Integer	Número de grupos que se devolverán. Valor predeterminado: `10`. Valor máximo: `2000`.
minDocCount (opcional)	Long	Número mínimo de filas en un grupo. Los grupos con menos filas no se devuelven.
groupBySorters (opcional)	`List<GroupBySorter>`	Reglas de ordenación de grupos. De forma predeterminada, los grupos se ordenan por conteo de filas en orden descendente. Varias reglas surten efecto en el orden en que se agregan.
subAggregations (opcional)	`List<Aggregation>`	Agregaciones de métricas calculadas dentro de cada grupo.
subGroupBys (opcional)	`List<GroupBy>`	Group-bys aplicados dentro de cada grupo padre.

groupBySorters[] admite los siguientes valores.

Valor	Descripción
groupKeySortInAsc	Ordena los grupos por clave en orden lexicográfico ascendente.
groupKeySortInDesc	Ordena los grupos por clave en orden lexicográfico descendente.
rowCountSortInAsc	Ordena los grupos por conteo de filas en orden ascendente.
rowCountSortInDesc	Ordena los grupos por conteo de filas en orden descendente. Es el comportamiento predeterminado.
subAggSortInAsc	Ordena los grupos por el valor de una subagregación especificada en orden ascendente.
subAggSortInDesc	Ordena los grupos por el valor de una subagregación especificada en orden descendente.

GroupByComposite

Nombre	Tipo	Descripción
groupByName (obligatorio)	String	Nombre del group-by.
sources (obligatorio)	`List<GroupBy>`	Fuentes de agrupación para varios campos. Se admiten hasta 32 campos. Las fuentes pueden ser `GroupByField`, `GroupByHistogram` o `GroupByDateHistogram`. Una fuente de campo puede especificar su nombre, campo y orden de clasificación. Una fuente de histograma numérico también puede especificar un intervalo, y una fuente de histograma de fechas puede especificar además una zona horaria. Una fuente solo puede ordenarse por clave. El orden predeterminado es descendente. Si falta un campo, la clave correspondiente es `null`.
nextToken (opcional)	String	Token de paginación para la siguiente página de grupos. Omita este parámetro en la primera solicitud. Si `nextToken` en la respuesta no está vacío, utilice el valor sin modificaciones en la siguiente solicitud.
size (opcional)	Integer	Número de grupos que se devolverán. Valor predeterminado: `10`. Valor máximo: `2000`. En la mayoría de los casos, utilice este parámetro para limitar el número de grupos.
suggestedSize (opcional)	Integer	Límite flexible para integraciones de alto rendimiento con motores de cómputo como Spark y Presto. Puede establecer este parámetro en `-1` o en un valor superior al límite del servidor. El número real devuelto es `min(suggestedSize, server-side group limit, total groups)`. No configure este parámetro y `size` en la misma solicitud.
subAggregations (opcional)	`List<Aggregation>`	Subagregaciones.
subGroupBys (opcional)	`List<GroupBy>`	Sub-group-bys. `GroupByComposite` no puede utilizarse como sub-group-by.

Nota

El Tablestore SDK para Java representa nextToken como una cadena. Si persiste o transfiere el token, no modifique su contenido.

GroupByRange

Nombre	Tipo	Descripción
groupByName (obligatorio)	String	Nombre del group-by.
fieldName (obligatorio)	String	Nombre del campo de agrupación. Se admiten campos Long y Double.
ranges (obligatorio)	`List<Range>`	Rangos. Cada rango es cerrado por la izquierda y abierto por la derecha: `[from, to)`. Puede utilizar `Double.MIN_VALUE` y `Double.MAX_VALUE` como límites.
subAggregations (opcional)	`List<Aggregation>`	Subagregaciones.
subGroupBys (opcional)	`List<GroupBy>`	Sub-group-bys.

GroupByGeoDistance

Nombre	Tipo	Descripción
groupByName (obligatorio)	String	Nombre del group-by.
fieldName (obligatorio)	String	Nombre del campo de agrupación. Solo se admiten campos Geo-point.
origin (obligatorio)	GeoPoint	Punto central. Los parámetros del constructor son latitud seguida de longitud. El rango de latitud es `[-90,+90]` y el rango de longitud es `[-180,+180]`.
ranges (obligatorio)	`List<Range>`	Rangos de distancia en metros. Cada rango es cerrado por la izquierda y abierto por la derecha: `[from, to)`.
subAggregations (opcional)	`List<Aggregation>`	Subagregaciones.
subGroupBys (opcional)	`List<GroupBy>`	Sub-group-bys.

GroupByFilter

Nombre	Tipo	Descripción
groupByName (obligatorio)	String	Nombre del group-by.
filters (obligatorio)	`List<Query>`	Filtros. Los resultados se devuelven en el orden en que se agregan los filtros.
subAggregations (opcional)	`List<Aggregation>`	Subagregaciones.
subGroupBys (opcional)	`List<GroupBy>`	Sub-group-bys.

GroupByHistogram

Nombre	Tipo	Descripción
groupByName (obligatorio)	String	Nombre del group-by.
fieldName (obligatorio)	String	Nombre del campo de agrupación. Se admiten campos Long y Double.
interval (obligatorio)	ColumnValue	Intervalo del histograma.
fieldRange (opcional)	FieldRange	Rango de agregación, que contiene `min` y `max`. El valor de `(max-min)/interval` no puede exceder `2000`.
offset (opcional)	ColumnValue	Desplazamiento de los límites del bucket respecto al punto de inicio predeterminado.
minDocCount (opcional)	Long	Número mínimo de filas en un bucket. Los buckets con menos filas no se devuelven.
missing (opcional)	ColumnValue	Valor que se utiliza en el histograma si falta `fieldName`. Si no se configura este parámetro, se ignoran las filas donde falta el campo.
groupBySorters (opcional)	`List<GroupBySorter>`	Reglas de ordenación de buckets.
subAggregations (opcional)	`List<Aggregation>`	Subagregaciones.
subGroupBys (opcional)	`List<GroupBy>`	Sub-group-bys.

GroupByDateHistogram

Importante

La agregación de histograma de fechas es compatible con Tablestore SDK para Java 5.16.1 y versiones posteriores. El tipo de campo Date para índices de búsqueda es compatible con Tablestore SDK para Java 5.13.9 y versiones posteriores. Para obtener información sobre versiones, consulte Tablestore SDK for Java version history.

Nombre	Tipo	Descripción
groupByName (obligatorio)	String	Nombre del group-by.
fieldName (obligatorio)	String	Nombre del campo de agrupación. Solo se admiten campos Date.
interval (obligatorio)	DateTimeValue	Intervalo de fecha u hora, compuesto por un valor y una `DateTimeUnit`.
fieldRange (opcional)	FieldRange	Rango de agregación, que contiene `min` y `max`. El valor de `(max-min)/interval` no puede exceder `2000`.
minDocCount (opcional)	Long	Número mínimo de filas en un bucket. Los buckets con menos filas no se devuelven.
missing (opcional)	ColumnValue	Valor de fecha que se utiliza en el histograma si falta `fieldName`. Si no se configura este parámetro, se ignoran las filas donde falta el campo.
timeZone (opcional)	String	Zona horaria en formato `+hh:mm` o `-hh:mm`, como `+08:00`. Si el formato del campo Date no incluye información de zona horaria, configure este parámetro para evitar desfases horarios en los resultados de la agregación.
groupBySorters (opcional)	`List<GroupBySorter>`	Reglas de ordenación de buckets.
subAggregations (opcional)	`List<Aggregation>`	Subagregaciones.
subGroupBys (opcional)	`List<GroupBy>`	Sub-group-bys.

GroupByGeoGrid

Nombre	Tipo	Descripción
groupByName (obligatorio)	String	Nombre del group-by.
fieldName (obligatorio)	String	Nombre del campo de agrupación. Solo se admiten campos Geo-point.
precision (obligatorio)	GeoHashPrecision	Precisión de la cuadrícula GeoHash. Los valores van desde `GHP_5009KM_4992KM_1`, que equivale aproximadamente a 5,009 km × 4,992 km, hasta `GHP_37MM_19MM_12`, que equivale aproximadamente a 37 mm × 19 mm. Un sufijo mayor especifica una cuadrícula más pequeña.
size (opcional)	Integer	Número de grupos de cuadrícula que se devolverán.
subAggregations (opcional)	`List<Aggregation>`	Subagregaciones.
subGroupBys (opcional)	`List<GroupBy>`	Sub-group-bys.

Respuesta

El método search devuelve SearchResponse. La siguiente tabla describe los campos relacionados con la agregación.

Nombre	Tipo	Descripción
aggregationResults	AggregationResults	Resultados de agregación de métricas. Llame a `getAggregationResults()` para obtener el valor y utilice un nombre de agregación para obtener un tipo de resultado específico.
groupByResults	GroupByResults	Resultados de group-by. Llame a `getGroupByResults()` para obtener el valor y utilice un nombre de group-by para obtener un tipo de resultado específico.
totalCount	long	Número de coincidencias de la consulta. Llame a `getTotalCount()` para obtener el valor. El valor depende de `trackTotalCount`.
isAllSuccess	boolean	Indica si se consultaron todas las particiones del índice. Llame a `isAllSuccess()` para obtener el valor. Si este campo es `false`, los resultados de la agregación podrían estar incompletos.

Resultados de agregación de métricas

Tipo de configuración	Tipo de resultado	Campo de resultado y método de acceso
MinAggregation	MinAggregationResult	`value` es de tipo `double`. Llame a `getAsMinAggregationResult(aggName).getValue()`.
MaxAggregation	MaxAggregationResult	`value` es de tipo `double`. Llame a `getAsMaxAggregationResult(aggName).getValue()`.
SumAggregation	SumAggregationResult	`value` es de tipo `double`. Llame a `getAsSumAggregationResult(aggName).getValue()`.
AvgAggregation	AvgAggregationResult	`value` es de tipo `double`. Llame a `getAsAvgAggregationResult(aggName).getValue()`.
CountAggregation	CountAggregationResult	`value` es de tipo `long`. Llame a `getAsCountAggregationResult(aggName).getValue()`.
DistinctCountAggregation	DistinctCountAggregationResult	`value` es de tipo `long`. Llame a `getAsDistinctCountAggregationResult(aggName).getValue()`.
PercentilesAggregation	PercentilesAggregationResult	`percentilesAggregationItems` es de tipo `List<PercentilesAggregationItem>`. Llame a `getAsPercentilesAggregationResult(aggName).getPercentilesAggregationItems()`. Cada elemento contiene `key` y `value`.
TopRowsAggregation	TopRowsAggregationResult	`rows` es de tipo `List<Row>`. Llame a `getAsTopRowsAggregationResult(aggName).getRows()`.

Resultados de group-by

Tipo de configuración	Tipo de resultado	Campos principales del resultado
GroupByField	GroupByFieldResult	`groupByFieldResultItems`. Cada elemento contiene `key`, `rowCount`, `subAggregationResults` y `subGroupByResults`.
GroupByComposite	GroupByCompositeResult	`sourceNames`, `groupByCompositeResultItems` y `nextToken`. Las posiciones de `keys` en cada elemento corresponden a `sourceNames`.
GroupByRange	GroupByRangeResult	`groupByRangeResultItems`. Cada elemento contiene `from`, `to` y `rowCount`.
GroupByGeoDistance	GroupByGeoDistanceResult	`groupByGeoDistanceResultItems`. Cada elemento contiene distancia `from`, `to` y `rowCount`.
GroupByFilter	GroupByFilterResult	`groupByFilterResultItems`. Cada elemento contiene `rowCount` y el orden de los elementos coincide con el orden de los filtros.
GroupByHistogram	GroupByHistogramResult	`groupByHistogramItems`. Cada elemento contiene el inicio del bucket `key` y el conteo de filas `value`.
GroupByDateHistogram	GroupByDateHistogramResult	`groupByDateHistogramItems`. Cada elemento contiene la marca de tiempo en milisegundos `timestamp` y `rowCount`.
GroupByGeoGrid	GroupByGeoGridResult	`groupByGeoGridResultItems`. Cada elemento contiene GeoHash `key`, `geoGrid` con coordenadas superior izquierda e inferior derecha, y `rowCount`.

Ejemplos

Uso de subagregaciones y sub-group-bys

En el siguiente ejemplo se agrupan filas por categoría, se calcula el precio más alto en cada categoría y luego se agrupan las filas de cada categoría por ciudad. Las reglas de ordenación de grupos surten efecto en el orden en que se agregan.

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());
}

Paginación de un group-by de varios campos

GroupByComposite devuelve claves de varias columnas en una estructura plana y admite paginación mediante 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);

Agrupación por rango, distancia y filtro

El siguiente código muestra las configuraciones principales de tres tipos de group-by. Puede combinarlos en el mismo 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();

Creación de histogramas numéricos y de fechas

En el siguiente ejemplo se agrupan filas por un intervalo numérico de 20 y un intervalo de fechas de un mes.

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));

Agrupación por cuadrícula geográfica

En el siguiente ejemplo se agrupa un campo geográfico en cuadrículas GeoHash de aproximadamente 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());

Devolución de filas desde grupos

En el siguiente ejemplo se agrupan filas por categoría y se devuelve la fila con el precio más alto de cada categoría.

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);
}

Comparación de group-by de varios campos

Para agrupar por varios campos, anide múltiples configuraciones de GroupByField o utilice GroupByComposite directamente. Elija según los requisitos de paginación, la estructura de respuesta y las reglas de ordenación.

Elemento	Group-bys de campo anidados	Group-by compuesto
Configuración	Agregue `subGroupBys` a un `GroupByField` padre.	Agregue varias fuentes de agrupación a `GroupByComposite.sources`.
Número de grupos	Hasta 2,000 grupos en cada nivel.	Hasta 2,000 grupos por página.
Número de campos	Hasta tres niveles anidados.	Hasta 32 campos.
Estructura de respuesta	Anidada por niveles padre e hijo.	Las claves de varias columnas se devuelven como una lista plana.
Paginación	No compatible.	Compatible mediante `nextToken`.
Ordenación	Admite ordenación por clave de grupo, conteo de filas o valor de subagregación.	Cada fuente de agrupación solo admite ordenación lexicográfica por clave. El orden predeterminado es descendente.
Subagregaciones	Compatible.	Compatible.
Compatibilidad con campos de fecha	Las claves de grupo utilizan el formato de fecha definido para el campo.	Las claves de grupo de fechas se devuelven como cadenas de marcas de tiempo.