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

Gunakan Tablestore SDK for Python untuk melakukan agregasi metrik dan pengelompokan pada hasil indeks pencarian.

Prasyarat

Instal Tablestore SDK for Python dan inisialisasi klien.

Fitur agregasi memerlukan SDK versi 5.2.1 atau lebih baru. Disarankan untuk menggunakan versi SDK terbaru.

Deskripsi

Agregasi menghitung metrik atau membuat kelompok dari hasil kueri indeks pencarian. Tambahkan objek agregasi metrik ke SearchQuery.aggs dan objek pengelompokan ke SearchQuery.group_bys. Setiap name dalam permintaan harus unik dan mengidentifikasi hasil respons yang sesuai. Untuk hanya mengambil hasil agregasi, atur limit menjadi 0.

Feature	Description
Min, Max, Sum, Avg	Hitung nilai minimum, maksimum, jumlah, dan rata-rata.
Count, DistinctCount	Hitung baris dengan nilai bidang tidak kosong dan nilai bidang unik.
Percentiles	Hitung satu atau beberapa persentil.
TopRows	Kembalikan baris teratas yang diurutkan dalam setiap kelompok sebagai sub-agregasi.
GroupByField, GroupByComposite	Kelompokkan berdasarkan satu nilai bidang atau kombinasi beberapa bidang.
GroupByRange, GroupByGeoDistance, GroupByFilter	Kelompokkan berdasarkan rentang numerik, jarak geografis, atau kondisi filter.
GroupByHistogram, GroupByDateHistogram, GroupByGeoGrid	Buat histogram numerik, histogram tanggal, atau kelompok grid GeoHash.

Penting

Bidang indeks pencarian yang digunakan untuk agregasi harus memiliki fitur sorting dan aggregation yang diaktifkan. Jenis bidang yang didukung bervariasi tergantung pada jenis agregasi dan pengelompokan. Anda dapat mengonfigurasi hingga lima pengelompokan pada tingkat yang sama. Perhitungan distinct count, percentiles, dan field grouping bersifat perkiraan. Jumlah agregasi yang besar atau agregasi bertingkat yang dalam akan meningkatkan kompleksitas dan latensi permintaan.

Contoh berikut menghitung nilai minimum, maksimum, dan rata-rata dari price serta mengelompokkan baris berdasarkan category.

search_query = SearchQuery(
    MatchAllQuery(),
    limit=0,
    aggs=[
        Min("price", name="min_price"),
        Max("price", name="max_price"),
        Avg("price", name="avg_price"),
    ],
    group_bys=[
        GroupByField("category", name="by_category"),
    ],
)
response = client.search(
    "example_table",
    "example_index",
    search_query,
)
for result in response.agg_results:
    print(result.name, result.value)
for result in response.group_by_results:
    print(result.name, result.items)

Parameter

Permintaan pencarian

Metode search memiliki parameter berikut.

Name	Type	Description
table_name (required)	`str`	Nama tabel data.
index_name (required)	`str`	Nama indeks pencarian.
search_query (required)	`SearchQuery`	Kondisi kueri dan konfigurasi kueri umum.
columns_to_get (optional)	`ColumnsToGet`	Konfigurasi kolom yang dikembalikan. Jika parameter ini tidak ditentukan, hanya kolom kunci primer yang dikembalikan.
routing_keys (optional)	`list`	Nilai kunci primer dari bidang routing kustom. Parameter ini tidak diperlukan jika routing kustom tidak dikonfigurasi.
timeout_s (optional)	`int`	Timeout permintaan dalam detik. Jika parameter ini tidak ditentukan, timeout tingkat client akan digunakan.

Konfigurasi kueri

search_query bertipe SearchQuery dan memiliki parameter berikut yang terkait agregasi.

Name	Type	Description
query (required)	`Query`	Kondisi kueri yang menentukan cakupan agregasi. Gunakan `MatchAllQuery` untuk mengagregasi semua baris.
aggs (optional)	`list[Agg]`	Daftar agregasi metrik. Anda dapat menggabungkan agregasi dengan nama berbeda.
group_bys (optional)	`list[BaseGroupBy]`	Daftar pengelompokan. Anda dapat menggabungkan pengelompokan dengan nama berbeda.
limit (optional)	`int`	Jumlah baris kueri yang dikembalikan. Atur parameter ini ke `0` untuk hanya mengambil hasil agregasi.

Agregasi metrik

Tambahkan objek berikut ke search_query.aggs. field adalah bidang agregasi, name mengidentifikasi hasilnya, dan missing_value digunakan ketika bidang tersebut tidak tersedia. Jika missing_value tidak ditentukan, baris yang tidak memiliki bidang tersebut akan diabaikan.

Min, Max, dan Avg

Name	Type	Description
field (required)	`str`	Bidang agregasi. Jenis yang didukung: `Long`, `Double`, dan `Date`.
missing_value (optional)	`str / int / float`	Nilai yang digunakan ketika bidang tidak tersedia.
name (optional)	`str`	Nama agregasi. Nilai default: `min`, `max`, dan `avg`, masing-masing.

Sum

Name	Type	Description
field (required)	`str`	Bidang agregasi. Jenis yang didukung: `Long` dan `Double`.
missing_value (optional)	`int / float`	Nilai yang digunakan dalam penjumlahan ketika bidang tidak tersedia.
name (optional)	`str`	Nama agregasi. Nilai default: `sum`.

Count

Name	Type	Description
field (required)	`str`	Bidang yang baris tidak kosongnya dihitung. Jenis yang didukung: `Long`, `Double`, `Boolean`, `Keyword`, `Date`, dan `GeoPoint`.
name (optional)	`str`	Nama agregasi. Nilai default: `count`.

DistinctCount

Name	Type	Description
field (required)	`str`	Bidang yang nilai uniknya dihitung. Jenis yang didukung: `Long`, `Double`, `Boolean`, `Keyword`, `Date`, dan `GeoPoint`.
missing_value (optional)	`str / int / float / bool`	Nilai yang disertakan dalam perhitungan nilai unik ketika bidang tidak tersedia.
name (optional)	`str`	Nama agregasi. Nilai default: `distinct_count`.

Percentiles

Name	Type	Description
field (required)	`str`	Bidang agregasi. Jenis yang didukung: `Long`, `Double`, dan `Date`.
percentiles_list (required)	`list[float]`	Persentil yang akan dihitung, seperti `[50, 90, 99]`.
missing_value (optional)	`str / int / float`	Nilai yang digunakan ketika bidang tidak tersedia.
name (optional)	`str`	Nama agregasi. Nilai default: `percentiles`.

TopRows

Name	Type	Description
limit (required)	`int`	Jumlah maksimum baris yang dikembalikan dari setiap kelompok.
sort (required)	`Sort`	Urutan pengurutan baris dalam setiap kelompok.
name (optional)	`str`	Nama agregasi. Nilai default: `top_rows`.

Catatan

DistinctCount bersifat perkiraan. Hasilnya mendekati akurat untuk kurang dari 10.000 nilai unik, dan kesalahan sekitar 2% pada 100 juta nilai. Percentiles juga perkiraan, dan persentil ekstrem biasanya lebih akurat daripada median. Gunakan TopRows hanya sebagai sub-agregasi dari pengelompokan.

Pengelompokan

Tambahkan objek berikut ke search_query.group_bys. Gunakan sub_aggs dan sub_group_bys untuk melakukan sub-agregasi metrik dan sub-pengelompokan dalam setiap kelompok.

GroupByField

Name	Type	Description
field_name (required)	`str`	Bidang pengelompokan. Jenis yang didukung: `Long`, `Double`, `Boolean`, `Keyword`, dan `Date`.
size (optional)	`int`	Jumlah kelompok yang dikembalikan. Nilai default: `10`. Nilai maksimum: `2000`.
group_by_sort (optional)	`list`	Aturan pengurutan kelompok. Secara default, kelompok diurutkan berdasarkan jumlah baris secara menurun. `GroupKeySort`, `RowCountSort`, dan `SubAggSort` didukung.
sub_aggs (optional)	`list[Agg]`	Sub-agregasi metrik.
sub_group_bys (optional)	`list[BaseGroupBy]`	Sub-pengelompokan.
name (optional)	`str`	Nama pengelompokan. Nilai default: `group_by_field`.

GroupByComposite

Name	Type	Description
sources (required)	`list[BaseGroupBy]`	Sumber pengelompokan multi-bidang. Anda dapat menentukan hingga 32 sumber bertipe `GroupByField`, `GroupByHistogram`, atau `GroupByDateHistogram`.
size (optional)	`int`	Jumlah kelompok yang dikembalikan. Nilai default: `10`. Nilai maksimum: `2000`.
next_token (optional)	`bytes`	Token untuk halaman kelompok berikutnya. Abaikan pada permintaan pertama.
suggested_size (optional)	`int`	Batas lunak untuk skenario komputasi throughput tinggi. Jangan tentukan bersamaan dengan `size`.
sub_aggs (optional)	`list[Agg]`	Sub-agregasi metrik.
sub_group_bys (optional)	`list[BaseGroupBy]`	Sub-pengelompokan. `GroupByComposite` tidak dapat menjadi sub-kelompok dari pengelompokan lain.
name (optional)	`str`	Nama pengelompokan. Nilai default: `group_by_composite`.

GroupByRange

Name	Type	Description
field_name (required)	`str`	Bidang pengelompokan. Jenis yang didukung: `Long` dan `Double`.
ranges (required)	`list[tuple]`	Rentang tertutup-kiri, terbuka-kanan, seperti `[(0, 100), (100, 200)]`.
sub_aggs (optional)	`list[Agg]`	Sub-agregasi metrik.
sub_group_bys (optional)	`list[BaseGroupBy]`	Sub-pengelompokan.
name (optional)	`str`	Nama pengelompokan. Nilai default: `group_by_range`.

GroupByGeoDistance

Name	Type	Description
field_name (required)	`str`	Bidang pengelompokan `GeoPoint`.
origin (required)	`GeoPoint`	Titik pusat. Parameter konstruktor berupa lintang diikuti bujur.
ranges (required)	`list[tuple]`	Rentang jarak dalam meter. Setiap rentang bersifat tertutup-kiri dan terbuka-kanan.
sub_aggs (optional)	`list[Agg]`	Sub-agregasi metrik.
sub_group_bys (optional)	`list[BaseGroupBy]`	Sub-pengelompokan.
name (optional)	`str`	Nama pengelompokan. Nilai default: `group_by_geo_distance`.

GroupByFilter

Name	Type	Description
filters (required)	`list[Query]`	Kondisi filter. Urutan hasil mengikuti urutan kondisi.
sub_aggs (optional)	`list[Agg]`	Sub-agregasi metrik.
sub_group_bys (optional)	`list[BaseGroupBy]`	Sub-pengelompokan.
name (optional)	`str`	Nama pengelompokan. Nilai default: `group_by_filter`.

GroupByHistogram

Name	Type	Description
field_name (required)	`str`	Bidang pengelompokan. Jenis yang didukung: `Long` dan `Double`.
interval (required)	`int / float`	Interval histogram numerik.
field_range (required)	`FieldRange`	Rentang agregasi. `(max-min)/interval` tidak boleh melebihi `2000`.
missing_value (optional)	`int / float`	Nilai yang digunakan dalam histogram ketika bidang tidak tersedia.
min_doc_count (optional)	`int`	Jumlah baris minimum untuk sebuah bucket. Bucket dengan jumlah baris lebih sedikit tidak dikembalikan.
group_by_sort (optional)	`list`	Aturan pengurutan kelompok.
sub_aggs (optional)	`list[Agg]`	Sub-agregasi metrik.
sub_group_bys (optional)	`list[BaseGroupBy]`	Sub-pengelompokan.
name (optional)	`str`	Nama pengelompokan. Nilai default: `group_by_histogram`.

GroupByDateHistogram

Name	Type	Description
field_name (required)	`str`	Bidang pengelompokan `Date`.
interval (required)	`DateTimeValue`	Interval tanggal atau waktu, terdiri atas nilai dan `DateTimeUnit`.
field_range (required)	`FieldRange`	Rentang agregasi. Server mewajibkan parameter ini meskipun konstruktor Python memperbolehkan penggunaannya diabaikan.
missing (optional)	`str`	Nilai tanggal yang digunakan dalam histogram ketika bidang tidak tersedia.
min_doc_count (optional)	`int`	Jumlah baris minimum untuk sebuah bucket. Bucket dengan jumlah baris lebih sedikit tidak dikembalikan.
time_zone (optional)	`str`	Zona waktu dalam format `+hh:mm` atau `-hh:mm`, seperti `+08:00`.
group_by_sort (optional)	`list`	Aturan pengurutan kelompok.
offset (optional)	`DateTimeValue`	Offset batas bucket dari origin default.
sub_aggs (optional)	`list[Agg]`	Sub-agregasi metrik.
sub_group_bys (optional)	`list[BaseGroupBy]`	Sub-pengelompokan.
name (optional)	`str`	Nama pengelompokan. Nilai default: `group_by_date_histogram`.

GroupByGeoGrid

Name	Type	Description
field_name (required)	`str`	Bidang pengelompokan `GeoPoint`.
precision (required)	`GeoHashPrecision`	Precisi grid GeoHash. Angka enum yang lebih tinggi merepresentasikan grid yang lebih kecil.
size (optional)	`int`	Jumlah kelompok grid yang dikembalikan.
sub_aggs (optional)	`list[Agg]`	Sub-agregasi metrik.
sub_group_bys (optional)	`list[BaseGroupBy]`	Sub-pengelompokan.
name (optional)	`str`	Nama pengelompokan. Nilai default: `group_by_geo_grid`.

Catatan

GroupByComposite memerlukan Tablestore SDK for Python versi 6.4.4 atau lebih baru. Jika terdapat banyak kelompok, tentukan size dan lakukan paginasi menggunakan next_token dari setiap hasil hingga token tersebut kosong.

Kolom yang dikembalikan

columns_to_get bertipe ColumnsToGet dan memiliki parameter berikut.

Name	Type	Description
column_names (optional)	`list[str]`	Nama kolom atribut yang dikembalikan. Tentukan parameter ini hanya ketika `return_type` bernilai `SPECIFIED`.
return_type (optional)	`ColumnReturnType`	Mode kolom yang dikembalikan. `NONE` (default) hanya mengembalikan kolom kunci primer; `SPECIFIED` mengembalikan kolom atribut yang ditentukan; `ALL` mengembalikan semua kolom atribut dalam tabel; dan `ALL_FROM_INDEX` mengembalikan semua bidang yang disimpan dalam indeks.

Respons

Metode search mengembalikan SearchResponse. Tabel berikut menjelaskan bidang utamanya.

Field	Type	Description
rows	`list[Row]`	Baris yang dikembalikan oleh kueri. Jumlahnya tidak melebihi `limit`.
next_token	`bytes`	Token untuk halaman berikutnya. Nilai kosong menunjukkan tidak ada data tambahan.
total_count	`int`	Jumlah baris yang cocok. Nilainya bergantung pada `get_total_count`.
is_all_succeed	`bool`	Menunjukkan apakah semua partisi indeks telah diinterogasi. Jika nilainya `False`, hasil parsial dikembalikan.
agg_results	`list[AggResult]`	Hasil agregasi metrik. Bidang ini kosong jika `aggs` tidak dikonfigurasi.
group_by_results	`list[GroupByResult]`	Hasil pengelompokan. Bidang ini kosong jika `group_bys` tidak dikonfigurasi.
search_hits	`list[SearchHit]`	Hasil pencarian, termasuk informasi tambahan seperti baris, skor relevansi, dan sorotan.

Setiap item dalam agg_results menggunakan name dan value untuk mengidentifikasi agregasi dan nilainya. Setiap item dalam group_by_results menggunakan name dan items untuk mengembalikan kunci kelompok, jumlah baris, sub-agregasi, dan sub-pengelompokan. Hasil GroupByComposite juga berisi source_group_by_names dan next_token untuk pembacaan lanjutan. keys dari setiap kelompok merupakan daftar string yang selaras dengan sources; nilai bidang yang tidak tersedia direpresentasikan dengan None.

Respons kompatibel tuple

Mulai Tablestore SDK for Python versi 5.2.0, API pencarian mengembalikan objek respons, bukan tuple. Versi 5.1.0 dan sebelumnya mengembalikan tuple secara langsung. Pada versi 5.2.1 dan seterusnya, Anda dapat memanggil SearchResponse.v1_response() untuk mendapatkan tuple yang kompatibel dengan versi sebelumnya. Untuk kode baru, akses atribut SearchResponse secara langsung guna menghindari kesalahan unpacking jika bidang respons diperluas.

(
    rows,
    next_token,
    total_count,
    is_all_succeed,
    agg_results,
    group_by_results,
    search_hits,
) = response.v1_response()

Contoh

Paginasi pengelompokan multi-bidang

Contoh berikut mengelompokkan berdasarkan category dan price serta mengembalikan dua kelompok per halaman.

sources = [
    GroupByField("category", name="category_source"),
    GroupByField("price", name="price_source"),
]
next_token = None
all_items = []

while True:
    group_by = GroupByComposite(
        sources,
        size=2,
        next_token=next_token,
        name="by_category_and_price",
    )
    response = client.search(
        "example_table",
        "example_index",
        SearchQuery(MatchAllQuery(), limit=0, group_bys=[group_by]),
    )
    result = response.group_by_results[0]
    all_items.extend(result.items)
    next_token = result.next_token
    if not next_token:
        break

for item in all_items:
    print(item.keys, item.row_count)

Buat histogram tanggal dan grid geografis

Contoh berikut membuat histogram harian dan mengelompokkan lokasi ke dalam grid GeoHash berukuran sekitar 39 km × 19 km.

group_bys = [
    GroupByDateHistogram(
        "event_date",
        DateTimeValue(1, DateTimeUnit.DAY),
        field_range=FieldRange("2026-08-01", "2026-08-04"),
        name="by_day",
    ),
    GroupByGeoGrid(
        "location",
        GeoHashPrecision.GHP_39KM_19KM_4,
        name="by_geo_grid",
    ),
]
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(MatchAllQuery(), limit=0, group_bys=group_bys),
)
for result in response.group_by_results:
    print(result.name, result.items)