Filter untuk pencarian kata kunci di Pencarian Azure AI

Filter menyediakan kriteria berbasis nilai untuk menyertakan atau mengecualikan konten sebelum eksekusi kueri untuk pencarian kata kunci, atau sebelum atau sesudah eksekusi kueri untuk pencarian vektor. Filter diterapkan ke bidang nonvektor, tetapi dapat digunakan dalam pencarian vektor jika dokumen menyertakan bidang nonvector. Misalnya, untuk indeks yang diatur di sekitar konten yang dipotong, Anda mungkin memiliki bidang tingkat induk atau bidang metadata yang dapat difilter.

Artikel ini menjelaskan pemfilteran untuk pencarian kata kunci. Untuk informasi selengkapnya tentang vektor, lihat Menambahkan filter dalam kueri vektor.

Filter ditentukan menggunakan sintaks ekspresi filter OData. Berbeda dengan pencarian kata kunci dan vektor, filter hanya berhasil jika kecocokan tepat.

Kapan menggunakan filter

Filter bersifat dasar untuk beberapa pengalaman pencarian, termasuk pencarian geospasial "temukan di dekat saya", navigasi tersaring, dan filter keamanan yang hanya menampilkan dokumen yang diizinkan untuk dilihat pengguna. Jika Anda menerapkan salah satu pengalaman ini, filter diperlukan. Ini adalah filter yang dilampirkan ke kueri pencarian yang menyediakan koordinat geolokasi, kategori faset yang dipilih oleh pengguna, atau ID keamanan pemohon.

Skenario umum meliputi:

• Potong hasil pencarian berdasarkan konten dalam indeks. Mengingat skema dengan lokasi, kategori, dan fasilitas hotel, Anda dapat membuat filter untuk secara eksplisit cocok dengan kriteria (di Seattle, di atas air, dengan pemandangan).

• Terapkan pengalaman pencarian yang dilengkapi dengan dependensi filter:

  • Navigasi berfaset menggunakan filter untuk mengembalikan kategori faset yang dipilih oleh pengguna.
  • Pencarian geospasial menggunakan filter untuk meneruskan koordinat lokasi saat ini di aplikasi dan fungsi "temukan di dekat saya" yang cocok dalam area atau berdasarkan jarak.
  • Filter keamanan meneruskan pengidentifikasi keamanan sebagai kriteria filter, di mana kecocokan dalam indeks berfungsi sebagai proksi untuk hak akses ke dokumen.

• Lakukan "pencarian angka". Bidang numerik dapat diambil dan dapat muncul di hasil pencarian, tetapi tidak dapat dicari (tunduk pada pencarian teks lengkap) satu per satu. Jika Anda memerlukan kriteria pilihan berdasarkan data numerik, gunakan filter.

Bagaimana filter dijalankan

Pada waktu kueri, pengurai filter menerima kriteria sebagai input, mengonversi ekspresi menjadi ekspresi Boolean atom yang diwakili sebagai pohon, lalu mengevaluasi pohon filter di atas bidang yang dapat difilter dalam indeks.

Pemfilteran terjadi bersamaan dengan pencarian, memenuhi syarat dokumen mana yang akan disertakan dalam pemrosesan hilir untuk pengambilan dokumen dan penilaian relevansi. Saat dipasangkan dengan string pencarian, filter secara efektif mengurangi kumpulan pengenalan operasi pencarian berikutnya. Ketika digunakan sendiri (misalnya, ketika string kueri kosong search=*), kriteria filter adalah satu-satunya input.

Bagaimana filter ditentukan

Filter berlaku untuk konten teks dan numerik (nonvector) pada bidang yang diatribusikan sebagai filterable.

Filter adalah ekspresi OData, diartikulasikan dalam sintaks filter didukung oleh Pencarian Azure AI.

Anda dapat menentukan satu filter untuk setiap operasi pencarian , tetapi filter itu sendiri dapat menyertakan beberapa bidang, beberapa kriteria, dan jika Anda menggunakan ismatch fungsi, beberapa ekspresi pencarian teks lengkap. Dalam ekspresi filter multi-bagian, Anda dapat menentukan predikat dalam urutan apa pun (tunduk pada aturan prioritas operator). Tidak ada keuntungan performa yang dapat diapresiasi jika Anda mencoba mengatur ulang predikat dalam urutan tertentu.

Salah satu batas ekspresi filter adalah batas ukuran maksimum permintaan. Seluruh permintaan, termasuk filter, dapat maksimal 16 MB untuk POST, atau 8 KB untuk GET. Ada juga batasan jumlah klausa dalam ekspresi filter Anda. Aturan praktis yang baik adalah bahwa jika Anda memiliki ratusan klausul, Anda berisiko mencapai batas. Sebaiknya desain aplikasi Anda sedemikian sehingga tidak menghasilkan filter dengan ukuran yang tidak terbatas.

Contoh berikut mewakili definisi filter prototipis dalam beberapa API.

POST https://[service name].search.windows.net/indexes/hotels/docs/search?api-version=2026-04-01
{
    "search": "*",
    "filter": "Rooms/any(room: room/BaseRate lt 150.0)",
    "select": "HotelId, HotelName, Rooms/Description, Rooms/BaseRate"
}

options = new SearchOptions()
{
    Filter = "Rating gt 4",
    OrderBy = { "Rating desc" }
};

Pola penyaringan

Contoh berikut mengilustrasikan beberapa pola penggunaan untuk skenario filter. Untuk ide lainnya, lihat Contoh sintaks > ekspresi OData.

• $filter berdiri sendiri, tanpa string kueri, berguna saat ekspresi filter dapat sepenuhnya mengidentifikasi dokumen yang menarik. Tanpa string kueri, tidak ada analisis leksikal atau linguistik, tidak ada penilaian, dan tidak ada peringkat. Perhatikan bahwa string pencarian hanyalah tanda bintang, yang berarti "cocok dengan semua dokumen".

  {
    "search": "*",
    "filter": "Rooms/any(room: room/BaseRate ge 60 and room/BaseRate lt 300) and Address/City eq 'Honolulu"
  }
  

• Kombinasi string kueri dan $filter, di mana filter membuat subset, dan string kueri menyediakan input istilah untuk pencarian teks lengkap melalui subset yang difilter. Penambahan istilah (teater jarak berjalan kaki) menghasilkan skor pencarian dalam hasil, di mana dokumen yang paling cocok dengan istilah diberi peringkat lebih tinggi. Menggunakan filter dengan string kueri adalah pola penggunaan yang paling umum.

  {
    "search": "walking distance theaters",
    "filter": "Rooms/any(room: room/BaseRate ge 60 and room/BaseRate lt 300) and Address/City eq 'Seattle'"
  }
  
  

• Kueri majemuk, dipisahkan oleh "atau", masing-masing dengan kriteria filternya sendiri (misalnya, 'beagles' dalam 'anjing' atau 'siamese' dalam 'kucing'). Ekspresi yang digabungkan dengan or dievaluasi secara individual, dengan penyatuan dokumen yang cocok dengan setiap ekspresi yang dikirim kembali dalam respons. Pola penggunaan ini dicapai melalui search.ismatchscoring fungsi . Anda juga dapat menggunakan versi nonscoring, search.ismatch.

  # Match on hostels rated higher than 4 OR 5-star motels.
  $filter=search.ismatchscoring('hostel') and Rating ge 4 or search.ismatchscoring('motel') and Rating eq 5
  
  # Match on 'luxury' or 'high-end' in the description field OR on category exactly equal to 'Luxury'.
  $filter=search.ismatchscoring('luxury | high-end', 'Description') or Category eq 'Luxury'&$count=true
  

  Dimungkinkan juga untuk menggabungkan pencarian teks lengkap melalui search.ismatchscoring dengan filter menggunakan and alih-alih or, tetapi ini secara fungsional setara dengan menggunakan search parameter dan $filter dalam permintaan pencarian. Misalnya, dua kueri berikut menghasilkan hasil yang sama:

  $filter=search.ismatchscoring('pool') and Rating ge 4
  
  search=pool&$filter=Rating ge 4
  

Persyaratan bidang untuk pemfilteran

Dalam REST API, filterable diaktifkan secara default untuk bidang sederhana. Bidang yang dapat difilter meningkatkan ukuran indeks; pastikan untuk mengatur "filterable": false pada bidang yang tidak Anda rencanakan untuk digunakan dalam filter. Untuk informasi selengkapnya tentang pengaturan untuk definisi bidang, lihat Membuat Indeks.

Dalam Azure SDK, dapat difilter off secara default. Anda dapat membuat bidang dapat difilter dengan mengatur properti IsFilterable dari objek SearchField yang sesuai ke true. Dalam contoh berikutnya, atribut diatur pada Rating properti kelas model yang memetakan ke definisi indeks.

[SearchField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
public double? Rating { get; set; }

Membuat bidang yang ada dapat difilter

Anda tidak dapat mengubah bidang yang ada untuk membuatnya dapat difilter. Sebagai gantinya, Anda perlu menambahkan bidang baru, atau membangun ulang indeks. Untuk informasi selengkapnya tentang membangun kembali indeks atau mempopulasi ulang bidang, lihat Cara membangun kembali indeks Pencarian Azure AI.

Dasar-dasar penyaringan teks

Filter teks mencari kecocokan antara bidang string dengan string literal yang Anda sediakan di filter: $filter=Category eq 'Resort and Spa'

Tidak seperti pencarian teks lengkap, tidak ada analisis leksikal atau pemecahan kata untuk filter teks, jadi perbandingan hanya untuk kecocokan yang tepat. Misalnya, asumsikan bidang f berisi "hari cerah", $filter=f eq 'sunny' tidak cocok, tetapi $filter=f eq 'sunny day' akan.

String teks sensitif terhadap huruf besar-kecil, yang berarti secara default, filter teks akan sensitif terhadap huruf besar-kecil. Misalnya, $filter=f eq 'Sunny day' tidak akan menemukan "hari cerah". Namun, Anda dapat menggunakan normalizer agar pemfilteran menjadi tidak peka terhadap huruf besar atau kecil.

Pendekatan untuk pemfilteran pada teks

Dasar-dasar filter numerik

Bidang numerik tidak searchable dalam konteks pencarian teks lengkap. Hanya string yang tunduk pada pencarian teks lengkap. Misalnya, jika Anda memasukkan 99,99 sebagai istilah pencarian, Anda tidak akan mendapatkan kembali item dengan harga $ 99,99. Sebagai gantinya, Anda akan melihat item yang memiliki angka 99 di bidang string dokumen. Dengan demikian, jika Anda memiliki data numerik, asumsinya adalah Anda akan menggunakannya untuk filter, termasuk rentang, faset, grup, dan sebagainya.

Dokumen yang berisi bidang numerik (harga, ukuran, SKU, ID) menyediakan nilai tersebut dalam hasil pencarian jika bidang ditandai retrievable. Titik di sini adalah bahwa pencarian teks lengkap itu sendiri tidak berlaku untuk jenis bidang numerik.

Langkah berikutnya

Pertama, coba Search explorer di portal Azure untuk mengirimkan kueri dengan parameter $filter. Indeks real estate-sample memberikan hasil yang menarik untuk kueri yang difilter berikut saat Anda menempelkannya ke bilah pencarian:

# Geo-filter returning documents within 5 kilometers of Redmond, Washington state
# Use $count=true to get a number of hits returned by the query
# Use $select to trim results, showing values for named fields only
# Use search=* for an empty query string. The filter is the sole input

search=*&$count=true&$select=description,city,postCode&$filter=geo.distance(location,geography'POINT(-122.121513 47.673988)') le 5

# Numeric filters use comparison like greater than (gt), less than (lt), not equal (ne)
# Include "and" to filter on multiple fields (baths and bed)
# Full text search is on John Leclerc, matching on John or Leclerc

search=John Leclerc&$count=true&$select=source,city,postCode,baths,beds&$filter=baths gt 3 and beds gt 4

# Text filters can also use comparison operators
# Wrap text in single or double quotes and use the correct case
# Full text search is on John Leclerc, matching on John or Leclerc

search=John Leclerc&$count=true&$select=source,city,postCode,baths,beds&$filter=city gt 'Seattle'

Untuk bekerja dengan contoh lainnya, lihat Contoh Sintaks > Ekspresi Filter OData.

Lihat juga

• Cara kerja pencarian teks lengkap di Pencarian Azure AI
• API REST Pencarian Dokumen
• Sintaks kueri sederhana
• Sintaksis kueri Lucene
• Jenis data yang didukung