Bagikan melalui

Contoh kueri pencarian sederhana di Azure AI Search

  • Artikel

Di Azure AI Search, sintaks kueri sederhana memanggil pengurai kueri default untuk pencarian teks lengkap. Pengurai cepat dan menangani skenario umum, termasuk pencarian teks lengkap, pencarian yang difilter dan tersaring, dan pencarian awalan. Artikel ini menggunakan contoh untuk mengilustrasikan penggunaan sintaksis sederhana dalam permintaan Pencarian Dokumen (REST API).

Catatan

Sintaks kueri alternatif adalah Lucene, yang mendukung struktur kueri yang lebih kompleks, seperti pencarian fuzzy dan wildcard. Untuk informasi selengkapnya, lihat Contoh sintaks pencarian Lucene lengkap .

Indeks sampel hotel

Kueri berikut didasarkan pada indeks sampel hotel, yang dapat Anda buat dengan mengikuti instruksi di Mulai Cepat: Membuat indeks pencarian di portal Azure.

Contoh kueri diartikulasikan menggunakan permintaan REST API dan POST. Anda dapat menempelkan dan menjalankannya di klien REST. Atau, gunakan tampilan JSON penjelajah Pencarian di portal Azure. Dalam tampilan JSON, Anda bisa menempelkan contoh kueri yang diperlihatkan di sini dalam artikel ini.

Permintaan header harus memiliki nilai berikut:

Tombol Nilai
Content-Type application/json
api-key <your-search-service-api-key>, baik kueri atau kunci admin

Parameter URI harus menyertakan titik akhir layanan pencarian Anda dengan nama indeks, koleksi dokumen, perintah pencarian, dan versi API, mirip dengan contoh berikut:

https://{{service-name}}.search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2024-07-01

Isi permintaan harus dibentuk sebagai JSON yang valid:

{
    "search": "*",
    "queryType": "simple",
    "select": "HotelId, HotelName, Category, Tags, Description",
    "count": true
}

  • search diatur ke * adalah kueri yang tidak ditentukan, setara dengan pencarian null atau kosong. Ini tidak terlalu berguna, tetapi ini adalah pencarian paling sederhana yang dapat Anda lakukan, dan menunjukkan semua bidang yang dapat diambil dalam indeks, dengan semua nilai.

  • queryType diatur ke sederhana adalah default dan dapat dihilangkan, tetapi disertakan untuk menekankan bahwa contoh kueri dalam artikel ini dinyatakan dalam sintaks sederhana.

  • select diatur ke daftar bidang yang dibatasi koma digunakan untuk komposisi hasil pencarian, termasuk hanya bidang yang berguna dalam konteks hasil pencarian.

  • count mengembalikan jumlah dokumen yang cocok dengan kriteria pencarian. Pada string pencarian kosong, jumlahnya adalah semua dokumen dalam indeks (50 di indeks sampel hotel).

Contoh 1: Pencarian teks lengkap

Pencarian teks lengkap dapat berupa sejumlah istilah mandiri atau frasa yang diapit kutipan, dengan atau tanpa operator Boolean.

POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
    "search": "pool spa +airport",
    "searchMode": "any",
    "queryType": "simple",
    "select": "HotelId, HotelName, Category, Description",
    "count": true
}

Pencarian kata kunci yang terdiri dari istilah atau frasa penting cenderung berfungsi paling baik. Bidang string menjalani analisis teks selama pengindeksan dan kueri, menghilangkan kata-kata yang tidak penting seperti, dan, itu. Untuk melihat bagaimana untai kueri diberi token dalam indeks, teruskan untai dalam panggilan Analisis Teks ke indeks.

Parameter searchMode mengontrol presisi dan pengenalan. Jika Anda menginginkan lebih banyak pengenalan, gunakan nilai default apa pun , yang mengembalikan hasil jika ada bagian dari string kueri yang cocok. Jika Anda mendukung presisi, di mana semua bagian string harus dicocokkan, ubah searchMode ke semua. Coba kueri sebelumnya dengan kedua cara untuk melihat bagaimana searchMode mengubah hasil.

Respons untuk spa kumpulan +kueri bandara akan terlihat mirip dengan contoh berikut.

"@odata.count": 4,
"value": [
{
    "@search.score": 6.090657,
    "HotelId": "12",
    "HotelName": "Winter Panorama Resort",
    "Description": "Plenty of great skiing, outdoor ice skating, sleigh rides, tubing and snow biking. Yoga, group exercise classes and outdoor hockey are available year-round, plus numerous options for shopping as well as great spa services. Newly-renovated with large rooms, free 24-hr airport shuttle & a new restaurant. Rooms/suites offer mini-fridges & 49-inch HDTVs.",
    "Category": "Resort and Spa"
},
{
    "@search.score": 4.314683,
    "HotelId": "21",
    "HotelName": "Good Business Hotel",
    "Description": "1 Mile from the airport. Free WiFi, Outdoor Pool, Complimentary Airport Shuttle, 6 miles from Lake Lanier & 10 miles from downtown. Our business center includes printers, a copy machine, fax, and a work area.",
    "Category": "Suite"
},
{
    "@search.score": 3.575948,
    "HotelId": "27",
    "HotelName": "Starlight Suites",
    "Description": "Complimentary Airport Shuttle & WiFi. Book Now and save - Spacious All Suite Hotel, Indoor Outdoor Pool, Fitness Center, Florida Green certified, Complimentary Coffee, HDTV",
    "Category": "Suite"
},
{
    "@search.score": 2.6926985,
    "HotelId": "25",
    "HotelName": "Waterfront Scottish Inn",
    "Description": "Newly Redesigned Rooms & airport shuttle. Minutes from the airport, enjoy lakeside amenities, a resort-style pool & stylish new guestrooms with Internet TVs.",
    "Category": "Suite"
}
]

Perhatikan skor pencarian dalam respons. Ini adalah skor relevansi kecocokan. Secara default, layanan pencarian mengembalikan 50 kecocokan teratas berdasarkan skor ini.

Skor seragam 1,0 terjadi ketika tidak ada peringkat, baik karena pencarian bukan pencarian teks lengkap, atau karena tidak ada kriteria yang disediakan. Misalnya, dalam pencarian kosong (search=*), baris kembali dalam urutan arbitrer. Saat menyertakan kriteria aktual, Anda akan melihat skor pencarian berkembang menjadi nilai yang bermakna.

Contoh 2: Cari berdasarkan ID

Setelah hasil pencarian dikembalikan, langkah logis selanjutnya adalah menyediakan halaman detail yang menyertakan lebih banyak bidang dari dokumen. Contoh ini memperlihatkan kepada Anda cara mengembalikan satu dokumen menggunakan Dapatkan Dokumen dengan meneruskan ID dokumen.

GET /indexes/hotels-sample-index/docs/41?api-version=2024-07-01

Semua dokumen memiliki pengidentifikasi unik. Jika Anda menggunakan portal, pilih indeks dari tab Indeks lalu lihat definisi bidang untuk menentukan bidang mana yang menjadi kuncinya. Di REST API, panggilan Indeks GET mengembalikan definisi indeks dalam isi respons.

Respons untuk kueri sebelumnya terdiri dari dokumen yang kuncinya adalah 41. Bidang apa pun yang ditandai sebagai dapat diambil dalam definisi indeks dapat dikembalikan dalam hasil pencarian dan dirender di aplikasi Anda.

{
    "HotelId": "41",
    "HotelName": "Windy Ocean Motel",
    "Description": "Oceanfront hotel overlooking the beach features rooms with a private balcony and 2 indoor and outdoor pools. Inspired by the natural beauty of the island, each room includes an original painting of local scenes by the owner. Rooms include a mini fridge, Keurig coffee maker, and flatscreen TV. Various shops and art entertainment are on the boardwalk, just steps away.",
    "Description_fr": "Cet hôtel en bord de mer donnant sur la plage propose des chambres dotées d'un balcon privé et de 2 piscines intérieure et extérieure. Inspiré par la beauté naturelle de l'île, chaque chambre comprend une peinture originale de scènes locales par le propriétaire. Les chambres comprennent un mini-réfrigérateur, une cafetière Keurig et une télévision à écran plat. Divers magasins et divertissements artistiques se trouvent sur la promenade, à quelques pas.",
    "Category": "Suite",
    "Tags": [
    "pool",
    "air conditioning",
    "bar"
    ],
    "ParkingIncluded": true,
    "LastRenovationDate": "2021-05-10T00:00:00Z",
    "Rating": 3.5,
    "Location": {
    "type": "Point",
    "coordinates": [
        -157.846817,
        21.295841
    ],
    "crs": {
        "type": "name",
        "properties": {
        "name": "EPSG:4326"
        }
    }
    },
    "Address": {
    "StreetAddress": "1450 Ala Moana Blvd 2238 Ala Moana Ctr",
    "City": "Honolulu",
    "StateProvince": "HI",
    "PostalCode": "96814",
    "Country": "USA"
    }
}

Contoh 3: Memfilter teks

Sintaks filter adalah ekspresi OData yang dapat Anda gunakan dengan sendirinya atau dengan search. Ketika digunakan bersama-sama dalam permintaan yang sama, filter diterapkan terlebih dahulu ke seluruh indeks, dan kemudian search dilakukan pada hasil filter. Oleh karena itu, filter bisa menjadi teknik yang berguna untuk meningkatkan performa kueri karena mengurangi kumpulan dokumen yang perlu diproses oleh kueri pencarian.

Filter dapat didefinisikan pada bidang apa pun yang ditandai sebagai filterable dalam definisi indeks. Untuk indeks sampel hotel, bidang yang dapat difilter termasuk Kategori, Tag, ParkingIncluded, Peringkat, dan sebagian besar bidang Alamat. 

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "art tours",
    "queryType": "simple",
    "filter": "Category eq 'Boutique'",
    "searchFields": "HotelName,Description,Category",
    "select": "HotelId,HotelName,Description,Category",
    "count": true
}

Respons untuk kueri sebelumnya hanya dilingkupkan ke hotel-hotel yang dikategorikan sebagai Boutique, dan itu termasuk istilah seni atau tur. Dalam hal ini, hanya ada satu kecocokan.

"value": [
{
    "@search.score": 1.2814453,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.",
    "Category": "Boutique"
}
]

Contoh 4: Memfilter fungsi

Ekspresi filter dapat menyertakan fungsi search.ismatch dan search.ismatchscoring, yang memungkinkan Anda membuat kueri pencarian dalam filter. Ekspresi filter ini menggunakan kartubebas gratis untuk memilih fasilitas termasuk wifi gratis, parkir gratis, dan sebagainya.

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
  {
    "search": "",
    "filter": "search.ismatch('free*', 'Tags', 'full', 'any')",
    "select": "HotelName, Tags, Description",
    "count": true
  }

Respons untuk kueri sebelumnya cocok pada 27 hotel yang menawarkan fasilitas gratis. Perhatikan bahwa skor pencarian adalah seragam 1 di seluruh hasil. Ini karena ekspresi pencarian null atau kosong, yang mengakibatkan filter verbatim cocok, tetapi tidak ada pencarian teks lengkap. Skor relevansi hanya dikembalikan pada pencarian teks lengkap. Jika Anda menggunakan filter tanpa search, pastikan Anda memiliki bidang yang cukup dapat diurutkan sehingga Anda dapat mengontrol peringkat pencarian.

  "@odata.count": 27,
  "value": [
    {
      "@search.score": 1,
      "HotelName": "Country Residence Hotel",
      "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door.",
      "Tags": [
        "laundry service",
        "restaurant",
        "free parking"
      ]
    },
    {
      "@search.score": 1,
      "HotelName": "Downtown Mix Hotel",
      "Description": "Mix and mingle in the heart of the city. Shop and dine, mix and mingle in the heart of downtown, where fab lake views unite with a cheeky design.",
      "Tags": [
        "air conditioning",
        "laundry service",
        "free wifi"
      ]
    },
    {
      "@search.score": 1,
      "HotelName": "Starlight Suites",
      "Description": "Complimentary Airport Shuttle & WiFi. Book Now and save - Spacious All Suite Hotel, Indoor Outdoor Pool, Fitness Center, Florida Green certified, Complimentary Coffee, HDTV",
      "Tags": [
        "pool",
        "coffee in lobby",
        "free wifi"
      ]
    },
. . .

Contoh 5: Filter rentang

Pemfilteran rentang didukung melalui ekspresi filter untuk tipe data apa pun. Contoh berikut mengilustrasikan rentang numerik dan untai. Jenis data adalah hal yang penting dalam filter rentang dan bekerja paling baik saat data numerik berada dalam bidang numerik, dan untai data berada dalam bidang untai. Data numerik dalam bidang string tidak cocok untuk rentang karena string numerik tidak sebanding.

Kueri berikut ini adalah rentang numerik. Dalam hotel-sample-index, satu-satunya bidang numerik yang dapat difilter adalah Rating.

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "*",
    "filter": "Rating ge 2 and Rating lt 4",
    "select": "HotelId, HotelName, Rating",
    "orderby": "Rating desc",
    "count": true
}

Respons untuk kueri ini akan terlihat mirip dengan contoh berikut, dipangkas untuk brevity.

"@odata.count": 27,
"value": [
{
    "@search.score": 1,
    "HotelId": "22",
    "HotelName": "Lion's Den Inn",
    "Rating": 3.9
},
{
    "@search.score": 1,
    "HotelId": "25",
    "HotelName": "Waterfront Scottish Inn",
    "Rating": 3.8
},
{
    "@search.score": 1,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Rating": 3.6
},
...

Kueri berikutnya adalah filter rentang di atas bidang untai (Address/StateProvince):

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "*",
    "filter": "Address/StateProvince ge 'A*' and Address/StateProvince lt 'D*'",
    "select": "HotelId, HotelName, Address/StateProvince",
    "count": true
}

Respons untuk kueri ini akan terlihat mirip dengan contoh berikut, dipangkas untuk brevity. Dalam contoh ini, tidak dimungkinkan untuk mengurutkan berdasarkan StateProvince karena bidang tidak dikaitkan sebagai dapat diurutkan dalam definisi indeks.

{
  "@odata.count": 9,
  "value": [
    {
      "@search.score": 1,
      "HotelId": "39",
      "HotelName": "White Mountain Lodge & Suites",
      "Address": {
        "StateProvince": "CO"
      }
    },
    {
      "@search.score": 1,
      "HotelId": "9",
      "HotelName": "Smile Up Hotel",
      "Address": {
        "StateProvince": "CA "
      }
    },
    {
      "@search.score": 1,
      "HotelId": "7",
      "HotelName": "Roach Motel",
      "Address": {
        "StateProvince": "CA "
      }
    },
    {
      "@search.score": 1,
      "HotelId": "34",
      "HotelName": "Lakefront Captain Inn",
      "Address": {
        "StateProvince": "CT"
      }
    },
    {
      "@search.score": 1,
      "HotelId": "37",
      "HotelName": "Campus Commander Hotel",
      "Address": {
        "StateProvince": "CA "
      }
    },
. . .

Indeks sampel hotel mencakup bidang Lokasi dengan koordinat garis lintang dan bujur. Contoh ini menggunakan fungsi geo.distance yang memfilter pada dokumen dalam lingkar titik awal, hingga jarak arbitrer (dalam kilometer) yang Anda sediakan. Anda bisa menyesuaikan nilai terakhir dalam kueri (10) untuk mengurangi atau memperbesar area permukaan kueri.

POST /indexes/v/docs/search?api-version=2024-07-01
{
    "search": "*",
    "filter": "geo.distance(Location, geography'POINT(-122.335114 47.612839)') le 10",
    "select": "HotelId, HotelName, Address/City, Address/StateProvince",
    "count": true
}

Respons untuk kueri ini mengembalikan semua hotel dalam jarak 10 kilometer dari koordinat yang disediakan:

{
  "@odata.count": 3,
  "value": [
    {
      "@search.score": 1,
      "HotelId": "45",
      "HotelName": "Happy Lake Resort & Restaurant",
      "Address": {
        "City": "Seattle",
        "StateProvince": "WA"
      }
    },
    {
      "@search.score": 1,
      "HotelId": "24",
      "HotelName": "Uptown Chic Hotel",
      "Address": {
        "City": "Seattle",
        "StateProvince": "WA"
      }
    },
    {
      "@search.score": 1,
      "HotelId": "16",
      "HotelName": "Double Sanctuary Resort",
      "Address": {
        "City": "Seattle",
        "StateProvince": "WA"
      }
    }
  ]
}

Contoh 7: Booleans dengan searchMode

Sintaks sederhana mendukung operator Boolean dalam bentuk karakter (+, -, |) untuk mendukung logika kueri AND, OR, dan NOT. Pencarian Boolean berperilaku seperti yang Anda harapkan, dengan beberapa pengecualian penting.

Dalam pencarian Boolean, pertimbangkan untuk menambahkan searchMode parameter sebagai mekanisme untuk menginfluensikan presisi dan pengenalan. Nilai yang valid termasuk "searchMode": "any" mendukung pengenalan (dokumen yang memenuhi salah satu kriteria dianggap cocok), dan "searchMode": "all" presisi yang mendukung (semua kriteria harus dicocokkan dalam dokumen).

Dalam konteks pencarian Boolean, defaultnya "searchMode": "any" bisa membingungkan jika Anda menumpuk kueri dengan beberapa operator dan mendapatkan hasil yang lebih luas alih-alih hasil yang lebih sempit. Ini terutama berlaku dengan NOT, di mana hasilnya mencakup semua dokumen yang tidak berisi istilah atau frasa tertentu.

Contoh berikut memberikan ilustrasi. Kueri mencari kecocokan di restoran yang mengecualikan AC frasa. Jika Anda menjalankan kueri berikut dengan searchMode (apa pun), 43 dokumen dikembalikan: yang berisi istilah restoran, ditambah semua dokumen yang tidak memiliki frasa *AC.

Perhatikan bahwa tidak ada ruang antara operator boolean (-) dan AC frasa. Tanda kutip lolos (\").

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "restaurant -\"air conditioning\"",
    "searchMode": "any",
    "searchFields": "Tags",
    "select": "HotelId, HotelName, Tags",
    "count": true
}

Mengubah untuk memberlakukan efek kumulatif pada kriteria dan mengembalikan tataan hasil yang lebih kecil (tujuh kecocokan"searchMode": "all") yang terdiri dari dokumen yang berisi istilah restoran, dikurangi yang berisi AC frasa.

Respons untuk kueri ini sekarang akan terlihat mirip dengan contoh berikut, dipangkas untuk brevity.

{
  "@odata.count": 14,
  "value": [
    {
      "@search.score": 3.1383743,
      "HotelId": "18",
      "HotelName": "Ocean Water Resort & Spa",
      "Tags": [
        "view",
        "pool",
        "restaurant"
      ]
    },
    {
      "@search.score": 2.028083,
      "HotelId": "22",
      "HotelName": "Lion's Den Inn",
      "Tags": [
        "laundry service",
        "free wifi",
        "restaurant"
      ]
    },
    {
      "@search.score": 2.028083,
      "HotelId": "34",
      "HotelName": "Lakefront Captain Inn",
      "Tags": [
        "restaurant",
        "laundry service",
        "coffee in lobby"
      ]
    },
...

Contoh 8: Hasil penomoran

Dalam contoh sebelumnya, Anda mempelajari tentang parameter yang memengaruhi komposisi hasil pencarian, termasuk select yang menentukan bidang mana yang dalam hasil, urutan pengurutan, dan cara menyertakan hitungan semua kecocokan. Contoh ini adalah kelanjutan dari komposisi hasil pencarian dalam bentuk parameter penomoran yang memungkinkan Anda untuk mengelompokkan jumlah hasil yang muncul di halaman tertentu.

Secara default, layanan pencarian mengembalikan 50 kecocokan teratas. Untuk mengontrol jumlah kecocokan di setiap halaman, gunakan top untuk menentukan ukuran batch, lalu gunakan skip untuk mengambil batch berikutnya.

Contoh berikut menggunakan filter dan urutan pengurutan pada bidang (Peringkat dapat difilter Rating dan dapat diurutkan) karena lebih mudah untuk melihat efek penomoran halaman pada hasil yang diurutkan. Dalam kueri pencarian penuh reguler, kecocokan teratas diberi peringkat dan di halaman oleh @search.score.

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "*",
    "filter": "Rating gt 4",
    "select": "HotelName, Rating",
    "orderby": "Rating desc",
    "top": 5,
    "count": true
}

Kueri menemukan 21 dokumen yang cocok, tetapi karena Anda menentukan , respons hanya mengembalikan lima kecocokan topteratas, dengan peringkat mulai dari 4,9, dan berakhir pada 4,7 dengan Lakeside B & B.

Untuk mendapatkan lima berikutnya, lewati batch pertama:

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "*",
    "filter": "Rating gt 4",
    "select": "HotelName, Rating",
    "orderby": "Rating desc",
    "top": 5,
    "skip": 5,
    "count": true
}

Respons untuk batch kedua melewati lima pertandingan pertama, mengembalikan lima pertandingan berikutnya, dimulai dengan Pull'r Inn Motel. Untuk melanjutkan dengan lebih banyak batch, Anda akan menyimpan top di lima, dan kemudian bertambah skip lima pada setiap permintaan baru (skip=5, skip=10, skip=15, dan sebagainya).

{
  "@odata.count": 21,
  "value": [
    {
      "@search.score": 1,
      "HotelName": "Head Wind Resort",
      "Rating": 4.7
    },
    {
      "@search.score": 1,
      "HotelName": "Sublime Palace Hotel",
      "Rating": 4.6
    },
    {
      "@search.score": 1,
      "HotelName": "City Skyline Antiquity Hotel",
      "Rating": 4.5
    },
    {
      "@search.score": 1,
      "HotelName": "Nordick's Valley Motel",
      "Rating": 4.5
    },
    {
      "@search.score": 1,
      "HotelName": "Winter Panorama Resort",
      "Rating": 4.5
    }
  ]
}

Konten terkait

Sekarang setelah Anda berlatih sintaksis kueri dasar, coba tentukan kueri dalam kode. Tautan berikut mencakup cara menyiapkan kueri pencarian menggunakan Azure SDK.

Referensi sintaks lainnya, arsitektur kueri, dan contoh dapat ditemukan di tautan berikut: