Kueri Geo - Tablestore SDK untuk Python - Tablestore - Alibaba Cloud Documentation Center

Gunakan Tablestore SDK untuk Python untuk memfilter data berdasarkan jarak dari titik pusat, kotak pembatas (bounding box), atau poligon.

Prasyarat

Instal Tablestore SDK untuk Python dan inisialisasi klien.

Deskripsi

Kueri geo memfilter data berdasarkan lokasi geografis dalam bidang GeoPoint. Anda dapat melakukan kueri berdasarkan jarak, kotak pembatas, atau poligon. Saat memanggil metode search, atur jenis kueri menjadi GeoDistanceQuery, GeoBoundingBoxQuery, atau GeoPolygonQuery sesuai dengan rentang geografis yang diperlukan.

GeoDistanceQuery(field_name, center_point, distance)
GeoBoundingBoxQuery(field_name, top_left, bottom_right)
GeoPolygonQuery(field_name, points)

Contoh berikut melakukan kueri terhadap baris-baris di mana bidang location berjarak tidak lebih dari 200.000 meter dari 30,25,120,16 serta mengembalikan hingga 10 baris dan jumlah total baris yang cocok.

query = GeoDistanceQuery("location", "30.25,120.16", 200000)
search_query = SearchQuery(
    query,
    limit=10,
    get_total_count=True,
)
response = client.search(
    "example_table",
    "example_index",
    search_query,
    ColumnsToGet(return_type=ColumnReturnType.ALL),
)
print(response.total_count)
for row in response.rows:
    print(row)

Parameter

Permintaan pencarian

Metode search mencakup parameter-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`	Daftar nilai kunci primer untuk bidang routing kustom. Anda tidak perlu menentukan parameter ini 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 mencakup parameter-parameter berikut.

Name	Type	Description
query (required)	`Query`	Kondisi kueri. Atur parameter ini ke `GeoDistanceQuery`.
sort (optional)	`Sort`	Urutan pengurutan hasil kueri. Untuk informasi selengkapnya, lihat Sort and paginate results.
get_total_count (optional)	`bool`	Menentukan apakah jumlah total baris yang cocok dikembalikan. Nilai default: `False`. Mengatur parameter ini ke `True` meningkatkan beban kueri.
next_token (optional)	`bytes`	Token paginasi. Atur parameter ini ke `next_token` dari respons sebelumnya untuk mengambil halaman berikutnya. Untuk informasi selengkapnya, lihat Sort and paginate results.
offset (optional)	`int`	Offset tempat kueri saat ini dimulai. Gunakan parameter ini untuk paginasi dangkal.
limit (optional)	`int`	Jumlah maksimum baris yang dikembalikan. Jika parameter ini diatur ke `0`, tidak ada data baris yang dikembalikan.
aggs (optional)	`list[Agg]`	Konfigurasi agregasi. Untuk informasi selengkapnya, lihat Aggregation.
group_bys (optional)	`list[BaseGroupBy]`	Konfigurasi pengelompokan. Untuk informasi selengkapnya, lihat Aggregation.
collapse_field (optional)	`Collapse`	Konfigurasi collapsing hasil, yang menghapus hasil duplikat berdasarkan bidang tertentu. Untuk informasi selengkapnya, lihat Collapse query results.

Koordinat dalam ketiga jenis kueri menggunakan format latitude,longitude, dengan lintang mendahului bujur. Rentang lintang adalah [-90,+90] dan rentang bujur adalah [-180,+180]. Contoh: 35.8,-45.91.

Kondisi jarak geo

search_query.query bertipe GeoDistanceQuery dan mencakup parameter-parameter berikut.

Name	Type	Description
field_name (required)	`str`	Nama bidang `GeoPoint` yang akan dikueri.
center_point (required)	`str`	Koordinat titik pusat.
distance (required)	`float`	Jarak maksimum dari titik pusat. Satuan: meter.

Kondisi kotak pembatas geo

search_query.query bertipe GeoBoundingBoxQuery dan mencakup parameter-parameter berikut.

Name	Type	Description
field_name (required)	`str`	Nama bidang `GeoPoint` yang akan dikueri.
top_left (required)	`str`	Koordinat sudut kiri atas.
bottom_right (required)	`str`	Koordinat sudut kanan bawah.

Kondisi poligon geo

search_query.query bertipe GeoPolygonQuery dan mencakup parameter-parameter berikut.

Name	Type	Description
field_name (required)	`str`	Nama bidang `GeoPoint` yang akan dikueri.
points (required)	`list[str]`	Daftar koordinat yang membentuk poligon. Tentukan koordinat dalam urutan batas.

Kolom yang dikembalikan

columns_to_get bertipe ColumnsToGet dan mencakup parameter-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 dalam `column_names`; `ALL` mengembalikan semua kolom atribut dari tabel; dan `ALL_FROM_INDEX` mengembalikan semua kolom atribut yang diindeks.

Respons

Metode search mengembalikan SearchResponse. Tabel berikut menjelaskan bidang-bidang intinya.

Field	Type	Description
rows	`list[Row]`	Baris-baris yang dikembalikan oleh kueri saat ini. Jumlah baris tidak melebihi `limit`.
next_token	`bytes`	Token untuk halaman berikutnya. Jika bidang ini tidak kosong, teruskan ke permintaan berikutnya untuk melanjutkan pembacaan.
total_count	`int`	Jumlah baris yang cocok. Nilainya bergantung pada konfigurasi `get_total_count`.
is_all_succeed	`bool`	Menunjukkan apakah semua partisi indeks telah dikueri. Jika nilainya `False`, hasil parsial dikembalikan dan `total_count` mungkin kurang dari jumlah aktual baris yang cocok.
agg_results	`list[AggResult]`	Hasil agregasi. 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 skor relevansi, sorotan (highlights), dan baris anak yang cocok.

Respons kompatibel tupel

Mulai 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 error unpacking jika bidang respons diperluas.

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

Contoh

Kueri data dalam kotak pembatas

Contoh berikut mengkueri data dalam kotak pembatas yang dibatasi oleh koordinat sudut kiri atas 32.0,119.0 dan sudut kanan bawah 29.0,122.0.

query = GeoBoundingBoxQuery(
    "location",
    "32.0,119.0",
    "29.0,122.0",
)
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(query, limit=10),
    ColumnsToGet(return_type=ColumnReturnType.ALL),
)
print(response.rows)

Kueri data dalam poligon

Contoh berikut melakukan kueri terhadap data dalam poligon yang dibentuk oleh empat koordinat.

query = GeoPolygonQuery(
    "location",
    [
        "29.0,119.0",
        "32.0,119.0",
        "32.0,122.0",
        "29.0,122.0",
    ],
)
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(query, limit=10),
    ColumnsToGet(return_type=ColumnReturnType.ALL),
)
print(response.rows)