Contoh kueri pencarian simple di Pencarian Azure AI

Dalam Pencarian Azure AI, sintaks kueri sederhana memanggil pengurai kueri default untuk pencarian teks lengkap. Pengurai cepat dan menangani skenario umum, termasuk pencarian teks lengkap, pencarian terfilter 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 Quickstart: Pencarian teks lengkap di Azure portal.

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

Permintaan header harus memiliki nilai berikut:

Kunci Nilai
Jenis-Konten application/json
kunci API <your-search-service-api-key>, baik kueri atau kunci admin

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

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

Isi permintaan harus dibentuk sebagai JSON yang valid:

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

  • search dikonfigurasikan sebagai * 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 dalam 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=2026-04-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 penarikan data, gunakan nilai default apa pun, yang akan 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 dari query kolam spa +bandara harus terlihat serupa 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 bawaan, sebuah layanan pencarian mengembalikan 50 kecocokan teratas berdasarkan skor ini.

Skor seragam 1,0 terjadi ketika tidak ada peringkat, baik karena pencarian tidak pencarian teks lengkap, atau karena tidak ada kriteria yang disediakan. Misalnya, dalam pencarian kosong (search=*), baris akan muncul 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/docs/41?api-version=2026-04-01

Semua dokumen memiliki pengidentifikasi unik. Jika Anda menggunakan Azure portal, pilih indeks dari tab Indexes 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/docs/search?api-version=2026-04-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: Fungsi Filter

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/docs/search?api-version=2026-04-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. Skor pencarian adalah seragam 1 di seluruh hasil. Ini karena ekspresi pencarian bernilai null atau kosong, yang menyebabkan filter verbatim menghasilkan kecocokan, tetapi tidak ada pencarian teks penuh. 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 merupakan hal yang penting dalam penyaring rentang dan bekerja paling baik saat data numerik berada dalam bidang numerik, dan data string berada dalam bidang string. Data numerik dalam kolom string tidak cocok untuk rentang karena string numerik tidak dapat dibandingkan.

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

POST /indexes/hotels-sample/docs/search?api-version=2026-04-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 kejelasan.

"@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 untuk bidang string (Address/StateProvince):

POST /indexes/hotels-sample/docs/search?api-version=2026-04-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 kejelasan. 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 dapat menyesuaikan nilai terakhir dalam kueri (10) untuk mengurangi atau memperbesar area permukaan kueri.

POST /indexes/v/docs/search?api-version=2026-04-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" memprioritaskan keteringatan (dokumen yang memenuhi salah satu kriteria dianggap cocok), dan "searchMode": "all" memprioritaskan presisi (semua kriteria harus dicocokkan dalam dokumen).

Dalam konteks pencarian Boolean, pengaturan default "searchMode": "any" bisa membingungkan jika Anda menggabungkan kueri dengan beberapa operator dan menghasilkan hasil yang lebih luas daripada 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 frasa AC. Jika Anda menjalankan kueri berikut dengan searchMode (apa pun), 43 dokumen dikembalikan: yang berisi istilah restoran, ditambah semua dokumen yang tidak memiliki frasa *AC.

Tidak ada spasi antara operator boolean (-) dan frasa air conditioning. Tanda kutip lolos (\").

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

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

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

{
  "@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 bawaan, layanan pencarian mengembalikan 50 hasil 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 Rating (Peringkat dapat difilter dan diurutkan) karena lebih mudah untuk melihat efek penomoran halaman pada hasil yang diurutkan. Dalam kueri pencarian lengkap reguler, kecocokan teratas diberi peringkat dan dipisah dalam halaman oleh @search.score.

POST /indexes/hotels-sample/docs/search?api-version=2026-04-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 top, respons hanya mengembalikan lima kecocokan teratas, 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/docs/search?api-version=2026-04-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 kumpulan, Anda harus mempertahankan top pada angka lima, dan kemudian menaikkan skip sebanyak lima setiap kali ada permintaan baru (skip=5, skip=10, skip=15, dan seterusnya).

{
  "@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

  • Last updated on