Mengurutkan dan membagi hasil ke dalam halaman - Tablestore SDK untuk Python - Tablestore

Gunakan Tablestore SDK untuk Python untuk mengontrol urutan hasil indeks pencarian dan membagi hasil ke dalam halaman menggunakan offset atau next_token.

Prasyarat

Pasang Tablestore SDK untuk Python dan inisialisasi klien.

Deskripsi

Indeks pencarian mendukung pengurutan awal indeks (index presorting) dan pengurutan saat kueri. Saat membuat indeks pencarian, gunakan index_sort untuk menentukan urutan default. Jika index_sort tidak ditentukan, baris diurutkan berdasarkan primary key. Pengurutan awal indeks hanya mendukung PrimaryKeySort dan FieldSort, serta tidak didukung untuk indeks yang berisi bidang Nested. Setelah pembuatan, Anda dapat memperbarui skema secara dinamis untuk mengubah pengurutan awal indeks. Saat kueri, gunakan SearchQuery.sort untuk menentukan ScoreSort, PrimaryKeySort, FieldSort, atau GeoDistanceSort, atau gabungkan beberapa sorter sesuai urutan daftar. Kecuali untuk primary key, bidang pengurutan harus memiliki fitur sorting dan aggregation yang diaktifkan saat indeks dibuat.

Metode Paginasi	Deskripsi
limit and offset	Gunakan ketika hasil tidak melebihi 100.000 baris dan Anda perlu melompat ke posisi tertentu. `limit + offset` tidak boleh melebihi `100000`.
next_token	Gunakan untuk pagination mendalam atau membaca semua hasil secara berurutan. Kedalaman pagination tidak tunduk pada batas 100.000 baris, tetapi halaman hanya dapat dibaca secara berurutan.

Contoh berikut mengembalikan 10 baris pertama yang diurutkan berdasarkan score secara descending, lalu berdasarkan primary key secara ascending.

sort = Sort([
    FieldSort("score", SortOrder.DESC),
    PrimaryKeySort(SortOrder.ASC),
])
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(MatchAllQuery(), sort=sort, limit=10),
    ColumnsToGet(return_type=ColumnReturnType.ALL),
)
print(response.rows)

Parameter

Permintaan pencarian

Metode search mencakup parameter berikut.

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

Konfigurasi kueri

search_query bertipe SearchQuery dan mencakup parameter pengurutan dan pagination berikut.

Nama	Tipe	Deskripsi
query (wajib)	`Query`	Kondisi kueri.
sort (opsional)	`Sort`	Konfigurasi pengurutan saat kueri. Jika diabaikan, pengurutan awal indeks akan digunakan. Jangan tentukan parameter ini saat menggunakan `next_token`.
offset (opsional)	`int`	Offset. Nilai default: `0`. Jangan tentukan parameter ini saat menggunakan `next_token`.
limit (opsional)	`int`	Jumlah maksimum baris yang dikembalikan. Nilai default: `10`. Maksimum adalah `100` jika ada kolom yang dikembalikan harus dibaca dari tabel, dan `1000` jika semua kolom yang dikembalikan dibaca dari indeks pencarian.
next_token (opsional)	`bytes`	Token pagination. Abaikan pada permintaan pertama dan gunakan `next_token` dari respons sebelumnya pada permintaan berikutnya.
get_total_count (opsional)	`bool`	Menentukan apakah jumlah total baris yang cocok dikembalikan. Nilai default: `False`.

Konfigurasi pengurutan

search_query.sort bertipe Sort dan mencakup parameter berikut.

Nama	Tipe	Deskripsi
sorters (wajib)	`list[Sorter]`	Daftar sorter. Urutan daftar menentukan prioritas pengurutan multi-level. Jenis sorter yang didukung adalah `ScoreSort`, `PrimaryKeySort`, `FieldSort`, dan `GeoDistanceSort`.

Pengurutan berdasarkan skor relevansi

Jika search_query.sort.sorters[] bertipe ScoreSort, baris diurutkan berdasarkan skor relevansi. ScoreSort mencakup parameter berikut.

Nama	Tipe	Deskripsi
sort_order (opsional)	`SortOrder`	Urutan pengurutan. Nilai default: `DESC`. Konfigurasikan secara eksplisit `ScoreSort` untuk mengurutkan berdasarkan skor relevansi.

Pengurutan berdasarkan primary key

Jika search_query.sort.sorters[] bertipe PrimaryKeySort, baris diurutkan berdasarkan primary key. PrimaryKeySort mencakup parameter berikut.

Nama	Tipe	Deskripsi
sort_order (opsional)	`SortOrder`	Urutan pengurutan. Nilai default: `ASC`.

Pengurutan berdasarkan bidang

Jika search_query.sort.sorters[] bertipe FieldSort, baris diurutkan berdasarkan nilai bidang. FieldSort mencakup parameter berikut.

Nama	Tipe	Deskripsi
field_name (wajib)	`str`	Nama bidang pengurutan. Fitur sorting dan aggregation harus diaktifkan untuk bidang tersebut.
sort_order (opsional)	`SortOrder`	Urutan pengurutan. Nilai default: `ASC`.
sort_mode (opsional)	`SortMode`	Mode pemilihan nilai untuk bidang bernilai ganda: `MIN`, `MAX`, atau `AVG`.
nested_filter (opsional)	`NestedFilter`	Konfigurasi pengurutan bidang anak Nested, termasuk path Nested dan kueri yang memilih baris anak yang digunakan untuk pengurutan.

Pengurutan berdasarkan jarak geografis

Jika search_query.sort.sorters[] bertipe GeoDistanceSort, baris diurutkan berdasarkan jarak antara titik geografis dan titik target. GeoDistanceSort mencakup parameter berikut.

Nama	Tipe	Deskripsi
field_name (wajib)	`str`	Nama bidang GeoPoint untuk pengurutan.
points (wajib)	`list[str]`	Titik target dalam format `latitude,longitude`.
sort_order (opsional)	`SortOrder`	`ASC` mengurutkan dari terdekat ke terjauh, dan `DESC` mengurutkan dari terjauh ke terdekat.
sort_mode (opsional)	`SortMode`	Mode pemilihan nilai ketika terdapat beberapa jarak: `MIN`, `MAX`, atau `AVG`.
geo_distance_type (opsional)	`GeoDistanceType`	Metode perhitungan jarak. `ARC` (default) menggunakan model bola, sedangkan `PLANE` menggunakan model datar.
nested_filter (opsional)	`NestedFilter`	Konfigurasi pengurutan bidang anak Nested.

Kolom yang dikembalikan

columns_to_get bertipe ColumnsToGet dan mencakup parameter berikut.

Nama	Tipe	Deskripsi
column_names (opsional)	`list[str]`	Nama kolom atribut yang dikembalikan. Tentukan parameter ini hanya ketika `return_type` bernilai `SPECIFIED`.
return_type (opsional)	`ColumnReturnType`	Mode kolom yang dikembalikan. `NONE` (default) hanya mengembalikan kolom primary key; `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 intinya.

Bidang	Tipe	Deskripsi
rows	`list[Row]`	Baris yang dikembalikan oleh kueri. Jumlahnya tidak melebihi `limit`.
next_token	`bytes`	Token untuk halaman berikutnya. Nilai kosong menunjukkan bahwa tidak ada data tambahan yang tersedia.
total_count	`int`	Jumlah baris yang cocok. Nilainya bergantung pada `get_total_count`.
is_all_succeed	`bool`	Menunjukkan apakah semua partisi indeks telah dikueri. 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 (highlights).

next_token yang kosong juga dapat menunjukkan bahwa kueri tidak memiliki urutan pengurutan deterministik. total_count adalah jumlah total baris yang cocok, bukan jumlah baris pada halaman saat ini.

Respons kompatibel tupel

Mulai dari Tablestore SDK untuk Python versi 5.2.0, API pencarian mengembalikan objek respons, bukan tupel. Versi 5.1.0 dan sebelumnya mengembalikan tupel secara langsung. Pada versi 5.2.1 dan seterusnya, Anda dapat memanggil SearchResponse.v1_response() untuk mendapatkan tupel 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

Mengurutkan berdasarkan jarak geografis

Contoh berikut mengembalikan hasil dari terdekat ke terjauh berdasarkan jarak bola antara location dan 30.25,120.16.

sort = Sort([
    GeoDistanceSort(
        "location",
        ["30.25,120.16"],
        sort_order=SortOrder.ASC,
        sort_mode=SortMode.MIN,
        geo_distance_type=GeoDistanceType.ARC,
    )
])
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(MatchAllQuery(), sort=sort, limit=10),
)
print(response.rows)

Pagination menggunakan next_token

Tentukan urutan pengurutan pada permintaan pertama. Pada permintaan berikutnya, cukup berikan next_token dari respons sebelumnya dan kondisi kueri yang sama hingga token tersebut kosong.

query = MatchAllQuery()
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(query, sort=Sort([PrimaryKeySort()]), limit=100),
)
all_rows = list(response.rows)

while response.next_token:
    response = client.search(
        "example_table",
        "example_index",
        SearchQuery(query, next_token=response.next_token, limit=100),
    )
    all_rows.extend(response.rows)

print(len(all_rows))

Penting

Saat melakukan pagination menggunakan next_token, jangan tentukan offset, dan halaman tidak dapat dilewati secara langsung. Untuk berpindah mundur, simpan token yang digunakan untuk setiap halaman dan lakukan kueri ulang dengan token untuk halaman target. Indeks pencarian yang berisi bidang Nested tidak memiliki pengurutan awal indeks. Tentukan secara eksplisit sort pada permintaan pertama, atau server tidak akan mengembalikan next_token.

Tablestore:Mengurutkan dan membagi hasil ke dalam halaman