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

Pencarian Azure AI mendukung kueri geo-spasial dalam ekspresi filter OData melalui fungsi geo.distance 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.

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:

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.

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 Pencarian Azure AI, 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 yang bukan persegi panjang atau tidak sejajar, pertimbangkan pendekatan poligon terpisah.

Fungsi geo-spasial dan null

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

• Dalam filter, geo.distance dari bidang null menghasilkan null. Karena null dibandingkan dengan nilai bukan nol akan dievaluasi menjadi false, ini berarti dokumen tidak akan cocok.
• 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 urutan-order

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

• Filter di Pencarian Azure AI
• Gambaran umum bahasa ekspresi OData untuk Pencarian Azure AI
• Referensi sintaks ekspresi OData untuk Pencarian Azure AI
• Pencarian Dokumen (Pencarian Azure AI REST API)