多層面導覽範例 - Azure AI Search

2025-04-21

本節會使用示範基本使用方式和其他案例的範例來擴充多面向導覽組態。

可 Facet 欄位定義於索引中，但 Facet 參數和運算式則定義於查詢要求中。如果您有具有可面向欄位的索引，您可以嘗試新的預覽功能，例如 Facet 階層、 Facet 匯總和現有索引上的 Facet 篩選。

根據 API，Facet 查詢通常是套用至搜尋結果的 facet 表達式陣列。每個 Facet 運算式都包含一個可 Facet 欄位名稱，且後面可以選擇性地加上名稱/值組的逗號分隔清單。

Facet 查詢是包含 Facet 屬性的查詢要求。
可 Facet 欄位是搜尋索引中以 facetable 屬性屬性化的欄位定義。
count 是在搜尋結果中找到的每個 Facet 的相符項目數。

下表說明範例中使用的面向參數。

Facet 參數	說明	用法	範例
`count`	每個結構的 Facet 字詞數目上限。	整數。預設值為 10。沒有上限，但較高的值會降低效能，特別是當多面向字段包含大量唯一詞彙時。這是因為 Facet 查詢的方式會散佈於各個分區。您可以將 `count` 設定為零，或設為大於或等於可 Facet 欄位欄位中唯一值數目的值，以便在所有分區間獲得精確計數。取捨會增加延遲。	`Tags,count:5` 會將多面向導覽回應限制為 5 個包含最多 Facet 計數的 Facet 貯體 (但順序可以任意排列)。
`sort`	決定 Facet 貯體的順序。	有效值為 `count`、`-count`、`value-value`。使用 `count` 列出從最大到最小的方面。使用 `-count` 以遞增順序排序（最小到最大）。使用 `value`，以遞增順序依 Facet 值按字母和數字順序排序。用來 `-value` 依值排序遞減。	`"facet=Category,count:3,sort:count"` 會取得搜尋結果中排名前三的 Facet 貯體，依每個類別中的相符項目數以遞減順序列出。如果排名前三的類別是預算、長期住宿和奢侈品，而預算命中了 5 次、長期住宿 6 次、奢侈品 4 次，則 Facet 貯體會排序為長期住宿、預算、奢侈品。另一個範例是`"facet=Rating,sort:-value"`。它會產生所有可能評等的 Facet (按值遞減排序)。如果評等是從 1 到 5，則分類會按 5、4、3、2、1 排序，而不論每個評等匹配了多少個檔案。
`values`	提供 Facet 標籤的值。	設定為直立線符號分隔的數字或 `Edm.DateTimeOffset` 值，指定一組動態的 Facet 項目值。值必須以循序遞增順序序列出，才能取得預期的結果。	`"facet=baseRate,values:10 \| 20"` 會產生三個 Facet 貯體：一個用於基準費率 0 到 10 (不包括 10)、一個用於 10 到 20 (不包括 20)，一個用於 20 和以上。字串 `"facet=lastRenovationDate,values:2024-02-01T00:00:00Z"` 會產生兩個篩選類別：一個用於 2024 年 2 月之前翻新的酒店，另一個用於 2024 年 2 月 1 日或之後翻新的酒店。
`interval`	為可分組為間隔的 Facet 提供間隔序列。	數值為大於零的整數間隔，日期時間值為分鐘、小時、日、週、月、季、年。	`"facet=baseRate,interval:100"` 會根據大小為 100 的基準費率範圍產生 Facet 貯體。如果基準費率全都介於 60 美元到 600 美元之間，則會有下列 Facet 貯體：0-100、100-200、200-300、300-400、400-500 和 500-600。字串 `"facet=lastRenovationDate,interval:year"` 會為旅館進行翻修的每個年份產生一個 Facet 貯體。
`timeoffset`	指定在設定時間界限時要考慮的 UTC 時間偏移。	設定為（`[+-]hh:mm, [+-]hhmm, or [+-]hh`）。如果使用， `timeoffset` 參數必須與 interval 選項結合，而且只有在套用至類型的 `Edm.DateTimeOffset`欄位時。	`"facet=lastRenovationDate,interval:day,timeoffset:-01:00"` 會使用從 01：00：00 UTC 開始的日期界限（目標時區午夜）。

count 和 sort 可以結合在相同的 Facet 規格中，但不能與 interval 或 values結合。

interval 和 values 無法結合在一起。

若未指定 timeoffset，就會根據 UTC 時間來計算日期時間上的間隔 Facet。例如，針對 "facet=lastRenovationDate,interval:day"，日期界限從 00：00：00 UTC 開始。

以下是用於旅館範例索引的 Facet 查詢。您可以在 [搜尋總管] 中使用 JSON 檢視 來貼上 JSON 查詢。如需開始使用的說明，請參閱將多面向導覽新增至搜尋結果。

第一個查詢會擷取 baseRate 值落在特定範圍內的類別、評等、標籤和房間的 Facet。請注意，最後一個 Facet 位於「房間」集合的子欄位上。 Facet 會計算父檔（Hotels）而非中繼子檔（Rooms），因此響應會決定每個定價類別中具有任何房間的旅館數目。

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

用戶選取評等 3 和類別「Motel」後，這個第二個範例使用篩選器來縮小之前多面向查詢結果的範圍。

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

第三個範例會針對查詢中傳回的唯一詞彙設定上限。默認值為 10，但您可以使用 facet 屬性上的 count 參數來增加或減少此值。此範例會傳回城市的 Facet (限制為 5 個)。

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

此範例顯示「類別」、「標籤」和「評等」的三個 Facet，其中的「標籤」具有計數覆寫，「評等」具有範圍覆寫；兩者原本在索引中都儲存為雙精度浮點數。

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

對於每個多面向導覽樹狀目錄，預設限制為查詢找到的排名前 10 的 Facet 執行個體。對於導覽結構來說，此項預設值相當合理，因為它維持值清單在一個可管理的大小。您可以透過指派「計數」值來覆蓋預設值。例如，"Tags,count:5" 會將 [標記] 區段底下的標記數目減少為前五個。

針對 [數值] 和 [日期時間] 值，您可以明確設定 Facet 欄位的值 (例如，facet=Rating,values:1|2|3|4|5)，將結果分成連續範圍 (根據數值或時間週期的範圍)。或者，您也可以新增「間隔」，如同在 facet=Rating,interval:1 中一樣。

已使用 0 做為起始點，清單中的值做為結束點建置各範圍，並且修剪之前的範圍來建立離散間隔。

相異值範例

您可以編寫查詢，使每個可 Facet 欄位傳回相異值計數。此範例會編寫與所有文件相符的空查詢或未限定查詢 ("search": "*")，但只要將 top 設定為零，就能僅取得計數，而沒有結果。

為了簡潔起見，此查詢只包含兩個字段，在旅館範例索引中標示為 facetable 。

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

此查詢的結果如下所示：

{
  "@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": []
}

備註

這項功能目前處於公開預覽狀態。此預覽版在沒有服務等級協議的情況下提供，不建議用於生產工作負載。可能不支援特定功能，或可能已經限制功能。如需詳細資訊，請參閱 Microsoft Azure 預覽版增補使用條款。

從 2025-03-01-preview REST API 開始，您可以在 Azure 入口網站中，使用 > 和 ; 運算符來設定 Facet 階層。

巢狀（階層式）運算符 > 表示父子關聯性，分號運算符 ; 代表相同巢狀層級的多個字段，這些字段都是同一父系的所有子系。父代必須僅包含一個欄位。父欄位與子欄位都必須是 facetable。

包含 Facet 階層的 Facet 運算式中的作業順序如下：

將 Facet 欄位的 Facet 參數分隔的選項運算子 (逗號 ,)，例如 Rooms/BaseRate,values 中的逗號
括弧，例如括住 (Rooms/BaseRate,values:50 ; Rooms/Type) 的括弧。
巢狀運算子 (角括弧 >)
附加運算子 (分號 ;)，在本節中的第二個範例 "Tags>(Rooms/BaseRate,values:50 ; Rooms/Type)" 有其示範，其中，兩個子 Facet 在 Tags 父代下具有對等關係。

層面階層有數個範例。第一個範例是只傳回幾個文件的查詢，有助於檢視完整的回應。 Facet 會計算父檔（Hotels）而非中繼子檔（Rooms），因此回應會決定每個 Facet 貯體中具有任何房間的旅館數目。

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

此查詢的結果如下所示。兩家酒店都有游泳池。對於其他標籤，只有一家旅館提供這項便利設施。

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

第二個範例是前一個的延伸，示範具有多個子系的多個最上層 Facet。請注意，分號 (;) 運算子會分隔每個子系。

POST /indexes/hotels-sample-index/docs/search?api-version=2025-03-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 
}

為了簡潔而修剪過的部分回應顯示「標籤」具有房間基準費率和類型的子 Facet。在旅館範例索引中，匹配+ocean的兩家酒店都有各類房型和游泳池。

{
  "@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
            }
          ]
        }}]},
  ...
}

最後一個範例顯示會影響巢狀層級的括弧優先順序規則。假設您想要按此順序傳回 Facet 階層。

Address/StateProvince
  Address/City
    Category
    Rating

若要傳回此階層，請建立一個查詢，並且讓「類別」和「評等」成為「地址/城市」下的同層級。

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

如果您移除最內層的括弧，「類別」和「評等」就不再是同層級，因為優先順序規則指出 > 運算子會在 ; 之前受到評估。

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

最上層的父系仍然是 Address/StateProvince，但現在 Address/City 和 Rating 位於相同層級。

Address/StateProvince
  Rating
  Address/City
    Category

備註

從 2025-03-01-preview REST API 開始，您可以在 Azure 入口網站中設定 Facet 篩選器。

Facet 篩選可讓您將傳回的 Facet 值限定於與指定的規則運算式相符的值。兩個新參數接受套用至 Facet 欄位的正規表示式：

includeTermFilter 將 Facet 值篩選為符合正則表達式的值
excludeTermFilter 會篩選出與規則運算式不相符的 Facet 值

如果 Facet 字串同時符合這兩個條件，則會以 excludeTermFilter 優先，因為貯體字串的設定會先以 includeTermFilter 進行評估，再使用 excludeTermFilter 進行排除。

只會傳回符合正則表達式的面向值。您可以將這些參數與其他 Facet 選項（例如、 countsort和階層式 Faceting）結合在字串字段上。

由於規則運算式內嵌於 JSON 字串值內，因此必須逸出雙引號 (") 和反斜線 (\) 字元。正則表達式本身是以正斜線（/）分隔。如需逸出模式的詳細資訊，請參閱正則表達式搜尋。

下列範例示範如何逸出正則表達式中的特殊字元，例如反斜杠、雙引號或正則表達式語法字元。

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

以下 Facet 篩選範例會就「預算」和「長期住宿」來比對旅館，且每個旅館類別都有「評等」子類別。

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

下列範例是縮寫的回應（省略旅館檔以求簡潔）。

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

備註

從 2025-03-01-preview REST API 開始，您可以在 Azure 入口網站中彙總 Facet。

Facet 彙總可讓您從 Facet 值中計算計量。匯總功能會與現有的面向化選項搭配運作。唯一支援的計量是 sum。將 metric: sum 新增至數值 Facet 時，會彙總每個貯體的所有值。

您可以新增預設值，以在文件包含該欄位的 Null 時使用："facets": [ "Rooms/SleepsCount, metric: sum, default:2"]。如果 Room/SleepsCount 欄位有 Null 值，則會以預設值取代遺漏值。

您可以加總任何數值數據類型中的可分面字段（不包括向量和地理坐標）。

以下是使用 hotels-sample-index 的範例。「房間/睡眠計數」欄位是可分面且具有數值特性的，所以我們選擇此欄位來示範求和。如果我們加總該欄位，我們會取得整個旅館的睡眠計數。先前提到，Facet 會計算父文件 (旅館)，而不是中繼子文件 (房間)，因此回應會加總整個旅館所有房間的 SleepsCount。在此查詢中，我們新增了篩選條件，僅加總一家旅館的 SleepsCount。

POST /indexes/hotels-sample-index/docs/search?api-version=2025-03-01-Preview

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

查詢的回應可能如下列範例所示。風海模型可容納總共40位客人。

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

後續步驟

重新流覽工具和 API 的 Facet 導覽組態，並檢閱在程式碼中使用 Facet 的最佳做法。

我們建議使用 C#：將搜尋新增至 Web 應用程式，以取得包含呈現層程式代碼的多面向導覽範例。此範例也包含篩選、建議和自動完成。它會針對表示層使用 JavaScript 和 React。

共用方式為

多面向導覽範例

Facet 參數和語法

基本 Facet 範例

相異值範例

Facet 階層範例

Facet 篩選範例

Facet 彙總範例

後續步驟

意見反應

其他資源