Agregação - Tablestore SDK for Java - Tablestore: Central de Documentação do Alibaba Cloud

Use o Tablestore SDK for Java para calcular métricas ou agrupar resultados de consultas em índices de busca, inclusive com histogramas, group-bys aninhados e principais linhas por grupo.

Pré-requisitos

Instale o Tablestore SDK for Java e inicialize um cliente.

Funcionamento

Após a conclusão de uma consulta no índice de busca, a agregação calcula métricas ou agrupa todas as linhas correspondentes. As agregações de métrica calculam valores mínimos, máximos, soma, média, contagem, contagem distinta ou percentis de campos. Os group-bys agrupam linhas por valores de campo, múltiplos campos, intervalos numéricos, distâncias geográficas, filtros, intervalos numéricos fixos, intervalos de data ou grades geográficas. Também é possível adicionar agregações de métrica ou group-bys dentro de um grupo.

Categoria	Tipo de configuração	Descrição
Agregação de métrica	MinAggregation	Retorna o valor mínimo de um campo, semelhante ao `MIN` em SQL.
Agregação de métrica	MaxAggregation	Retorna o valor máximo de um campo, semelhante ao `MAX` em SQL.
Agregação de métrica	SumAggregation	Retorna a soma de um campo numérico, semelhante ao `SUM` em SQL.
Agregação de métrica	AvgAggregation	Retorna o valor médio de um campo, semelhante ao `AVG` em SQL.
Agregação de métrica	CountAggregation	Retorna o número de linhas em que um campo especificado possui valor, semelhante ao `COUNT(field)` em SQL.
Agregação de métrica	DistinctCountAggregation	Retorna o número de valores distintos em um campo, semelhante ao `COUNT(DISTINCT field)` em SQL.
Agregação de métrica	PercentilesAggregation	Retorna um ou mais percentis de um campo.
Agregação de métrica	TopRowsAggregation	Retorna as primeiras linhas de cada grupo com base em uma ordem especificada.
Group-by	GroupByField	Agrupa linhas pelo valor de um único campo.
Group-by	GroupByComposite	Agrupa linhas por múltiplos campos e suporta tokens de paginação.
Group-by	GroupByRange	Agrupa linhas por intervalos numéricos.
Group-by	GroupByGeoDistance	Agrupa linhas por faixas de distância a partir de um ponto central.
Group-by	GroupByFilter	Agrupa linhas por múltiplos filtros.
Group-by	GroupByHistogram	Crie um histograma usando intervalos numéricos fixos.
Group-by	GroupByDateHistogram	Crie um histograma usando intervalos fixos de data ou hora.
Group-by	GroupByGeoGrid	Agrupa linhas por grade GeoHash.

Importante

Ative a ordenação e a agregação para qualquer campo do índice de busca utilizado em uma agregação. Os tipos de campo suportados variam conforme o tipo de agregação. Para obter informações sobre os tipos de campo do índice de busca e seus mapeamentos para tipos de campo da tabela de dados, consulte Data types.
As agregações operam sobre as correspondências da consulta. Uma requisição com agregações é mais complexa do que uma requisição que apenas consulta linhas. Caso não precise das linhas na resposta, defina limit como 0.
A contagem distinta, os percentis e os group-bys de campo utilizam cálculos aproximados. Uma contagem distinta abaixo de 10.000 aproxima-se do valor exato. Com uma contagem distinta de 100 milhões, a margem de erro é de aproximadamente 2%. Percentis nas extremidades costumam ser mais precisos; por exemplo, P1 e P99 geralmente são mais exatos que P50. O cálculo paralelo de group-bys de campo também pode introduzir uma pequena margem de erro.
É possível combinar múltiplas agregações. Um grande volume de agregações ou aninhamentos profundos aumenta a complexidade da requisição e pode elevar a latência. Para limites de aninhamento, consulte Search index limits.

Chame search para consultar dados. Configure SearchQuery.aggregationList para agregações de métrica e SearchQuery.groupByList para group-bys.

SearchResponse search(SearchRequest request)

O exemplo abaixo consulta todas as linhas em um índice de busca, calcula os valores mínimo, máximo, soma, média, contagem, quantidade de categorias distintas e P50 dos preços, além de agrupar as linhas por categoria.

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

Requisição de consulta

O tipo de request é SearchRequest. A tabela a seguir descreve seus parâmetros.

Nome	Tipo	Descrição
tableName (obrigatório)	String	Nome da tabela de dados.
indexName (obrigatório)	String	Nome do índice de busca.
searchQuery (obrigatório)	SearchQuery	Condição de consulta e configurações de agregação.
columnsToGet (opcional)	SearchRequest.ColumnsToGet	Colunas a retornar. Este parâmetro aplica-se apenas quando `TopRowsAggregation` retorna linhas nos grupos. Se este parâmetro não for configurado, apenas as colunas de chave primária serão retornadas.
timeoutInMillisecond (opcional)	int	Tempo limite da consulta no nível da requisição, em milissegundos. Valor padrão: `-1`, indicando que nenhum tempo limite específico foi configurado.
routingValues (opcional)	`List<PrimaryKey>`	Valores de chave primária dos campos de roteamento personalizado. Não é necessário configurar este parâmetro se o roteamento personalizado não for utilizado.

Configuração da consulta

O tipo de request.searchQuery é SearchQuery. A tabela a seguir descreve os parâmetros relacionados à agregação.

Nome	Tipo	Descrição
query (obrigatório)	Query	Condição de consulta que determina o escopo da agregação. Para agregar todas as linhas de um índice de busca, utilize `MatchAllQuery`.
aggregationList (opcional)	`List<Aggregation>`	Configurações de agregação de métrica. Configure pelo menos este parâmetro ou `groupByList`.
groupByList (opcional)	`List<GroupBy>`	Configurações de group-by. Configure pelo menos este parâmetro ou `aggregationList`.
limit (opcional)	Integer	Número máximo de linhas a retornar. Valor padrão: `10`. Defina este parâmetro como `0` se precisar apenas dos resultados da agregação.
offset (opcional)	Integer	Posição da linha onde a consulta começa. Valor padrão: `0`.
sort (opcional)	Sort	Ordem de classificação dos resultados da consulta. Este parâmetro não altera o escopo das agregações de métrica ou dos group-bys comuns.
trackTotalCount (opcional)	int	Número máximo esperado de linhas correspondentes a contar. Se este parâmetro for definido como `TRACK_TOTAL_COUNT`, você poderá obter o total de correspondências da consulta através de `SearchResponse.totalCount`.
filter (opcional)	SearchFilter	Filtro aplicado aos resultados da `query`. As agregações operam sobre os resultados filtrados.

Agregações de métrica

Adicione os seguintes objetos de parâmetro a request.searchQuery.aggregationList[]. O aggName identifica o resultado correspondente e deve ser único na requisição.

MinAggregation, MaxAggregation e AvgAggregation

Nome	Tipo	Descrição
aggName (obrigatório)	String	Nome da agregação.
fieldName (obrigatório)	String	Nome do campo de agregação. Campos Long, Double e Date são suportados.
missing (opcional)	ColumnValue	Valor utilizado caso `fieldName` esteja ausente. Se este parâmetro não for configurado, as linhas sem esse campo serão ignoradas.

SumAggregation

Nome	Tipo	Descrição
aggName (obrigatório)	String	Nome da agregação.
fieldName (obrigatório)	String	Nome do campo de agregação. Campos Long e Double são suportados.
missing (opcional)	ColumnValue	Valor usado na soma caso `fieldName` esteja ausente. Se este parâmetro não for configurado, as linhas sem esse campo serão ignoradas.

CountAggregation

Nome	Tipo	Descrição
aggName (obrigatório)	String	Nome da agregação.
fieldName (obrigatório)	String	Campo cujos valores não nulos serão contados. Campos Long, Double, Boolean, Keyword, Date, IP e Geo-point são suportados. Linhas em uma coluna esparsa que não contenham o campo não são contabilizadas.

Para contar todas as correspondências da consulta, configure trackTotalCount em SearchQuery e leia SearchResponse.totalCount. Para contar todas as linhas de um índice de busca, use MatchAllQuery.

DistinctCountAggregation

Nome	Tipo	Descrição
aggName (obrigatório)	String	Nome da agregação.
fieldName (obrigatório)	String	Campo cujos valores distintos serão contados. Campos Long, Double, Boolean, Keyword, Date, IP e Geo-point são suportados.
missing (opcional)	ColumnValue	Valor usado na contagem distinta caso `fieldName` esteja ausente. Se este parâmetro não for configurado, as linhas sem esse campo serão ignoradas.

PercentilesAggregation

Nome	Tipo	Descrição
aggName (obrigatório)	String	Nome da agregação.
fieldName (obrigatório)	String	Nome do campo de agregação. Campos Long, Double e Date são suportados.
percentiles (obrigatório)	`List<Double>`	Percentis a calcular, como `25.0`, `50.0`, `90.0` e `99.0`.
missing (opcional)	ColumnValue	Valor usado no cálculo de percentis caso `fieldName` esteja ausente. Se este parâmetro não for configurado, as linhas sem esse campo serão ignoradas.

TopRowsAggregation

Utilize TopRowsAggregation como uma subagregação de um group-by.

Nome	Tipo	Descrição
aggName (obrigatório)	String	Nome da agregação.
limit (opcional)	Integer	Número máximo de linhas a retornar de cada grupo. Valor padrão: `1`.
sort (opcional)	Sort	Ordem de classificação das linhas dentro de um grupo.

O parâmetro request.columnsToGet controla quais colunas de atributo retornar. Para retornar colunas de atributo diretamente do índice de busca, armazene os campos ao criar o índice. Se nenhuma coluna for especificada, apenas as chaves primárias serão retornadas.

Group-bys

Adicione os seguintes objetos de parâmetro a request.searchQuery.groupByList[]. O groupByName identifica o resultado correspondente e deve ser único na requisição.

GroupByField

Nome	Tipo	Descrição
groupByName (obrigatório)	String	Nome do group-by.
fieldName (obrigatório)	String	Nome do campo de agrupamento. Campos Long, Double, Boolean, Keyword, Date e IP são suportados.
size (opcional)	Integer	Quantidade de grupos a retornar. Valor padrão: `10`. Valor máximo: `2000`.
minDocCount (opcional)	Long	Número mínimo de linhas em um grupo. Grupos com menos linhas não são retornados.
groupBySorters (opcional)	`List<GroupBySorter>`	Regras de ordenação dos grupos. Por padrão, os grupos são classificados pela contagem de linhas em ordem decrescente. Múltiplas regras entram em vigor na ordem em que são adicionadas.
subAggregations (opcional)	`List<Aggregation>`	Agregações de métrica calculadas dentro de cada grupo.
subGroupBys (opcional)	`List<GroupBy>`	Group-bys aplicados dentro de cada grupo pai.

O groupBySorters[] suporta os seguintes valores.

Valor	Descrição
groupKeySortInAsc	Classifica grupos por chave em ordem lexicográfica crescente.
groupKeySortInDesc	Classifica grupos por chave em ordem lexicográfica decrescente.
rowCountSortInAsc	Classifica grupos pela contagem de linhas em ordem crescente.
rowCountSortInDesc	Classifica grupos pela contagem de linhas em ordem decrescente. Esta é a configuração padrão.
subAggSortInAsc	Classifica grupos pelo valor de uma subagregação especificada em ordem crescente.
subAggSortInDesc	Classifica grupos pelo valor de uma subagregação especificada em ordem decrescente.

GroupByComposite

Nome	Tipo	Descrição
groupByName (obrigatório)	String	Nome do group-by.
sources (obrigatório)	`List<GroupBy>`	Fontes de agrupamento para múltiplos campos. Até 32 campos são suportados. As fontes podem ser `GroupByField`, `GroupByHistogram` ou `GroupByDateHistogram`. Uma fonte de campo pode especificar seu nome, campo e ordem de classificação. Uma fonte de histograma numérica também pode especificar um intervalo, e uma fonte de histograma de data pode adicionalmente especificar um fuso horário. Uma fonte só pode ser ordenada por chave. A ordem padrão é decrescente. Se um campo estiver ausente, a chave correspondente será `null`.
nextToken (opcional)	String	Token de paginação para a próxima página de grupos. Omita este parâmetro na primeira requisição. Se o `nextToken` na resposta não estiver vazio, utilize o valor inalterado na próxima requisição.
size (opcional)	Integer	Quantidade de grupos a retornar. Valor padrão: `10`. Valor máximo: `2000`. Na maioria dos casos, utilize este parâmetro para limitar o número de grupos.
suggestedSize (opcional)	Integer	Limite flexível para integrações de alto throughput com engines de computação como Spark e Presto. É possível definir este parâmetro como `-1` ou um valor superior ao limite do servidor. O número real retornado será `min(suggestedSize, server-side group limit, total groups)`. Não configure este parâmetro e `size` na mesma requisição.
subAggregations (opcional)	`List<Aggregation>`	Subagregações.
subGroupBys (opcional)	`List<GroupBy>`	Sub-group-bys. O próprio `GroupByComposite` não pode ser usado como sub-group-by.

Nota

O Tablestore SDK for Java representa o nextToken como uma string. Ao persistir ou transferir o token, não modifique seu conteúdo.

GroupByRange

Nome	Tipo	Descrição
groupByName (obrigatório)	String	Nome do group-by.
fieldName (obrigatório)	String	Nome do campo de agrupamento. Campos Long e Double são suportados.
ranges (obrigatório)	`List<Range>`	Intervalos. Cada intervalo é fechado à esquerda e aberto à direita: `[from, to)`. É possível usar `Double.MIN_VALUE` e `Double.MAX_VALUE` como limites.
subAggregations (opcional)	`List<Aggregation>`	Subagregações.
subGroupBys (opcional)	`List<GroupBy>`	Sub-group-bys.

GroupByGeoDistance

Nome	Tipo	Descrição
groupByName (obrigatório)	String	Nome do group-by.
fieldName (obrigatório)	String	Nome do campo de agrupamento. Apenas campos Geo-point são suportados.
origin (obrigatório)	GeoPoint	Ponto central. Os parâmetros do construtor são latitude seguidos de longitude. O intervalo de latitude é `[-90,+90]` e o intervalo de longitude é `[-180,+180]`.
ranges (obrigatório)	`List<Range>`	Faixas de distância em metros. Cada intervalo é fechado à esquerda e aberto à direita: `[from, to)`.
subAggregations (opcional)	`List<Aggregation>`	Subagregações.
subGroupBys (opcional)	`List<GroupBy>`	Sub-group-bys.

GroupByFilter

Nome	Tipo	Descrição
groupByName (obrigatório)	String	Nome do group-by.
filters (obrigatório)	`List<Query>`	Filtros. Os resultados são retornados na ordem em que os filtros são adicionados.
subAggregations (opcional)	`List<Aggregation>`	Subagregações.
subGroupBys (opcional)	`List<GroupBy>`	Sub-group-bys.

GroupByHistogram

Nome	Tipo	Descrição
groupByName (obrigatório)	String	Nome do group-by.
fieldName (obrigatório)	String	Nome do campo de agrupamento. Campos Long e Double são suportados.
interval (obrigatório)	ColumnValue	Intervalo do histograma.
fieldRange (opcional)	FieldRange	Faixa de agregação, contendo `min` e `max`. O valor de `(max-min)/interval` não pode exceder `2000`.
offset (opcional)	ColumnValue	Deslocamento dos limites dos buckets em relação ao ponto inicial padrão.
minDocCount (opcional)	Long	Número mínimo de linhas em um bucket. Buckets com menos linhas não são retornados.
missing (opcional)	ColumnValue	Valor usado no histograma caso `fieldName` esteja ausente. Se este parâmetro não for configurado, as linhas sem esse campo serão ignoradas.
groupBySorters (opcional)	`List<GroupBySorter>`	Regras de ordenação dos buckets.
subAggregations (opcional)	`List<Aggregation>`	Subagregações.
subGroupBys (opcional)	`List<GroupBy>`	Sub-group-bys.

GroupByDateHistogram

Importante

A agregação de histograma de data é suportada pelo Tablestore SDK for Java 5.16.1 e versões posteriores. O tipo de campo Date para índices de busca é suportado pelo Tablestore SDK for Java 5.13.9 e versões posteriores. Para informações sobre versões, consulte Tablestore SDK for Java version history.

Nome	Tipo	Descrição
groupByName (obrigatório)	String	Nome do group-by.
fieldName (obrigatório)	String	Nome do campo de agrupamento. Apenas campos Date são suportados.
interval (obrigatório)	DateTimeValue	Intervalo de data ou hora, composto por um valor e uma `DateTimeUnit`.
fieldRange (opcional)	FieldRange	Faixa de agregação, contendo `min` e `max`. O valor de `(max-min)/interval` não pode exceder `2000`.
minDocCount (opcional)	Long	Número mínimo de linhas em um bucket. Buckets com menos linhas não são retornados.
missing (opcional)	ColumnValue	Valor de data usado no histograma caso `fieldName` esteja ausente. Se este parâmetro não for configurado, as linhas sem esse campo serão ignoradas.
timeZone (opcional)	String	Fuso horário no formato `+hh:mm` ou `-hh:mm`, como `+08:00`. Se o formato do campo Date não incluir informações de fuso horário, configure este parâmetro para evitar deslocamento de tempo nos resultados da agregação.
groupBySorters (opcional)	`List<GroupBySorter>`	Regras de ordenação dos buckets.
subAggregations (opcional)	`List<Aggregation>`	Subagregações.
subGroupBys (opcional)	`List<GroupBy>`	Sub-group-bys.

GroupByGeoGrid

Nome	Tipo	Descrição
groupByName (obrigatório)	String	Nome do group-by.
fieldName (obrigatório)	String	Nome do campo de agrupamento. Apenas campos Geo-point são suportados.
precision (obrigatório)	GeoHashPrecision	Precisão da grade GeoHash. Os valores variam de `GHP_5009KM_4992KM_1`, que equivale a aproximadamente 5.009 km × 4.992 km, até `GHP_37MM_19MM_12`, que equivale a aproximadamente 37 mm × 19 mm. Um sufixo maior especifica uma grade menor.
size (opcional)	Integer	Número de grupos de grade a retornar.
subAggregations (opcional)	`List<Aggregation>`	Subagregações.
subGroupBys (opcional)	`List<GroupBy>`	Sub-group-bys.

Resposta

O método search retorna SearchResponse. A tabela a seguir descreve os campos relacionados à agregação.

Nome	Tipo	Descrição
aggregationResults	AggregationResults	Resultados das agregações de métrica. Chame `getAggregationResults()` para obter o valor e use o nome da agregação para obter um tipo de resultado específico.
groupByResults	GroupByResults	Resultados dos group-bys. Chame `getGroupByResults()` para obter o valor e use o nome do group-by para obter um tipo de resultado específico.
totalCount	long	Número de correspondências da consulta. Chame `getTotalCount()` para obter o valor. O valor depende de `trackTotalCount`.
isAllSuccess	boolean	Indica se todas as partições do índice foram consultadas. Chame `isAllSuccess()` para obter o valor. Se este campo for `false`, os resultados da agregação podem estar incompletos.

Resultados de agregação de métrica

Tipo de configuração	Tipo de resultado	Campo de resultado e acessor
MinAggregation	MinAggregationResult	`value` é um `double`. Chame `getAsMinAggregationResult(aggName).getValue()`.
MaxAggregation	MaxAggregationResult	`value` é um `double`. Chame `getAsMaxAggregationResult(aggName).getValue()`.
SumAggregation	SumAggregationResult	`value` é um `double`. Chame `getAsSumAggregationResult(aggName).getValue()`.
AvgAggregation	AvgAggregationResult	`value` é um `double`. Chame `getAsAvgAggregationResult(aggName).getValue()`.
CountAggregation	CountAggregationResult	`value` é um `long`. Chame `getAsCountAggregationResult(aggName).getValue()`.
DistinctCountAggregation	DistinctCountAggregationResult	`value` é um `long`. Chame `getAsDistinctCountAggregationResult(aggName).getValue()`.
PercentilesAggregation	PercentilesAggregationResult	`percentilesAggregationItems` é uma `List<PercentilesAggregationItem>`. Chame `getAsPercentilesAggregationResult(aggName).getPercentilesAggregationItems()`. Cada item contém `key` e `value`.
TopRowsAggregation	TopRowsAggregationResult	`rows` é uma `List<Row>`. Chame `getAsTopRowsAggregationResult(aggName).getRows()`.

Resultados de group-by

Tipo de configuração	Tipo de resultado	Campos principais do resultado
GroupByField	GroupByFieldResult	`groupByFieldResultItems`. Cada item contém `key`, `rowCount`, `subAggregationResults` e `subGroupByResults`.
GroupByComposite	GroupByCompositeResult	`sourceNames`, `groupByCompositeResultItems` e `nextToken`. As posições das `keys` em cada item correspondem aos `sourceNames`.
GroupByRange	GroupByRangeResult	`groupByRangeResultItems`. Cada item contém `from`, `to` e `rowCount`.
GroupByGeoDistance	GroupByGeoDistanceResult	`groupByGeoDistanceResultItems`. Cada item contém distância `from`, `to` e `rowCount`.
GroupByFilter	GroupByFilterResult	`groupByFilterResultItems`. Cada item contém `rowCount`, e a ordem dos itens corresponde à ordem dos filtros.
GroupByHistogram	GroupByHistogramResult	`groupByHistogramItems`. Cada item contém início do bucket `key` e contagem de linhas `value`.
GroupByDateHistogram	GroupByDateHistogramResult	`groupByDateHistogramItems`. Cada item contém timestamp em milissegundos `timestamp` e `rowCount`.
GroupByGeoGrid	GroupByGeoGridResult	`groupByGeoGridResultItems`. Cada item contém GeoHash `key`, `geoGrid` com coordenadas superior-esquerda e inferior-direita, e `rowCount`.

Exemplos

Uso de subagregações e sub-group-bys

O exemplo a seguir agrupa linhas por categoria, calcula o preço mais alto em cada categoria e, em seguida, agrupa as linhas de cada categoria por cidade. As regras de ordenação de grupo entram em vigor na ordem em que são adicionadas.

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

Paginação de um group-by de múltiplos campos

O GroupByComposite retorna chaves de múltiplas colunas em uma estrutura plana e suporta paginação 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);

Agrupamento por intervalo, distância e filtro

O código a seguir mostra as configurações principais de três tipos de group-by. É possível combiná-los no mesmo 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();

Criação de histogramas numéricos e de data

O exemplo a seguir agrupa linhas por um intervalo numérico de 20 e um intervalo de data de um mês.

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

Agrupamento por grade geográfica

O exemplo a seguir agrupa um campo geográfico em grades 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());

Retorno de linhas dos grupos

O exemplo a seguir agrupa linhas por categoria e retorna a linha com o preço mais alto em cada categoria.

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

Comparação de group-by de múltiplos campos

Para agrupar por múltiplos campos, aninhe várias configurações de GroupByField ou use GroupByComposite diretamente. Escolha com base nos requisitos de paginação, estrutura de resposta e regras de ordenação.

Item	Group-bys de campo aninhados	Group-by composto
Configuração	Adicione `subGroupBys` a um `GroupByField` pai.	Adicione múltiplas fontes de agrupamento a `GroupByComposite.sources`.
Número de grupos	Até 2.000 grupos em cada nível.	Até 2.000 grupos por página.
Número de campos	Até três níveis de aninhamento.	Até 32 campos.
Estrutura de resposta	Aninhada por níveis pai e filho.	Chaves de múltiplas colunas são retornadas como uma lista plana.
Paginação	Não suportada.	Suportada via `nextToken`.
Ordenação	Suporta ordenação por chave de grupo, contagem de linhas ou valor de subagregação.	Cada fonte de agrupamento suporta apenas ordenação lexicográfica por chave. A ordem padrão é decrescente.
Subagregações	Suportadas.	Suportadas.
Compatibilidade com campo de data	As chaves de grupo usam o formato de data definido para o campo.	As chaves de grupo de data são retornadas como strings de timestamp.