Fungsi geo-spasial OData di Pencarian Azure AI - geo.distance dan geo.intersects

  • Artikel

Azure AI Search mendukung kueri geo-spasial dalam ekspresi filter OData melalui geo.distance fungsi dan geo.intersects . Fungsi geo.distance ini mengembalikan jarak dalam kilometer antara dua titik, satu menjadi variabel bidang atau rentang, dan satu menjadi konstanta yang dilewati sebagai bagian dari filter. Fungsi geo.intersects mengembalikan true jika titik tertentu berada dalam poligon tertentu, di mana titiknya adalah variabel bidang atau rentang dan poligon ditentukan sebagai konstanta yang diteruskan sebagai bagian dari filter.

Fungsi geo.distance juga dapat digunakan dalam parameter $orderby dari untuk mengurutkan hasil pencarian dengan jarak dari titik tertentu. Sintaksis untuk geo.distance dalam $orderby sama dengan yang ada di $filter. Saat menggunakan geo.distance dalam $orderby, bidang yang diterapkannya harus memiliki tipe Edm.GeographyPoint dan juga harus dapat diurutkan.

Catatan

Saat menggunakan geo.distance di dalam parameter $orderby, bidang yang Anda lewati ke fungsi hanya harus berisi satu titik geo. Dengan kata lain, harus berjenis Edm.GeographyPoint dan bukan Collection(Edm.GeographyPoint). Tidak dimungkinkan untuk mengurutkan bidang koleksi di Azure AI Search.

Sintaks

EBNF (Extended Backus-Naur Form) berikut mendefinisikan tata bahasa geo.distance dan geo.intersects fungsi, serta nilai geo-spasial tempat mereka beroperasi:

geo_distance_call ::=
    'geo.distance(' variable ',' geo_point ')'
    | 'geo.distance(' geo_point ',' variable ')'

geo_point ::= "geography'POINT(" lon_lat ")'"

lon_lat ::= float_literal ' ' float_literal

geo_intersects_call ::=
    'geo.intersects(' variable ',' geo_polygon ')'

/* You need at least four points to form a polygon, where the first and
last points are the same. */
geo_polygon ::=
    "geography'POLYGON((" lon_lat ',' lon_lat ',' lon_lat ',' lon_lat_list "))'"

lon_lat_list ::= lon_lat(',' lon_lat)*

Diagram sintaksis interaktif juga tersedia:

Diagram sintaks OData untuk Azure AI Search

Catatan

Lihat Referensi sintaks ekspresi OData untuk Pencarian Azure AI untuk EBNF lengkap.

geo.distance

Fungsi geo.distance mengambil dua parameter jenis Edm.GeographyPoint dan mengembalikan nilai Edm.Double yang merupakan jarak di antaranya dalam kilometer. Ini berbeda dari layanan lain yang mendukung operasi geo-spasial OData, yang biasanya mengembalikan jarak dalam meter.

Salah satu parameter kegeo.distance harus merupakan konstanta titik geografi, dan yang lainnya harus merupakan jalur bidang (atau variabel rentang dalam kasus filter yang berulang di atas bidang jenis Collection(Edm.GeographyPoint)). Urutan parameter ini tidak penting.

Konstanta titik geografi adalah formulir geography'POINT(<longitude> <latitude>)', di mana garis bujur dan lintang adalah konstanta numerik.

Catatan

Saat menggunakan geo.distance di dalam filter, Anda harus membandingkan jarak yang dikembalikan oleh fungsi dengan konstanta menggunakan lt, le, gt, atau ge. Operator eq dan ne tidak didukung saat membandingkan jarak. Misalnya, berikut adalah penggunaan yang benar dari geo.distance: $filter=geo.distance(location, geography'POINT(-122.131577 47.678581)') le 5.

geo.intersects

Fungsi geo.intersects ini mengambil variabel jenis Edm.GeographyPoint dan konstanta Edm.GeographyPolygon dan mengembalikan sebuah Edm.Boolean -- true jika titik berada dalam batas poligon, jika tidak false.

Poligon adalah permukaan dua dimensi yang disimpan sebagai urutan titik yang mendefinisikan cincin batas (lihat contoh di bawah). Poligon perlu ditutup, artinya set poin pertama dan terakhir harus sama. Titik-titik dalam poligon harus dalam urutan berlawanan arah jarum jam.

Kueri geo-spasial dan poligon yang mencakup meridian ke-180

Bagi banyak pustaka kueri geo-spasial, merumuskan kueri yang menyertakan meridian ke-180 (di dekat garis tanggal) adalah melampau batasnya atau memerlukan solusi sementara, seperti memisahkan poligon menjadi dua, satu di kedua sisi meridian.

Dalam Azure AI Search, kueri geo-spasial yang menyertakan bujur 180 derajat akan berfungsi seperti yang diharapkan jika bentuk kueri berbentuk persegi panjang dan koordinat Anda selaras dengan tata letak kisi di sepanjang bujur dan lintang (misalnya, geo.intersects(location, geography'POLYGON((179 65, 179 66, -179 66, -179 65, 179 65))'). Jika tidak, untuk bentuk non-persegi panjang atau tidak sejajar, pertimbangkan pendekatan poligon terpisah.

Fungsi geo-spasial dan null

Seperti semua bidang non-koleksi lainnya di Azure AI Search, bidang jenis Edm.GeographyPoint dapat berisi null nilai. Saat Azure AI Search mengevaluasi geo.intersects bidang yaitu null, hasilnya akan falseselalu . Perilaku geo.distance dalam hal ini tergantung pada konteks:

  • Dalam filter, geo.distance dari bidang null menghasilkan null. Ini berarti dokumen tidak akan cocok karena null dibandingkan dengan nilai bukan nol yang dievaluasi ke false.
  • Saat mengurutkan hasil menggunakan $orderby, bidang geo.distance dari null menghasilkan jarak maksimum yang mungkin. Dokumen dengan bidang seperti itu akan mengurutkan lebih rendah daripada yang lain saat arah pengurutan asc digunakan (default), dan lebih tinggi dari yang lain saat arahnya desc.

Contoh

Contoh filter

Temukan semua hotel dalam jarak 10 kilometer dari titik referensi tertentu (di mana lokasi adalah bidang tipe Edm.GeographyPoint):

    geo.distance(location, geography'POINT(-122.131577 47.678581)') le 10

Temukan semua hotel dalam viewport tertentu yang digambarkan sebagai poligon (di mana lokasi adalah bidang jenis Edm.GeographyPoint). Perhatikan bahwa poligon ditutup (set poin pertama dan terakhir harus sama) dan poin harus dicantumkan dalam urutan berlawanan arah jarum jam.

    geo.intersects(location, geography'POLYGON((-122.031577 47.578581, -122.031577 47.678581, -122.131577 47.678581, -122.031577 47.578581))')

Contoh order-by

Urutkan hotel secara menurun menurut rating, lalu naik menurut jaraknya dari koordinat yang diberikan:

    rating desc,geo.distance(location, geography'POINT(-122.131577 47.678581)') asc

Urutkan hotel dalam urutan menurun menurut search.score dan rating, lalu dalam urutan menaik menurut jarak dari koordinat yang diberikan sehingga di antara dua hotel dengan peringkat yang identik, yang terdekat dicantumkan terlebih dahulu:

    search.score() desc,rating desc,geo.distance(location, geography'POINT(-122.131577 47.678581)') asc

Langkah berikutnya