Aggregation - Tablestore SDK for Java - Tablestore - Alibaba Cloud Documentation Center

Anda dapat menggunakan Tablestore SDK for Java untuk menghitung metrik atau mengelompokkan hasil kueri indeks pencarian, termasuk dengan histogram, group-by bersarang, dan baris teratas dalam kelompok.

Prasyarat

Instal Tablestore SDK for Java dan inisialisasi client.

Cara kerja

Setelah kueri indeks pencarian selesai, agregasi menghitung metrik atau mengelompokkan semua baris yang cocok. Agregasi metrik menghitung nilai minimum, maksimum, jumlah, rata-rata, jumlah baris, jumlah nilai unik, atau persentil dari bidang tertentu. Group-by mengelompokkan baris berdasarkan nilai bidang, beberapa bidang, rentang numerik, jarak geografis, filter, interval numerik, interval tanggal, atau grid geografis. Anda juga dapat menambahkan agregasi metrik atau group-by di dalam suatu kelompok.

Category	Configuration type	Description
Metric aggregation	MinAggregation	Mengembalikan nilai minimum suatu bidang, mirip dengan `MIN` dalam SQL.
Metric aggregation	MaxAggregation	Mengembalikan nilai maksimum suatu bidang, mirip dengan `MAX` dalam SQL.
Metric aggregation	SumAggregation	Mengembalikan jumlah dari bidang numerik, mirip dengan `SUM` dalam SQL.
Metric aggregation	AvgAggregation	Mengembalikan nilai rata-rata suatu bidang, mirip dengan `AVG` dalam SQL.
Metric aggregation	CountAggregation	Mengembalikan jumlah baris di mana bidang tertentu memiliki nilai, mirip dengan `COUNT(field)` dalam SQL.
Metric aggregation	DistinctCountAggregation	Mengembalikan jumlah nilai unik dalam suatu bidang, mirip dengan `COUNT(DISTINCT field)` dalam SQL.
Metric aggregation	PercentilesAggregation	Mengembalikan satu atau beberapa persentil dari suatu bidang.
Metric aggregation	TopRowsAggregation	Mengembalikan beberapa baris pertama dalam setiap kelompok berdasarkan urutan yang ditentukan.
Group-by	GroupByField	Mengelompokkan baris berdasarkan nilai satu bidang.
Group-by	GroupByComposite	Mengelompokkan baris berdasarkan beberapa bidang dan mendukung token pagination.
Group-by	GroupByRange	Mengelompokkan baris berdasarkan rentang numerik.
Group-by	GroupByGeoDistance	Mengelompokkan baris berdasarkan rentang jarak dari titik pusat.
Group-by	GroupByFilter	Mengelompokkan baris berdasarkan beberapa filter.
Group-by	GroupByHistogram	Membuat histogram menggunakan interval numerik tetap.
Group-by	GroupByDateHistogram	Membuat histogram menggunakan interval tanggal atau waktu tetap.
Group-by	GroupByGeoGrid	Mengelompokkan baris berdasarkan grid GeoHash.

Penting

Pengurutan dan agregasi harus diaktifkan untuk bidang indeks pencarian yang digunakan dalam agregasi. Jenis bidang yang didukung bervariasi tergantung jenis agregasi. Untuk informasi tentang jenis bidang indeks pencarian dan pemetaannya ke jenis bidang tabel data, lihat Data types.
Agregasi beroperasi pada hasil kueri yang cocok. Permintaan yang berisi agregasi lebih kompleks daripada permintaan yang hanya mengambil baris. Jika Anda tidak memerlukan baris dalam respons, atur limit menjadi 0.
Perhitungan distinct count, persentil, dan group-by berdasarkan bidang menggunakan perhitungan perkiraan. Distinct count di bawah 10.000 mendekati nilai eksak. Pada distinct count sebesar 100 juta, kesalahan sekitar 2%. Persentil di ujung biasanya lebih akurat; misalnya, P1 dan P99 umumnya lebih akurat daripada P50. Perhitungan paralel untuk group-by berdasarkan bidang juga dapat menyebabkan kesalahan kecil.
Anda dapat menggabungkan beberapa agregasi. Jumlah agregasi yang besar atau tingkat bersarang yang dalam meningkatkan kompleksitas permintaan dan dapat meningkatkan latensi. Untuk batas bersarang, lihat Search index limits.

Panggil search untuk mengkueri data. Konfigurasikan SearchQuery.aggregationList untuk agregasi metrik dan SearchQuery.groupByList untuk group-by.

SearchResponse search(SearchRequest request)

Contoh berikut mengkueri semua baris dalam indeks pencarian, menghitung nilai minimum, maksimum, jumlah, rata-rata, jumlah baris, jumlah kategori unik, dan P50 dari harga, serta mengelompokkan baris berdasarkan kategori.

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

Parameter

Permintaan kueri

Jenis request adalah SearchRequest. Tabel berikut menjelaskan parameternya.

Name	Type	Description
tableName (required)	String	Nama tabel data.
indexName (required)	String	Nama indeks pencarian.
searchQuery (required)	SearchQuery	Kondisi kueri dan konfigurasi agregasi.
columnsToGet (optional)	SearchRequest.ColumnsToGet	Kolom yang dikembalikan. Parameter ini hanya berlaku ketika `TopRowsAggregation` mengembalikan baris dalam kelompok. Jika parameter ini tidak dikonfigurasi, hanya kolom kunci primer yang dikembalikan.
timeoutInMillisecond (optional)	int	Timeout kueri tingkat permintaan dalam milidetik. Nilai default: `-1`, yang menunjukkan bahwa tidak ada timeout kueri terpisah yang dikonfigurasi.
routingValues (optional)	`List<PrimaryKey>`	Nilai kunci primer dari bidang routing kustom. Anda tidak perlu mengonfigurasi parameter ini jika routing kustom tidak digunakan.

Konfigurasi kueri

Jenis request.searchQuery adalah SearchQuery. Tabel berikut menjelaskan parameter yang terkait dengan agregasi.

Name	Type	Description
query (required)	Query	Kondisi kueri yang menentukan cakupan agregasi. Untuk mengagregasi semua baris dalam indeks pencarian, gunakan `MatchAllQuery`.
aggregationList (optional)	`List<Aggregation>`	Konfigurasi agregasi metrik. Konfigurasikan minimal salah satu dari parameter ini dan `groupByList`.
groupByList (optional)	`List<GroupBy>`	Konfigurasi group-by. Konfigurasikan minimal salah satu dari parameter ini dan `aggregationList`.
limit (optional)	Integer	Jumlah maksimum baris yang dikembalikan. Nilai default: `10`. Atur parameter ini menjadi `0` jika Anda hanya memerlukan hasil agregasi.
offset (optional)	Integer	Posisi baris tempat kueri dimulai. Nilai default: `0`.
sort (optional)	Sort	Urutan pengurutan hasil kueri. Parameter ini tidak mengubah cakupan agregasi metrik atau group-by reguler.
trackTotalCount (optional)	int	Jumlah maksimum baris yang cocok yang diharapkan untuk dihitung. Jika parameter ini diatur ke `TRACK_TOTAL_COUNT`, Anda dapat memperoleh jumlah total hasil kueri yang cocok dari `SearchResponse.totalCount`.
filter (optional)	SearchFilter	Filter yang diterapkan pada hasil `query`. Agregasi beroperasi pada hasil yang telah difilter.

Agregasi metrik

Tambahkan objek parameter berikut ke request.searchQuery.aggregationList[]. aggName mengidentifikasi hasil yang sesuai dan harus unik dalam satu permintaan.

MinAggregation, MaxAggregation, dan AvgAggregation

Name	Type	Description
aggName (required)	String	Nama agregasi.
fieldName (required)	String	Nama bidang agregasi. Bidang Long, Double, dan Date didukung.
missing (optional)	ColumnValue	Nilai yang digunakan jika `fieldName` tidak tersedia. Jika parameter ini tidak dikonfigurasi, baris yang tidak memiliki bidang tersebut diabaikan.

SumAggregation

Name	Type	Description
aggName (required)	String	Nama agregasi.
fieldName (required)	String	Nama bidang agregasi. Bidang Long dan Double didukung.
missing (optional)	ColumnValue	Nilai yang digunakan dalam penjumlahan jika `fieldName` tidak tersedia. Jika parameter ini tidak dikonfigurasi, baris yang tidak memiliki bidang tersebut diabaikan.

CountAggregation

Name	Type	Description
aggName (required)	String	Nama agregasi.
fieldName (required)	String	Bidang yang nilainya yang tidak null dihitung. Bidang Long, Double, Boolean, Keyword, Date, IP, dan Geo-point didukung. Baris dalam kolom sparse yang tidak berisi bidang tersebut tidak dihitung.

Untuk menghitung semua hasil kueri yang cocok, konfigurasikan trackTotalCount dalam SearchQuery dan baca SearchResponse.totalCount. Untuk menghitung semua baris dalam indeks pencarian, gunakan MatchAllQuery.

DistinctCountAggregation

Name	Type	Description
aggName (required)	String	Nama agregasi.
fieldName (required)	String	Bidang yang jumlah nilai uniknya dihitung. Bidang Long, Double, Boolean, Keyword, Date, IP, dan Geo-point didukung.
missing (optional)	ColumnValue	Nilai yang digunakan untuk perhitungan distinct count jika `fieldName` tidak tersedia. Jika parameter ini tidak dikonfigurasi, baris yang tidak memiliki bidang tersebut diabaikan.

PercentilesAggregation

Name	Type	Description
aggName (required)	String	Nama agregasi.
fieldName (required)	String	Nama bidang agregasi. Bidang Long, Double, dan Date didukung.
percentiles (required)	`List<Double>`	Persentil yang dihitung, seperti `25.0`, `50.0`, `90.0`, dan `99.0`.
missing (optional)	ColumnValue	Nilai yang digunakan dalam perhitungan persentil jika `fieldName` tidak tersedia. Jika parameter ini tidak dikonfigurasi, baris yang tidak memiliki bidang tersebut diabaikan.

TopRowsAggregation

Gunakan TopRowsAggregation sebagai sub-agregasi dari group-by.

Name	Type	Description
aggName (required)	String	Nama agregasi.
limit (optional)	Integer	Jumlah maksimum baris yang dikembalikan dari setiap kelompok. Nilai default: `1`.
sort (optional)	Sort	Urutan pengurutan baris dalam suatu kelompok.

Parameter request.columnsToGet mengontrol kolom atribut yang dikembalikan. Untuk mengembalikan kolom atribut langsung dari indeks pencarian, simpan bidang tersebut saat membuat indeks pencarian. Jika tidak ada kolom yang ditentukan, hanya kunci primer yang dikembalikan.

Group-by

Tambahkan objek parameter berikut ke request.searchQuery.groupByList[]. groupByName mengidentifikasi hasil yang sesuai dan harus unik dalam satu permintaan.

GroupByField

Name	Type	Description
groupByName (required)	String	Nama group-by.
fieldName (required)	String	Nama bidang pengelompokan. Bidang Long, Double, Boolean, Keyword, Date, dan IP didukung.
size (optional)	Integer	Jumlah kelompok yang dikembalikan. Nilai default: `10`. Nilai maksimum: `2000`.
minDocCount (optional)	Long	Jumlah minimum baris dalam suatu kelompok. Kelompok dengan jumlah baris lebih sedikit tidak dikembalikan.
groupBySorters (optional)	`List<GroupBySorter>`	Aturan pengurutan kelompok. Secara default, kelompok diurutkan berdasarkan jumlah baris secara menurun. Beberapa aturan berlaku sesuai urutan penambahannya.
subAggregations (optional)	`List<Aggregation>`	Agregasi metrik yang dihitung dalam setiap kelompok.
subGroupBys (optional)	`List<GroupBy>`	Group-by yang diterapkan dalam setiap kelompok induk.

groupBySorters[] mendukung nilai-nilai berikut.

Value	Description
groupKeySortInAsc	Mengurutkan kelompok berdasarkan kunci secara leksikografis menaik.
groupKeySortInDesc	Mengurutkan kelompok berdasarkan kunci secara leksikografis menurun.
rowCountSortInAsc	Mengurutkan kelompok berdasarkan jumlah baris secara menaik.
rowCountSortInDesc	Mengurutkan kelompok berdasarkan jumlah baris secara menurun. Ini adalah nilai default.
subAggSortInAsc	Mengurutkan kelompok berdasarkan nilai sub-agregasi tertentu secara menaik.
subAggSortInDesc	Mengurutkan kelompok berdasarkan nilai sub-agregasi tertentu secara menurun.

GroupByComposite

Name	Type	Description
groupByName (required)	String	Nama group-by.
sources (required)	`List<GroupBy>`	Sumber pengelompokan untuk beberapa bidang. Maksimal 32 bidang didukung. Sumber dapat berupa `GroupByField`, `GroupByHistogram`, atau `GroupByDateHistogram`. Sumber bidang dapat menentukan nama, bidang, dan urutan pengurutan. Sumber histogram numerik juga dapat menentukan interval, dan sumber histogram tanggal dapat menentukan zona waktu tambahan. Sumber hanya dapat diurutkan berdasarkan kunci. Urutan default adalah menurun. Jika bidang tidak tersedia, kunci yang sesuai adalah `null`.
nextToken (optional)	String	Token pagination untuk halaman kelompok berikutnya. Abaikan parameter ini pada permintaan pertama. Jika `nextToken` dalam respons tidak kosong, gunakan nilainya tanpa perubahan pada permintaan berikutnya.
size (optional)	Integer	Jumlah kelompok yang dikembalikan. Nilai default: `10`. Nilai maksimum: `2000`. Dalam kebanyakan kasus, gunakan parameter ini untuk membatasi jumlah kelompok.
suggestedSize (optional)	Integer	Batas lunak untuk integrasi throughput tinggi dengan mesin komputasi seperti Spark dan Presto. Anda dapat mengatur parameter ini ke `-1` atau nilai yang lebih besar dari batas server. Jumlah aktual yang dikembalikan adalah `min(suggestedSize, server-side group limit, total groups)`. Jangan konfigurasi parameter ini dan `size` dalam permintaan yang sama.
subAggregations (optional)	`List<Aggregation>`	Sub-agregasi.
subGroupBys (optional)	`List<GroupBy>`	Sub-group-by. `GroupByComposite` tidak dapat digunakan sebagai sub-group-by.

Catatan

Tablestore SDK for Java merepresentasikan nextToken sebagai string. Jika Anda menyimpan atau mentransfer token tersebut, jangan ubah isinya.

GroupByRange

Name	Type	Description
groupByName (required)	String	Nama group-by.
fieldName (required)	String	Nama bidang pengelompokan. Bidang Long dan Double didukung.
ranges (required)	`List<Range>`	Rentang. Setiap rentang bersifat tertutup di kiri dan terbuka di kanan: `[from, to)`. Anda dapat menggunakan `Double.MIN_VALUE` dan `Double.MAX_VALUE` sebagai batas.
subAggregations (optional)	`List<Aggregation>`	Sub-agregasi.
subGroupBys (optional)	`List<GroupBy>`	Sub-group-by.

GroupByGeoDistance

Name	Type	Description
groupByName (required)	String	Nama group-by.
fieldName (required)	String	Nama bidang pengelompokan. Hanya bidang Geo-point yang didukung.
origin (required)	GeoPoint	Titik pusat. Parameter konstruktor adalah lintang diikuti bujur. Rentang lintang adalah `[-90,+90]`, dan rentang bujur adalah `[-180,+180]`.
ranges (required)	`List<Range>`	Rentang jarak dalam meter. Setiap rentang bersifat tertutup di kiri dan terbuka di kanan: `[from, to)`.
subAggregations (optional)	`List<Aggregation>`	Sub-agregasi.
subGroupBys (optional)	`List<GroupBy>`	Sub-group-by.

GroupByFilter

Name	Type	Description
groupByName (required)	String	Nama group-by.
filters (required)	`List<Query>`	Filter. Hasil dikembalikan sesuai urutan penambahan filter.
subAggregations (optional)	`List<Aggregation>`	Sub-agregasi.
subGroupBys (optional)	`List<GroupBy>`	Sub-group-by.

GroupByHistogram

Name	Type	Description
groupByName (required)	String	Nama group-by.
fieldName (required)	String	Nama bidang pengelompokan. Bidang Long dan Double didukung.
interval (required)	ColumnValue	Interval histogram.
fieldRange (optional)	FieldRange	Rentang agregasi, yang berisi `min` dan `max`. Nilai `(max-min)/interval` tidak boleh melebihi `2000`.
offset (optional)	ColumnValue	Offset batas bucket dari titik awal default.
minDocCount (optional)	Long	Jumlah minimum baris dalam suatu bucket. Bucket dengan jumlah baris lebih sedikit tidak dikembalikan.
missing (optional)	ColumnValue	Nilai yang digunakan dalam histogram jika `fieldName` tidak tersedia. Jika parameter ini tidak dikonfigurasi, baris yang tidak memiliki bidang tersebut diabaikan.
groupBySorters (optional)	`List<GroupBySorter>`	Aturan pengurutan bucket.
subAggregations (optional)	`List<Aggregation>`	Sub-agregasi.
subGroupBys (optional)	`List<GroupBy>`	Sub-group-by.

GroupByDateHistogram

Penting

Agregasi histogram tanggal didukung oleh Tablestore SDK for Java versi 5.16.1 ke atas. Jenis bidang Date untuk indeks pencarian didukung oleh Tablestore SDK for Java versi 5.13.9 ke atas. Untuk informasi versi, lihat Tablestore SDK for Java version history.

Name	Type	Description
groupByName (required)	String	Nama group-by.
fieldName (required)	String	Nama bidang pengelompokan. Hanya bidang Date yang didukung.
interval (required)	DateTimeValue	Interval tanggal atau waktu, yang terdiri dari nilai dan `DateTimeUnit`.
fieldRange (optional)	FieldRange	Rentang agregasi, yang berisi `min` dan `max`. Nilai `(max-min)/interval` tidak boleh melebihi `2000`.
minDocCount (optional)	Long	Jumlah minimum baris dalam suatu bucket. Bucket dengan jumlah baris lebih sedikit tidak dikembalikan.
missing (optional)	ColumnValue	Nilai tanggal yang digunakan dalam histogram jika `fieldName` tidak tersedia. Jika parameter ini tidak dikonfigurasi, baris yang tidak memiliki bidang tersebut diabaikan.
timeZone (optional)	String	Zona waktu dalam format `+hh:mm` atau `-hh:mm`, seperti `+08:00`. Jika format bidang Date tidak mencakup informasi zona waktu, konfigurasikan parameter ini untuk mencegah offset waktu dalam hasil agregasi.
groupBySorters (optional)	`List<GroupBySorter>`	Aturan pengurutan bucket.
subAggregations (optional)	`List<Aggregation>`	Sub-agregasi.
subGroupBys (optional)	`List<GroupBy>`	Sub-group-by.

GroupByGeoGrid

Name	Type	Description
groupByName (required)	String	Nama group-by.
fieldName (required)	String	Nama bidang pengelompokan. Hanya bidang Geo-point yang didukung.
precision (required)	GeoHashPrecision	Precisi grid GeoHash. Nilai berkisar dari `GHP_5009KM_4992KM_1`, yang kira-kira berukuran 5.009 km × 4.992 km, hingga `GHP_37MM_19MM_12`, yang kira-kira berukuran 37 mm × 19 mm. Akhiran yang lebih besar menunjukkan grid yang lebih kecil.
size (optional)	Integer	Jumlah kelompok grid yang dikembalikan.
subAggregations (optional)	`List<Aggregation>`	Sub-agregasi.
subGroupBys (optional)	`List<GroupBy>`	Sub-group-by.

Respons

Metode search mengembalikan SearchResponse. Tabel berikut menjelaskan bidang yang terkait dengan agregasi.

Name	Type	Description
aggregationResults	AggregationResults	Hasil agregasi metrik. Panggil `getAggregationResults()` untuk memperoleh nilai, dan gunakan nama agregasi untuk memperoleh tipe hasil tertentu.
groupByResults	GroupByResults	Hasil group-by. Panggil `getGroupByResults()` untuk memperoleh nilai, dan gunakan nama group-by untuk memperoleh tipe hasil tertentu.
totalCount	long	Jumlah hasil kueri yang cocok. Panggil `getTotalCount()` untuk memperoleh nilai. Nilai ini bergantung pada `trackTotalCount`.
isAllSuccess	boolean	Menunjukkan apakah semua partisi indeks telah dikueri. Panggil `isAllSuccess()` untuk memperoleh nilai. Jika bidang ini `false`, hasil agregasi mungkin tidak lengkap.

Hasil agregasi metrik

Configuration type	Result type	Result field and accessor
MinAggregation	MinAggregationResult	`value` bertipe `double`. Panggil `getAsMinAggregationResult(aggName).getValue()`.
MaxAggregation	MaxAggregationResult	`value` bertipe `double`. Panggil `getAsMaxAggregationResult(aggName).getValue()`.
SumAggregation	SumAggregationResult	`value` bertipe `double`. Panggil `getAsSumAggregationResult(aggName).getValue()`.
AvgAggregation	AvgAggregationResult	`value` bertipe `double`. Panggil `getAsAvgAggregationResult(aggName).getValue()`.
CountAggregation	CountAggregationResult	`value` bertipe `long`. Panggil `getAsCountAggregationResult(aggName).getValue()`.
DistinctCountAggregation	DistinctCountAggregationResult	`value` bertipe `long`. Panggil `getAsDistinctCountAggregationResult(aggName).getValue()`.
PercentilesAggregation	PercentilesAggregationResult	`percentilesAggregationItems` bertipe `List<PercentilesAggregationItem>`. Panggil `getAsPercentilesAggregationResult(aggName).getPercentilesAggregationItems()`. Setiap item berisi `key` dan `value`.
TopRowsAggregation	TopRowsAggregationResult	`rows` bertipe `List<Row>`. Panggil `getAsTopRowsAggregationResult(aggName).getRows()`.

Hasil group-by

Configuration type	Result type	Core result fields
GroupByField	GroupByFieldResult	`groupByFieldResultItems`. Setiap item berisi `key`, `rowCount`, `subAggregationResults`, dan `subGroupByResults`.
GroupByComposite	GroupByCompositeResult	`sourceNames`, `groupByCompositeResultItems`, dan `nextToken`. Posisi `keys` dalam setiap item sesuai dengan `sourceNames`.
GroupByRange	GroupByRangeResult	`groupByRangeResultItems`. Setiap item berisi `from`, `to`, dan `rowCount`.
GroupByGeoDistance	GroupByGeoDistanceResult	`groupByGeoDistanceResultItems`. Setiap item berisi jarak `from`, `to`, dan `rowCount`.
GroupByFilter	GroupByFilterResult	`groupByFilterResultItems`. Setiap item berisi `rowCount`, dan urutan item sesuai dengan urutan filter.
GroupByHistogram	GroupByHistogramResult	`groupByHistogramItems`. Setiap item berisi awal bucket `key` dan jumlah baris `value`.
GroupByDateHistogram	GroupByDateHistogramResult	`groupByDateHistogramItems`. Setiap item berisi timestamp milidetik `timestamp` dan `rowCount`.
GroupByGeoGrid	GroupByGeoGridResult	`groupByGeoGridResultItems`. Setiap item berisi GeoHash `key`, `geoGrid` dengan koordinat kiri-atas dan kanan-bawah, serta `rowCount`.

Contoh

Gunakan sub-agregasi dan sub-group-by

Contoh berikut mengelompokkan baris berdasarkan kategori, menghitung harga tertinggi dalam setiap kategori, lalu mengelompokkan baris dalam setiap kategori berdasarkan kota. Aturan pengurutan kelompok berlaku sesuai urutan penambahannya.

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

Lakukan pagination pada group-by multi-bidang

GroupByComposite mengembalikan kunci multi-kolom dalam struktur datar dan mendukung pagination melalui 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);

Kelompokkan berdasarkan rentang, jarak, dan filter

Kode berikut menunjukkan konfigurasi inti dari tiga jenis group-by. Anda dapat menggabungkannya dalam SearchQuery yang sama.

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

Buat histogram numerik dan tanggal

Contoh berikut mengelompokkan baris berdasarkan interval numerik 20 dan interval tanggal satu bulan.

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

Kelompokkan berdasarkan grid geografis

Contoh berikut mengelompokkan bidang geografis ke dalam grid GeoHash berukuran kira-kira 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());

Kembalikan baris dari kelompok

Contoh berikut mengelompokkan baris berdasarkan kategori dan mengembalikan baris dengan harga tertinggi dalam setiap kategori.

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

Perbandingan group-by multi-bidang

Untuk mengelompokkan berdasarkan beberapa bidang, bersarangkan beberapa konfigurasi GroupByField atau gunakan GroupByComposite secara langsung. Pilih berdasarkan kebutuhan pagination, struktur respons, dan aturan pengurutan.

Item	Nested field group-bys	Composite group-by
Configuration	Tambahkan `subGroupBys` ke `GroupByField` induk.	Tambahkan beberapa sumber pengelompokan ke `GroupByComposite.sources`.
Number of groups	Hingga 2.000 kelompok di setiap level.	Hingga 2.000 kelompok per halaman.
Number of fields	Hingga tiga level bersarang.	Hingga 32 bidang.
Response structure	Bersarang berdasarkan level induk dan anak.	Kunci multi-kolom dikembalikan sebagai daftar datar.
Pagination	Tidak didukung.	Didukung melalui `nextToken`.
Sorting	Mendukung pengurutan berdasarkan kunci kelompok, jumlah baris, atau nilai sub-agregasi.	Setiap sumber pengelompokan hanya mendukung pengurutan leksikografis berdasarkan kunci. Urutan default adalah menurun.
Sub-aggregations	Didukung.	Didukung.
Date field compatibility	Kunci kelompok menggunakan format tanggal yang ditentukan untuk bidang tersebut.	Kunci kelompok tanggal dikembalikan sebagai string timestamp.