Membuat kueri teks lengkap di Azure AI Search

Jika Anda membuat kueri untuk pencarian teks lengkap, artikel ini menyediakan langkah-langkah untuk menyiapkan permintaan. Ini juga memperkenalkan struktur kueri, dan menjelaskan bagaimana atribut bidang dan penganalisis linguistik dapat memengaruhi hasil kueri.

Prasyarat

• Layanan Azure AI Search (tingkat apa pun). Buat layanan atau definisikan yang sudah ada.

• Indeks pencarian dengan kolom string yang dikaitkan sebagai dapat dicari. Anda juga dapat menggunakan alias indeks sebagai titik akhir permintaan kueri Anda.

• Izin untuk mengkueri indeks:

  • autentikasi berbasis kunci: Kunci API kueri untuk layanan pencarian Anda.
  • Autentikasi berbasis peran: Peran Pembaca Data Indeks Pencarian .

• Untuk pengembangan SDK, instal pustaka klien Azure Search:

  • Python: azure-search-documents
  • .NET: Azure. Search.Documents
  • JavaScript: @azure/search-documents
  • Java: azure-search-documents

Tip

Untuk contoh kode cepat, lewati ke Contoh permintaan kueri teks lengkap.

Contoh permintaan kueri teks lengkap

Dalam Azure AI Search, kueri adalah permintaan baca-saja terhadap kumpulan dokumen dari satu indeks pencarian, dengan parameter yang menginformasikan eksekusi kueri dan membentuk respons yang diterima.

Kueri teks lengkap ditentukan dalam search parameter dan terdiri dari istilah, frasa yang diapit kutipan, dan operator. Parameter lain menambahkan lebih banyak definisi ke permintaan.

Panggilan Search POST REST API berikut mengilustrasikan permintaan kueri menggunakan search dan parameter lainnya.

POST https://[service name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2025-09-01
{
    "search": "NY +view",
    "queryType": "simple",
    "searchMode": "all",
    "searchFields": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "select": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "top": 10,
    "count": true
}

Referensi:Cari POST

Poin-poin penting

• search menyediakan kriteria kecocokan, biasanya seluruh istilah atau frasa, dengan atau tanpa operator. Bidang apa pun yang diatribusikan sebagai dapat dicari dalam skema indeks berada dalam cakupan untuk operasi pencarian.

• queryType mengatur pengurai: sederhana, penuh. Pengurai kueri sederhana default optimal untuk pencarian teks lengkap. Parser kueri Lucene lengkap digunakan untuk konstruksi kueri tingkat lanjut seperti ekspresi reguler, pencarian kedekatan, pencarian fuzzy, dan pencarian wildcard. Parameter ini juga dapat diatur ke semantik untuk peringkat semantik untuk pemodelan semantik tingkat lanjut pada respons kueri.

• searchMode menentukan apakah kecocokan didasarkan pada semua kriteria (mendukung presisi) atau kriteria apa pun (mendukung pengenalan) dalam ekspresi. Defaultnya adalah apa pun. Jika Anda mengantisipasi penggunaan operator Boolean yang berat, yang lebih mungkin dalam indeks yang berisi blok teks besar (bidang konten atau deskripsi panjang), pastikan untuk menguji kueri dengan searchMode=Any|All parameter untuk mengevaluasi dampak pengaturan tersebut pada pencarian Boolean.

• searchFields membatasi eksekusi kueri ke bidang tertentu yang dapat dicari. Selama pengembangan, sangat berguna untuk menggunakan daftar bidang yang sama untuk memilih dan mencari. Jika tidak, kecocokan mungkin didasarkan pada nilai bidang yang tidak dapat Anda lihat dalam hasil, menciptakan ketidakpastian mengapa dokumen dikembalikan.

Parameter yang digunakan untuk membentuk respons:

• select menentukan bidang mana yang akan dikembalikan dalam respons. Hanya bidang yang ditandai sebagai dapat diambil dalam indeks yang dapat digunakan dalam pernyataan tertentu.

• top mengembalikan jumlah yang ditentukan dari dokumen yang paling cocok. Dalam contoh ini, hanya 10 hits yang dikembalikan. Anda bisa menggunakan "top" dan "skip" (tidak diperlihatkan) untuk menavigasi hasil halaman.

• count memberi tahu Anda berapa banyak dokumen di seluruh indeks yang cocok secara keseluruhan, yang bisa lebih dari apa yang dikembalikan. Nilai yang valid adalah "true" atau "false". Secara bawaan adalah "false". Hitungan akurat jika indeks stabil, tetapi akan melaporkan kurang atau berlebihan pada dokumen apa pun yang ditambahkan, diperbarui, atau dihapus secara aktif. Jika Anda hanya ingin mendapatkan hitungan tanpa dokumen apa pun, Anda dapat menggunakan $top=0.

• orderby digunakan jika Anda ingin mengurutkan hasil menurut nilai, seperti peringkat atau lokasi. Jika tidak, defaultnya adalah menggunakan skor relevansi untuk memberi peringkat hasil. Bidang harus dikaitkan sebagai dapat diurutkan untuk menjadi kandidat untuk parameter ini.

Memilih klien

Untuk pengembangan awal dan pengujian bukti konsep, mulailah dengan Azure portal atau klien REST atau Jupyter notebook. Pendekatan ini interaktif, berguna untuk pengujian yang ditargetkan, dan membantu Anda menilai efek properti yang berbeda tanpa harus menulis kode apa pun.

Untuk memanggil pencarian dari dalam aplikasi, gunakan pustaka klien Azure.Document.Search di SDK Azure untuk .NET, Java, JavaScript, dan Python.

Portal Azure

Di portal Azure, saat membuka indeks, Anda dapat bekerja dengan Search Explorer bersama definisi JSON indeks di tab berdampingan untuk memudahkan akses atribut bidang. Periksa tabel Bidang untuk melihat tabel mana yang dapat dicari, dapat diurutkan, dapat difilter, dan dapat difaset saat menguji kueri.

1. Buka layanan pencarian Anda di portal Microsoft Azure.

2. Di layanan Anda, pilih Indeks dan pilih indeks.

3. Indeks terbuka ke tab Penjelajah pencarian sehingga Anda bisa langsung mengkueri. Beralih ke tampilan JSON untuk menentukan sintaks kueri.

   Berikut adalah ekspresi kueri pencarian teks lengkap yang berfungsi untuk indeks sampel hotel:

      {
          "search": "pool spa +airport",
          "queryType": "simple",
          "searchMode": "any",
          "searchFields": "Description, Tags",
          "select": "HotelName, Description, Tags",
          "top": 10,
          "count": true
      }
   

   Referensi:Cari POST

   Cuplikan layar berikut mengilustrasikan kueri dan respons:

   

REST API

Ketika dipanggil dengan GET, panjang URL permintaan tidak boleh melebihi 8 KB. Panjang ini cukup untuk sebagian besar aplikasi. Namun, beberapa aplikasi menghasilkan kueri besar, khususnya ketika ekspresi filter OData digunakan. Untuk aplikasi ini, HTTP POST adalah pilihan yang lebih baik karena memungkinkan filter yang lebih besar daripada GET.

Dengan POST, jumlah klausul dalam filter adalah faktor pembatasan, bukan ukuran string filter mentah karena batas ukuran permintaan untuk POST adalah sekitar 16 MB. Meskipun batas ukuran permintaan POST besar, ekspresi filter tidak boleh begitu kompleks. Untuk informasi selengkapnya tentang batasan kompleksitas filter, lihat Sintaks Ekspresi OData.

Gunakan klien REST untuk menyiapkan permintaan. Jika Anda memerlukan bantuan terkait memulai, lihat Memulai Cepat: Pencarian teks lengkap menggunakan REST.

Contoh berikut memanggil REST API untuk pencarian teks lengkap:

POST https://[service name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2025-09-01
{
    "search": "NY +view",
    "queryType": "simple",
    "searchMode": "all",
    "searchFields": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "select": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "count": true
}

Referensi:Cari POST

Kelanjutan Respons Pencarian Parsial

Terkadang Azure AI Search tidak dapat mengembalikan semua hasil yang diminta dalam satu respons Pencarian. Respons parsial dapat terjadi karena alasan yang berbeda, seperti ketika kueri mengembalikan terlalu banyak dokumen dengan tidak menentukan $top, atau dengan menentukan nilai untuk $ top yang terlalu besar. Dalam kasus seperti itu, Azure AI Search menyertakan anotasi @odata.nextLink dalam isi respons, dan juga @search.nextPageParameters jika itu adalah permintaan POST. Anda dapat menggunakan nilai anotasi ini untuk merumuskan permintaan Pencarian lain untuk mendapatkan bagian berikutnya dari respons pencarian. Perilaku ini disebut kelanjutan permintaan Pencarian asli, dan anotasi disebut token kelanjutan. Lihat contoh di bagian Respons untuk detail tentang sintaks anotasi ini dan tempat anotasi tersebut muncul di isi respons.

Alasan mengapa Azure AI Search mungkin mengembalikan token kelanjutan khusus implementasi dan dapat berubah. Klien tangguh harus selalu siap untuk menangani kasus di mana dokumen yang dikembalikan lebih sedikit dari yang diharapkan dan token kelanjutan disertakan untuk melanjutkan pengambilan dokumen. Perhatikan juga bahwa Anda harus menggunakan metode HTTP yang sama dengan permintaan asli untuk melanjutkan. Misalnya, jika Anda mengirim permintaan GET, setiap permintaan kelanjutan yang Anda kirim juga harus menggunakan GET (dan demikian juga untuk POST).

Nota

Tujuan @odata.nextLink dan @search.nextPageParameters adalah untuk melindungi layanan dari kueri yang meminta terlalu banyak hasil, bukan untuk menyediakan mekanisme umum pengelolaan halaman. Jika Anda ingin menjelajah hasil, gunakan $top dan $skip bersama. Misalnya, jika Anda menginginkan halaman berukuran 10, permintaan pertama Anda harus memiliki $top=10 dan $skip=0, permintaan kedua harus memiliki $top=10 dan $skip=10, permintaan ketiga harus memiliki $top=10 dan $skip=20, dan sebagainya.

Azure SDK

Contoh berikut menunjukkan cara menjalankan kueri teks lengkap menggunakan SDK Azure.

Python

from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

# Set up the client
service_name = "<your-search-service-name>"
index_name = "hotels-sample"
api_key = "<your-query-api-key>"

endpoint = f"https://{service_name}.search.windows.net"
credential = AzureKeyCredential(api_key)
client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)

# Run a full-text search query
results = client.search(
    search_text="NY +view",
    search_mode="all",
    search_fields=["HotelName", "Description", "Address/City", "Tags"],
    select=["HotelName", "Description", "Address/City", "Tags"],
    top=10,
    include_total_count=True
)

print(f"Total documents matching query: {results.get_count()}")
for result in results:
    print(f"Hotel: {result['HotelName']}")

Referensi:SearchClient, search

C#

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Models;

// Set up the client
string serviceName = "<your-search-service-name>";
string indexName = "hotels-sample";
string apiKey = "<your-query-api-key>";

Uri endpoint = new Uri($"https://{serviceName}.search.windows.net");
AzureKeyCredential credential = new AzureKeyCredential(apiKey);
SearchClient searchClient = new SearchClient(endpoint, indexName, credential);

// Run a full-text search query
SearchOptions options = new SearchOptions
{
    SearchMode = SearchMode.All,
    IncludeTotalCount = true,
    Size = 10
};
options.SearchFields.Add("HotelName");
options.SearchFields.Add("Description");
options.Select.Add("HotelName");
options.Select.Add("Description");

SearchResults<SearchDocument> response = await searchClient.SearchAsync<SearchDocument>("NY +view", options);

Console.WriteLine($"Total documents matching query: {response.TotalCount}");
await foreach (SearchResult<SearchDocument> result in response.GetResultsAsync())
{
    Console.WriteLine($"Hotel: {result.Document["HotelName"]}");
}

Referensi:SearchClient, SearchAsync, SearchOptions

Sumber daya SDK tambahan

Azure SDK	Klien	Contoh
.NET	SearchClient	DotNetHowTo
Java	SearchClient	SearchForDynamicDocumentsExample.java
JavaScript	SearchClient	contoh pemakaian SDK
Python	SearchClient	sample_simple_query.py

Pilih jenis kueri: sederhana | penuh

Jika kueri Anda adalah pencarian teks lengkap, pengurai kueri digunakan untuk memproses teks apa pun yang diteruskan sebagai istilah pencarian dan frasa. Azure AI Search menawarkan dua pengurai kueri.

• Parser sederhana memahami sintaks kueri sederhana. Parser ini dipilih sebagai default karena kecepatan dan efektivitasnya dalam kueri teks bentuk bebas. Sintaks mendukung operator pencarian umum (AND, OR, NOT) untuk pencarian istilah dan frasa, serta pencarian dengan awalan (* seperti pada sea* untuk Seattle dan Seaside). Rekomendasi umum yang disarankan adalah dengan mencoba parser sederhana terlebih dahulu, dan kemudian beralih ke parser penuh jika persyaratan aplikasi membutuhkan kueri yang lebih kuat.

• Sintaks kueri Lucene lengkap, diaktifkan saat Anda menambahkan queryType=full ke permintaan, didasarkan pada Apache Lucene Parser.

Sintaks penuh dan sintaksis sederhana tumpang tindih hingga mendukung awalan dan operasi Boolean yang sama, tetapi sintaks penuh menyediakan lebih banyak operator. Ada lebih banyak operator untuk ekspresi Boolean, dan lebih banyak operator untuk kueri tingkat lanjut seperti pencarian fuzzy, pencarian wildcard, pencarian proksimitas, dan ekspresi reguler.

Pilih metode kueri

Pencarian pada dasarnya adalah latihan berbasis pengguna, di mana istilah atau frasa dikumpulkan dari kotak pencarian, atau dari kejadian klik pada halaman. Tabel berikut ini merangkum mekanisme yang dapat digunakan untuk mengumpulkan input pengguna, beserta pengalaman pencarian yang diharapkan.

Masukan	Pengalaman
Metode pencarian	Pengguna mengetik istilah atau frasa ke dalam kotak pencarian, dengan atau tanpa operator, dan memilih Cari untuk mengirim permintaan. Pencarian dapat digunakan dengan filter pada permintaan yang sama, tetapi tidak berlaku pada lengkapi otomatis atau saran.
Metode lengkapi otomatis	Pengguna mengetik beberapa karakter, dan kueri dimulai setelah setiap karakter baru diketik. Respon adalah string lengkap dari indeks. Jika string yang disediakan valid, pengguna memilih Cari untuk mengirim kueri tersebut ke layanan.
Metode saran	Seperti halnya lengkapi otomatis, pengguna mengetik beberapa karakter dan kueri inkremental akan dihasilkan. Responsnya adalah daftar dropdown dokumen yang cocok, biasanya diwakili oleh beberapa bidang unik atau deskriptif. Jika salah satu pilihan valid, pengguna memilih satu dan dokumen yang cocok dikembalikan.
Navigasi tersaring	Halaman memperlihatkan tautan navigasi atau breadcrumbs yang dapat diklik guna mempersempit cakupan pencarian. Struktur navigasi bersegi disusun secara dinamis berdasarkan kueri awal. Misalnya, search=* untuk mengisi pohon navigasi tersaring yang terdiri dari setiap kategori yang bisa digunakan. Struktur navigasi beraspek dibuat dari respons kueri, tetapi juga merupakan mekanisme untuk menyampaikan kueri berikutnya. Dalam referensi REST API, facets didokumentasikan sebagai parameter kueri dari operasi Pencarian Dokumen, tetapi dapat digunakan tanpa parameter search.
Metode filter	Filter digunakan dengan faset untuk mempersempit hasil. Anda juga dapat menerapkan filter di belakang halaman, misalnya untuk menginisialisasi halaman dengan bidang khusus bahasa. Dalam referensi REST API, $filter didokumentasikan sebagai parameter kueri dari operasi Pencarian Dokumen, tetapi dapat digunakan tanpa parameter search.

Efek atribut bidang pada kueri

Jika Anda terbiasa dengan jenis dan komposisi kueri, Anda mungkin ingat bahwa parameter pada permintaan kueri bergantung pada atribut bidang dalam indeks. Misalnya, hanya bidang yang ditandai sebagai dapat dicari dan dapat diambil yang dapat digunakan dalam kueri dan hasil pencarian. Saat mengatur parameter search, filter, dan orderby dalam permintaan Anda, Anda harus memeriksa atribut untuk menghindari hasil yang tidak terduga.

Dalam cuplikan layar indeks contoh hotel berikut, hanya dua bidang terakhir LastRenovationDate dan Peringkat yang dapat diurutkan, yang merupakan persyaratan untuk digunakan dalam klausul khusus "$orderby".

Untuk definisi atribut bidang, lihat Membuat Indeks (REST API).

Efek token pada kueri

Selama pengindeksan, mesin pencari menggunakan penganalisis teks pada string untuk memaksimalkan potensi untuk menemukan kecocokan pada waktu kueri. Minimal, string berukuran lebih rendah, tetapi tergantung pada penganalisis, mungkin juga mengalami lemmatisasi dan menghentikan penghapusan kata. String atau kata majemuk biasanya dipisahkan menggunakan whitespace, tanda hubung, atau tanda pisah, dan diindeks sebagai token terpisah.

Poin utamanya adalah bahwa apa yang Anda pikir indeks Anda berisi, dan apa yang sebenarnya ada di dalamnya, bisa berbeda. Jika kueri tidak mengembalikan hasil yang diharapkan, Anda dapat memeriksa token yang dibuat oleh penganalisis melalui Analyze Text (REST API). Untuk informasi selengkapnya tentang tokenisasi dan efek pada kueri, lihat Pencarian istilah parsial dan pola dengan karakter khusus.

Memecahkan masalah kueri

Tabel berikut ini mencantumkan masalah kueri umum dan cara mengatasinya.

Masalah	Penyebab	Resolusi
Hasil kosong	Tidak ada dokumen yang cocok dengan kata kunci kueri.	Pastikan kolom ditandai dapat dicari dalam skema. Gunakan Analyze Text API untuk memeriksa tokenisasi.
Hasil yang tidak terduga	Kueri cocok dengan bidang yang tidak diinginkan.	Gunakan searchFields untuk membatasi bidang mana yang dicari.
Terlalu banyak hasil	Kueri terlalu luas.	Tambahkan filter, gunakan searchMode=all, atau tambahkan istilah yang diperlukan dengan + operator.
Hasil tidak diberi peringkat seperti yang diharapkan	Penilaian relevansi tidak sesuai dengan harapan.	Pertimbangkan profil penilaian atau peringkat semantik.
Kecocokan parsial hilang	Analyzer ditokenisasi secara berbeda dari yang diharapkan.	Gunakan akhiran wildcard (*) atau periksa hasil analisis dengan Analyze Text API.
Filter tidak berfungsi	Bidang tidak ditandai dapat difilter.	Perbarui skema indeks sehingga filterable: true diatur pada bidang.

Konten terkait

Sekarang setelah Anda memiliki pemahaman yang lebih baik tentang cara kerja permintaan kueri, cobalah panduan cepat berikut ini untuk pengalaman praktis.

• Penjelajah pencarian
• Mulai cepat: Pencarian teks lengkap
• Sintaks kueri sederhana
• Sintaks kueri Lucene penuh
• Sintaks filter OData