Contoh navigasi berfaktor

Catatan

Pencarian Azure AI tersedia melalui portal Azure, REST API, dan Azure SDK. Ini juga mendukung Foundry IQ, lapisan pengetahuan terkelola yang mengubah konten perusahaan menjadi pangkalan pengetahuan yang dapat digunakan kembali dan sadar izin untuk agen di portal Microsoft Foundry.

Important

Fitur, kemampuan, atau properti yang ditandai (pratinjau) tidak tercakup dalam perjanjian tingkat layanan, tidak disarankan untuk beban kerja produksi, dan mungkin berubah atau dibatasi sebelum tersedia secara umum. Ketentuan pratinjau Pencarian Azure AI berlaku untuk semua fungsionalitas pratinjau, baik itu mandiri atau bagian dari fitur yang tersedia secara umum.

Bagian ini memperluas konfigurasi navigasi berkategori dengan contoh-contoh yang menunjukkan penggunaan dasar serta skenario lainnya.

Bidang yang bisa difasetkan ditentukan dalam indeks, tetapi parameter dan ekspresi faset ditentukan dalam permintaan kueri. Jika Anda memiliki indeks dengan bidang faset, Anda dapat mencoba hierarki faset (pratinjau), agregasi faset (pratinjau), dan filter faset (pratinjau) pada indeks yang ada.

Parameter dan sintaks faset

Bergantung pada API, kueri faset biasanya merupakan array ekspresi faset yang diterapkan ke hasil pencarian. Setiap ekspresi faset berisi nama bidang yang dapat difaset, secara opsional diikuti dengan daftar pasangan nilai nama yang dipisahkan koma.

  • kueri faset adalah permintaan kueri yang menyertakan properti faset.
  • bidang facetable adalah definisi bidang dalam indeks pencarian yang dikaitkan dengan properti facetable.
  • hitungan adalah jumlah kecocokan untuk setiap faset yang ditemukan dalam hasil pencarian.

Tabel berikut menjelaskan parameter faset yang digunakan dalam contoh.

Parameter faset Deskripsi Penggunaan Contoh
count Jumlah maksimum istilah faset per struktur. Integer. Defaultnya adalah 10. Tidak ada batas atas, tetapi angka yang lebih tinggi menurunkan performa, terutama jika bidang terfaktorkan berisi sejumlah besar istilah unik. Hal ini disebabkan oleh cara kueri faset didistribusikan di seluruh partisi. Anda dapat mengatur count ke nol atau ke nilai yang lebih besar dari atau sama dengan jumlah nilai unik di bidang yang dapat difaset untuk mendapatkan jumlah yang akurat di semua shard. Komprominya adalah peningkatan latensi. Tags,count:5 membatasi respons navigasi tersaring ke 5 wadah faset yang berisi jumlah faset terbanyak, tetapi dapat dalam urutan apa pun.
sort Menentukan urutan wadah faset. Nilai yang valid adalah count, -count, value, -value. Gunakan count untuk mencantumkan faset dari yang terbesar hingga terkecil. Gunakan -count untuk mengurutkan dalam urutan naik (terkecil ke terbesar). Gunakan value untuk mengurutkan secara alfanumerik menurut nilai faset dalam urutan naik. Gunakan -value untuk mengurutkan turun menurut nilai. "facet=Category,count:3,sort:count" mendapatkan tiga wadah faset teratas dalam hasil pencarian, yang tercantum dalam urutan menurun berdasarkan jumlah kecocokan di setiap Kategori. Jika tiga kategori teratas adalah Budget, Extended-Stay, dan Luxury, dan Budget memiliki 5 jumlah pencarian, Extended-Stay memiliki 6, dan Luxury memiliki 4, maka kelompok faset diurutkan menjadi Extended-Stay, Budget, Luxury. Contoh lain adalah"facet=Rating,sort:-value". Ini menghasilkan aspek untuk semua penilaian yang mungkin, dengan urutan berdasarkan nilai yang menurun. Jika peringkat dari 1 hingga 5, faset diurutkan 5, 4, 3, 2, 1, tak peduli berapa banyak dokumen yang cocok dengan setiap peringkat.
values Menyediakan nilai untuk label faset. Atur ke nilai numerik yang dipisahkan dengan pipa atau Edm.DateTimeOffset nilai yang menentukan sekumpulan nilai entri faset yang dinamis. Nilai harus dicantumkan secara berurutan, urutan naik untuk mendapatkan hasil yang diharapkan. "facet=baseRate,values:10 | 20" menghasilkan tiga wadah faset: satu untuk tarif dasar 0 hingga tetapi tidak termasuk 10, satu untuk 10 hingga tetapi tidak termasuk 20, dan satu untuk 20 dan lebih tinggi. String "facet=lastRenovationDate,values:2024-02-01T00:00:00Z" menghasilkan dua wadah faset: satu untuk hotel yang direnovasi sebelum Februari 2024, dan satu untuk hotel yang direnovasi 1 Februari 2024 atau setelahnya.
interval Menyediakan urutan interval untuk faset yang dapat dikelompokkan ke dalam interval. Interval bilangan bulat yang lebih besar dari nol untuk angka, atau menit, jam, hari, minggu, bulan, kuartal, tahun untuk nilai waktu tanggal. "facet=baseRate,interval:100" menghasilkan wadah faset berdasarkan rentang laju dasar ukuran 100. Jika tarif dasar semuanya antara $60 dan $600, ada wadah faset untuk 0-100, 100-200, 200-300, 300-400, 400-500, dan 500-600. String "facet=lastRenovationDate,interval:year" menghasilkan satu wadah faset untuk setiap tahun hotel direnovasi.
timeoffset Menentukan offset waktu UTC untuk memperhitungkan dalam mengatur batas waktu. Atur ke ([+-]hh:mm, [+-]hhmm, or [+-]hh). Jika digunakan, timeoffset parameter harus dikombinasikan dengan opsi interval, dan hanya saat diterapkan ke bidang jenis Edm.DateTimeOffset. "facet=lastRenovationDate,interval:day,timeoffset:-01:00" menggunakan batas hari yang dimulai pada pukul 01:00:00 UTC (tengah malam di zona waktu target).

count dan sort dapat dikombinasikan dalam spesifikasi faset yang sama, tetapi tidak dapat dikombinasikan dengan interval atau values.

interval dan values tidak dapat digabungkan bersama-sama.

Faset interval pada waktu tanggal dihitung berdasarkan waktu UTC jika timeoffset tidak ditentukan. Misalnya, untuk "facet=lastRenovationDate,interval:day", batas hari dimulai pada pukul 00:00:00 UTC.

Contoh faset dasar

Kueri faset berikut bekerja terhadap indeks sampel hotel. Anda bisa menggunakan tampilan JSON di Search Explorer untuk menempelkan kueri JSON. Untuk bantuan tentang memulai, lihat Menambahkan navigasi tersaring ke hasil pencarian.

Kueri pertama ini mengambil faset untuk Kategori, Peringkat, Tag, dan ruang dengan nilai baseRate dalam rentang tertentu. Perhatikan bahwa faset terakhir ada di subbidang dari koleksi Ruangan. Faset menghitung dokumen induk (Hotel) dan bukan subdokumen menengah (Kamar), sehingga respons menentukan jumlah hotel yang memiliki kamar di setiap kategori harga.

POST /indexes/hotels-sample/docs/search?api-version={{api_version}}
{  
  "search": "ocean view",  
  "facets": [ "Category", "Rating", "Tags", "Rooms/BaseRate,values:80|150|220" ],
  "count": true 
}  

Contoh kedua ini menggunakan filter untuk mempersempit hasil kueri tersaring sebelumnya setelah pengguna memilih Peringkat 3 dan kategori "Motel".

POST /indexes/hotels-sample/docs/search?api-version={{api_version}}
{  
  "search": "water view",  
  "facets": [ "Tags", "Rooms/BaseRate,values:80|150|220" ],
  "filter": "Rating eq 3 and Category eq 'Motel'",
  "count": true  
} 

Contoh ketiga menetapkan batas atas pada istilah unik yang dikembalikan dalam kueri. Defaultnya adalah 10, tetapi Anda dapat menambah atau mengurangi nilai ini menggunakan parameter hitungan pada atribut faset. Contoh ini mengembalikan facet untuk kota, dibatasi hingga 5.

POST /indexes/hotels-sample/docs/search?api-version={{api_version}}
{  
  "search": "view",  
  "facets": [ "Address/City,count:5" ],
  "count": true
} 

Contoh ini menunjukkan tiga faset untuk "Kategori", "Tag", dan "Peringkat", dengan penggantian jumlah untuk "Tag" dan penggantian rentang untuk "Peringkat", yang sebenarnya disimpan sebagai double dalam indeks.

POST https://{{service_name}}.search.windows.net/indexes/hotels-sample/docs/search?api-version={{api_version}}
{
    "search": "*",
    "facets": [ 
        "Category", 
        "Tags,count:5", 
        "Rating,values:1|2|3|4|5"
    ],
    "count": true
}

Untuk setiap pohon navigasi berfasilitas, ada batas default dari 10 instance faset teratas yang ditemukan oleh kueri. Default ini masuk akal untuk struktur navigasi karena menyimpan daftar nilai ke ukuran yang dapat dikelola. Anda dapat mengubah default dengan menetapkan nilai ke "count". Misalnya, "Tags,count:5" mengurangi jumlah tag di bawah bagian Tag ke lima besar.

Hanya untuk nilai Numerik dan DateTime, Anda dapat secara eksplisit mengatur nilai pada bidang faset (misalnya, facet=Rating,values:1|2|3|4|5) untuk memisahkan hasil menjadi rentang yang berdada (baik rentang berdasarkan nilai numerik atau periode waktu). Atau, Anda dapat menambahkan "interval", seperti dalam facet=Rating,interval:1.

Setiap rentang dibangun menggunakan 0 sebagai titik awal, nilai dari daftar sebagai titik akhir, lalu dipangkas dari rentang sebelumnya untuk membuat interval diskrit.

Contoh nilai yang berbeda

Anda bisa merumuskan kueri yang mengembalikan jumlah nilai yang berbeda untuk setiap bidang yang dapat difaset. Contoh ini merumuskan kueri kosong atau tidak memenuhi syarat ("search": "*") yang cocok pada semua dokumen, tetapi dengan mengatur top ke nol, Anda hanya mendapatkan hitungan, tanpa hasil.

Untuk singkatnya, kueri ini hanya memasukkan dua field yang ditandai sebagai facetable dalam indeks hotel-sampel.

POST https://{{service_name}}.search.windows.net/indexes/hotels-sample/docs/search?api-version={{api_version}}
{
    "search": "*",
    "count": true,
    "top": 0,
    "facets": [ 
        "Category", "Address/StateProvince""
    ]
}

Hasil dari kueri ini adalah sebagai berikut:

{
  "@odata.count": 50,
  "@search.facets": {
    "Address/StateProvince": [
      {
        "count": 9,
        "value": "WA"
      },
      {
        "count": 6,
        "value": "CA "
      },
      {
        "count": 4,
        "value": "FL"
      },
      {
        "count": 3,
        "value": "NY"
      },
      {
        "count": 3,
        "value": "OR"
      },
      {
        "count": 3,
        "value": "TX"
      },
      {
        "count": 2,
        "value": "GA"
      },
      {
        "count": 2,
        "value": "MA"
      },
      {
        "count": 2,
        "value": "TN"
      },
      {
        "count": 1,
        "value": "AZ"
      }
    ],
    "Category": [
      {
        "count": 13,
        "value": "Budget"
      },
      {
        "count": 12,
        "value": "Suite"
      },
      {
        "count": 7,
        "value": "Boutique"
      },
      {
        "count": 7,
        "value": "Resort and Spa"
      },
      {
        "count": 6,
        "value": "Extended-Stay"
      },
      {
        "count": 5,
        "value": "Luxury"
      }
    ]
  },
  "value": []
}

Contoh hierarki faset (pratinjau)

Dengan menggunakan REST API pratinjau latest atau portal Azure, Anda dapat mengonfigurasi hierarki faset menggunakan operator > dan ;.

Operator Deskripsi
> Operator berlapis (hierarkis) menunjukkan hubungan induk-anak.
; Operator titik koma menunjukkan beberapa bidang pada tingkat berlapis yang sama, yang semuanya merupakan turunan dari induk yang sama. Induk hanya boleh berisi satu bidang. Bidang induk dan anak harus facetable.

Urutan operasi dalam ekspresi faset yang mencakup hierarki faset adalah:

  • Operator opsi (koma ,) yang memisahkan parameter faset untuk bidang faset, seperti koma di Rooms/BaseRate,values
  • Tanda kurung, seperti yang mencakup (Rooms/BaseRate,values:50 ; Rooms/Type).
  • Operator penyusunan (tanda kurung sudut >)
  • Operator lampir (titik koma ;) ditunjukkan dalam contoh "Tags>(Rooms/BaseRate,values:50 ; Rooms/Type)" kedua di bagian ini, di mana dua faset anak adalah setara di bawah orang tua Tags.

Perhatikan bahwa tanda kurung diproses sebelum operasi bersarang dan tambahkan: A > B ; C akan berbeda dari A > (B ; C).

Ada beberapa contoh untuk hierarki faset. Contoh pertama adalah kueri yang hanya mengembalikan beberapa dokumen, yang berguna untuk menampilkan respons penuh. Faset menghitung dokumen induk (Hotel) dan bukan subdokumen menengah (Kamar), sehingga respons menentukan jumlah hotel yang memiliki kamar di setiap wadah faset.

POST /indexes/hotels-sample/docs/search?api-version=2026-08-01-preview
{
  "search": "ocean",  
  "facets": ["Address/StateProvince>Address/City", "Tags>Rooms/BaseRate,values:50"],
  "select": "HotelName, Description, Tags, Address/StateProvince, Address/City",
  "count": true 
}

Hasil dari kueri ini adalah sebagai berikut. Kedua hotel memiliki kolam renang. Untuk tag lain, hanya satu hotel yang menyediakan fasilitas.

{
  "@odata.count": 2,
  "@search.facets": {
    "Tags": [
      {
        "value": "pool",
        "count": 2,
        "@search.facets": {
          "Rooms/BaseRate": [
            {
              "to": 50,
              "count": 0
            },
            {
              "from": 50,
              "count": 2
            }
          ]
        }
      },
      {
        "value": "air conditioning",
        "count": 1,
        "@search.facets": {
          "Rooms/BaseRate": [
            {
              "to": 50,
              "count": 0
            },
            {
              "from": 50,
              "count": 1
            }
          ]
        }
      },
      {
        "value": "bar",
        "count": 1,
        "@search.facets": {
          "Rooms/BaseRate": [
            {
              "to": 50,
              "count": 0
            },
            {
              "from": 50,
              "count": 1
            }
          ]
        }
      },
      {
        "value": "restaurant",
        "count": 1,
        "@search.facets": {
          "Rooms/BaseRate": [
            {
              "to": 50,
              "count": 0
            },
            {
              "from": 50,
              "count": 1
            }
          ]
        }
      },
      {
        "value": "view",
        "count": 1,
        "@search.facets": {
          "Rooms/BaseRate": [
            {
              "to": 50,
              "count": 0
            },
            {
              "from": 50,
              "count": 1
            }
          ]
        }
      }
    ],
    "Address/StateProvince": [
      {
        "value": "FL",
        "count": 1,
        "@search.facets": {
          "Address/City": [
            {
              "value": "Tampa",
              "count": 1
            }
          ]
        }
      },
      {
        "value": "HI",
        "count": 1,
        "@search.facets": {
          "Address/City": [
            {
              "value": "Honolulu",
              "count": 1
            }
          ]
        }
      }
    ]
  },
  "value": [
    {
      "@search.score": 1.6076145,
      "HotelName": "Ocean Water Resort & Spa",
      "Description": "New Luxury Hotel for the vacation of a lifetime. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.",
      "Tags": [
        "view",
        "pool",
        "restaurant"
      ],
      "Address": {
        "City": "Tampa",
        "StateProvince": "FL"
      }
    },
    {
      "@search.score": 1.0594962,
      "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.",
      "Tags": [
        "pool",
        "air conditioning",
        "bar"
      ],
      "Address": {
        "City": "Honolulu",
        "StateProvince": "HI"
      }
    }
  ]
}

Contoh kedua ini memperluas yang sebelumnya, menunjukkan beberapa faset tingkat atas dengan beberapa anak. Perhatikan operator titik koma (;) memisahkan setiap anak.

POST /indexes/hotels-sample/docs/search?api-version=2026-08-01-preview
{  
  "search": "+ocean",  
  "facets": ["Address/StateProvince > Address/City", "Tags > (Rooms/BaseRate,values:50 ; Rooms/Type)"],
  "select": "HotelName, Description, Tags, Address/StateProvince, Address/City",
  "count": true 
}  

Respons parsial, dipangkas untuk singkatnya, menunjukkan tag dengan aspek anak untuk tarif dasar dan jenis kamar. Dalam indeks sampel hotel, kedua hotel yang cocok dengan +ocean memiliki kamar di setiap jenis dan juga kolam renang.

{
  "@odata.count": 2,
  "@search.facets": {
    "Tags": [
      {
        "value": "pool",
        "count": 2,
        "@search.facets": {
          "Rooms/BaseRate": [
            {
              "to": 50,
              "count": 0
            },
            {
              "from": 50,
              "count": 2
            }
          ],
          "Rooms/Type": [
            {
              "value": "Budget Room",
              "count": 2
            },
            {
              "value": "Deluxe Room",
              "count": 2
            },
            {
              "value": "Standard Room",
              "count": 2
            },
            {
              "value": "Suite",
              "count": 2
            }
          ]
        }}]},
  ...
}

Contoh terakhir ini menunjukkan aturan pendahuluan untuk tanda kurung yang memengaruhi tingkat sarang. Misalkan Anda ingin mengembalikan hierarki faset dalam urutan ini.

Address/StateProvince
  Address/City
    Category
    Rating

Untuk mengembalikan hierarki ini, buat kueri di mana Kategori dan Peringkat adalah saudara kandung di bawah Alamat/Kota.

  { 
    "search": "beach",  
    "facets": [
        "Address/StateProvince > (Address/City > (Category ; Rating))"
        ],
    "select": "HotelName, Description, Tags, Address/StateProvince, Address/City",
    "count": true 
  }

Jika Anda menghapus tanda kurung terdahulu, Kategori dan Peringkat tidak lagi bersaudara karena aturan prioritas berarti bahwa > operator dievaluasi sebelum ;.

  { 
    "search": "beach",  
    "facets": [
        "Address/StateProvince > (Address/City > Category ; Rating)"
        ],
    "select": "HotelName, Description, Tags, Address/StateProvince, Address/City",
    "count": true 
  }

Induk tingkat atas tetap Alamat/Provinsi, tetapi sekarang Alamat/Kota dan Peringkat berada pada tingkat yang sama.

Address/StateProvince
  Rating
  Address/City
    Category

Contoh pemfilteran faset (pratinjau)

Dengan menggunakan API REST pratinjau terbaru atau portal Azure, Anda dapat mengonfigurasi filter faset.

Pemfilteran faset memungkinkan Anda membatasi nilai faset yang dikembalikan ke yang cocok dengan ekspresi reguler tertentu. Dua parameter baru menerima ekspresi reguler yang diterapkan ke bidang faset:

  • includeTermFilter memfilter nilai faset ke nilai yang cocok dengan ekspresi reguler
  • excludeTermFilter memfilter nilai faset pada nilai yang tidak cocok dengan pola ekspresi reguler

Jika string faset memenuhi kedua kondisi, excludeTermFilter diutamakan karena kumpulan string kelompok pertama kali dievaluasi dengan includeTermFilter dan kemudian dikecualikan dengan excludeTermFilter.

Hanya nilai-nilai faset yang sesuai dengan ekspresi reguler yang akan dikembalikan. Anda dapat menggabungkan parameter ini dengan opsi faset lainnya (misalnya, count, , sortdan faset hierarkis) pada bidang string.

Karena ekspresi reguler ditumpuk dalam nilai string JSON, Anda harus keluar dari karakter tanda kutip ganda (") dan garis miring terbelakang (\). Ekspresi reguler itu sendiri dibatasi oleh garis miring ke depan (/). Untuk informasi selengkapnya tentang pola escape, lihat Pencarian ekspresi reguler.

Contoh berikut menunjukkan cara menghindari karakter khusus dalam ekspresi reguler Anda seperti garis miring terbalik, tanda kutip ganda, atau karakter sintaks ekspresi reguler.

{
    "search": "*", 
    "facets": ["name,includeTermFilter:/EscapeBackslash\\\OrDoubleQuote\\"OrRegexCharacter\\(/"] 
}

Berikut adalah contoh filter faset yang cocok dengan hotel Budget dan Extended-Stay, dengan Peringkat sebagai subkategori dari setiap kategori hotel.

POST /indexes/hotels-sample/docs/search?api-version=2026-08-01-preview
{ 
    "search": "*", 
    "facets": ["(Category,includeTermFilter:/(Budget|Extended-Stay)/)>Rating,values:1|2|3|4|5"],
    "select": "HotelName, Category, Rating",
    "count": true 
} 

Contoh berikut adalah respons yang dipersingkat (dokumen hotel dihilangkan untuk keperluan singkat).

{
  "@odata.count": 50,
  "@search.facets": {
    "Category": [
      {
        "value": "Budget",
        "count": 13,
        "@search.facets": {
          "Rating": [
            {
              "to": 1,
              "count": 0
            },
            {
              "from": 1,
              "to": 2,
              "count": 0
            },
            {
              "from": 2,
              "to": 3,
              "count": 4
            },
            {
              "from": 3,
              "to": 4,
              "count": 5
            },
            {
              "from": 4,
              "to": 5,
              "count": 4
            },
            {
              "from": 5,
              "count": 0
            }
          ]
        }
      },
      {
        "value": "Extended-Stay",
        "count": 6,
        "@search.facets": {
          "Rating": [
            {
              "to": 1,
              "count": 0
            },
            {
              "from": 1,
              "to": 2,
              "count": 0
            },
            {
              "from": 2,
              "to": 3,
              "count": 4
            },
            {
              "from": 3,
              "to": 4,
              "count": 1
            },
            {
              "from": 4,
              "to": 5,
              "count": 1
            },
            {
              "from": 5,
              "count": 0
            }
          ]
        }
      }
    ]
  }, 
  "value": [  ALL 50 HOTELS APPEAR HERE ]
}

Contoh agregasi faset (pratinjau)

Dengan menggunakan REST API pratinjau terbaru atau portal Azure, Anda dapat menggabungkan faset.

Agregasi faset memungkinkan Anda menghitung metrik dari nilai faset. Kemampuan agregasi berfungsi seiring dengan opsi faset yang ada.

Pengumpul Deskripsi
Jumlah Mengembalikan total nilai akumulasi dari kolom di semua dokumen. Hanya berlaku untuk jenis numerik. Didukung dalam rilis pratinjau sebelumnya.
Min Mengembalikan nilai minimum dari bidang di semua dokumen. Hanya berlaku untuk jenis numerik.
Maks Mengembalikan nilai maksimum dari bidang di semua dokumen. Hanya berlaku untuk jenis numerik.
Avg Mengembalikan nilai rata-rata dari bidang di semua dokumen. Hanya berlaku untuk jenis numerik.
Kardinalitas Mengembalikan perkiraan jumlah nilai yang berbeda dari bidang di semua dokumen menggunakan algoritma HyperLogLog. Anda dapat meminta cardinality pada bidang yang dapat difasetkan, termasuk bidang string dan tanggal dan waktu, beserta bentuk koleksinya.

Mengatur ambang presisi untuk agregasi kardinalitas

Pada agregasi kardinalitas, Anda dapat menetapkan precisionThreshold opsi sebagai demarkasi antara hitungan yang diharapkan mendekati akurat, dan hitungan yang bisa kurang akurat. Nilai maksimumnya adalah 40.000. Nilai defaultnya adalah 3.000.

Pemfaktoran dilakukan dalam memori. Meningkatkan precisionThreshold menghasilkan lebih banyak memori yang dikonsumsi (nilai precisionThreshold dikalikan dengan 8 byte).

Contoh: Menjumlahkan agregasi faset

Anda dapat menjumlahkan bidang yang dapat difasetkan dari jenis data numerik (kecuali vektor dan koordinat geografis).

Berikut adalah contoh menggunakan indeks sampel hotel. Bidang Rooms/SleepsCount dapat difaset dan numerik, jadi kami memilih bidang ini untuk menunjukkan jumlah. Jika kita menjumlahkan bidang itu, kita mendapatkan jumlah waktu tidur untuk seluruh hotel. Ingat bahwa faset menghitung dokumen induk (Hotel) dan bukan subdokumen menengah (Kamar), sehingga respons menjumlahkan SleepsCount dari semua kamar untuk seluruh hotel. Dalam kueri ini, kami menambahkan filter untuk menjumlahkan SleepsCount hanya untuk satu hotel.

POST /indexes/hotels-sample/docs/search?api-version=2026-08-01-preview

{ 
      "search": "*",
      "filter": "HotelId eq '41'",
      "facets": [ "Rooms/SleepsCount, metric: sum"],
      "select": "HotelId, HotelName, Rooms/Type, Rooms/SleepsCount",
      "count": true
}

Respons untuk kueri mungkin terlihat seperti contoh berikut. Windy Ocean Model dapat mengakomodasi total 40 tamu.

{
  "@odata.count": 1,
  "@search.facets": {
    "Rooms/SleepsCount": [
      {
        "sum": 40.0
      }
    ]
  },
  "value": [
    {
      "@search.score": 1.0,
      "HotelId": "41",
      "HotelName": "Windy Ocean Motel",
      "Rooms": [
        {
          "Type": "Suite",
          "SleepsCount": 4
        },
        {
          "Type": "Deluxe Room",
          "SleepsCount": 2
        },
        {
          "Type": "Budget Room",
          "SleepsCount": 2
        },
        {
          "Type": "Budget Room",
          "SleepsCount": 2
        },
        {
          "Type": "Suite",
          "SleepsCount": 2
        },
        {
          "Type": "Standard Room",
          "SleepsCount": 2
        },
        {
          "Type": "Deluxe Room",
          "SleepsCount": 2
        },
        {
          "Type": "Suite",
          "SleepsCount": 2
        },
        {
          "Type": "Suite",
          "SleepsCount": 4
        },
        {
          "Type": "Standard Room",
          "SleepsCount": 4
        },
        {
          "Type": "Standard Room",
          "SleepsCount": 2
        },
        {
          "Type": "Deluxe Room",
          "SleepsCount": 2
        },
        {
          "Type": "Suite",
          "SleepsCount": 2
        },
        {
          "Type": "Standard Room",
          "SleepsCount": 2
        },
        {
          "Type": "Deluxe Room",
          "SleepsCount": 2
        },
        {
          "Type": "Deluxe Room",
          "SleepsCount": 2
        },
        {
          "Type": "Standard Room",
          "SleepsCount": 2
        }
      ]
    }
  ]
}

Contoh: Gabungan dari seluruh agregasi

Berikut adalah contoh menggunakan indeks 'faset' hipotetis yang menunjukkan sintaks untuk setiap agregasi. Perhatikan bahwa kardinalitas memiliki opsi tambahan precisionThreshold (defaultnya adalah 3.000) yang diatur ke 40.000 dalam contoh ini.

POST https://search-service.search.windows.net/indexes/facets/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{token}}
Content-Type: application/json

{
    "search": "*",
    "facets": [// field names are named <something>Value in this example 
        "cardinalityValue, metric: cardinality,precisionThreshold: 40000", 
        "sumValue,metric: sum", 
        "avgValue,metric: avg", 
        "minValue,metric: min", 
        "maxValue,metric: max" 
    ] 
}

Respons untuk kueri mungkin terlihat seperti contoh berikut.

{ 
    "@search.facets": { 
        "cardinalityValue": [ 
            { 
                "cardinality": 24000 // Number of distinct values in "cardinalityValue" field 
            } 
        ], 
        "sumValue": [ 
            { 
                "sum": 1200000 // Sum of all values in "sumValue" field 
            } 
        ], 
        "avgValue": [ 
            { 
                "avg": 50 // Average of all values in "avgValue" field 
            } 
        ], 
        "minValue": [ 
            { 
                "min": 1 // Minimum value in "minValue" field 
            } 
        ], 
        "maxValue": [ 
            { 
                "max": 100 // Maximum value in "maxValue" field 
            } 
        ] 
    } 
}

Contoh: Tentukan default untuk mengganti nilai yang hilang

Semua metrik mendukung penentuan nilai default saat dokumen tidak berisi nilai.

  • Untuk jenis nonstring (numerik, tanggalwaktu, boolean), atur default parameter ke nilai tertentu: "default: 42" .

  • Untuk jenis string, atur default parameter ke string, dibatasi menggunakan pemisah apostrof tunggal: "default: 'mystringhere'".

Anda dapat menambahkan nilai default untuk digunakan jika dokumen berisi null untuk bidang tersebut: "facets": [ "Rooms/SleepsCount, metric: sum, default:2"]. Jika ruangan memiliki nilai null untuk bidang Rooms/SleepsCount, default menggantikan nilai yang hilang.

Berikut adalah permintaan yang mengilustrasikan spesifikasi default untuk setiap jenis bidang.

POST https://search-service.search.windows.net/indexes/facets/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{token}} 
Content-Type: application/json 

{ 
    "search": "*", 
    "facets": [// field names are named <datatype>Value in this example 
        "stringfield, metric: cardinality, default: 'my string goes here'", 
        "doubleField,metric: sum, default: 5.0", 
        "intField,metric: sum, default: 5", 
        "longField,metric: sum, default: 5" 
    ] 
} 

Untuk bidang string, nilai default dibatasi menggunakan karakter tanda kutip tunggal. Untuk menghindari karakter, awali dengan simbol backslash "\". Semua karakter dianggap valid di dalam batas string. Karakter yang mengakhiri tidak boleh menjadi garis miring terbalik.

Contoh: Beberapa metrik pada bidang yang sama

Jika data yang mendasar mendukung kasus penggunaan, Anda dapat menentukan beberapa metrik pada bidang yang sama.

POST https://search-service.search.windows.net/indexes/facets/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{token}} 
Content-Type: application/json 

{ 
    "search": "*", 
    "facets": [ 
        "fieldA, metric: cardinality, precisionThreshold: 40000", 
        "fieldA, metric: sum", 
        "fieldA, metric: avg", 
        "fieldA, metric: min", 
        "fieldA, metric: max" 
    ] 
}

Respons untuk kueri mungkin terlihat seperti contoh berikut.

{ 
    "@search.facets": { 
        "fieldA": [ 
            { 
                "cardinality": 24000 // Number of distinct values in "fieldA" field 
            }, 
            { 
                "sum": 1200000 // Sum of all values in " fieldA " field 
            }, 
            { 
                "avg": 5 // Avg of all values in " fieldA " field
            }, 
            { 
                "min": 0 // Min of all values in " fieldA " field 
            }, 
            { 
                "max": 1200 // Max of all values in " fieldA " field 
            } 
        ] 
    } 
}

Langkah berikutnya

Tinjau ulang konfigurasi navigasi faset untuk alat dan API, dan tinjau praktik terbaik dalam penggunaan faset dalam kode.

Kami merekomendasikan C#: Tambahkan pencarian ke aplikasi web untuk contoh navigasi tersaring yang menyertakan kode untuk lapisan presentasi. Sampel juga mencakup filter, saran, dan pelengkapan otomatis. Ini menggunakan JavaScript dan React untuk lapisan presentasi.