分面導航範例

本節將擴展 多面導航配置 ，並展示基本使用範例及其他情境。

可 Facet 欄位是在索引中定義，但 Facet 參數和運算式是在查詢要求中定義。 如果你有帶有面表欄位的索引，可以嘗試在現有索引上使用面狀結構（預覽）、面狀彙總（預覽）和面狀篩選器（預覽）。

面參數與語法

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

• 面向查詢 是一種包含面向屬性的查詢請求。
• facetable field 是搜尋索引中帶有 facetable 屬性的欄位定義。
• count 是搜尋結果中每個面向的匹配數量。

下表描述了範例中使用的面參數。

count 和 sort 可以在相同的面規範中組合，但無法與 interval 或 values合併。

interval 且 values 無法合併。

若未指定 timeoffset，則將以 UTC 時間計算日期時間的區間面向。 例如，對於 ， "facet=lastRenovationDate,interval:day"日邊界從 00：00：00 UTC 開始。

基本 Facet 範例

下列 Facet 查詢可針對 hotels-sample 索引運作。 你可以在搜尋總管裡用 JSON 檢視 來貼上 JSON 查詢。 如需入門協助，請參閱 「新增多面導覽至搜尋結果」。

第一個查詢會擷取 Categories、Ratings、Tags，以及 baseRate 值位於特定範圍內之房間的 Facet。 請注意，最後一個 Facet 位於 Rooms 集合的子欄位上。 分面計算的是母文件（飯店），而非中間子文件（客房），因此回應決定了每個價格類別中擁有房間的 飯店 數量。

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 
}  

第二個範例使用過濾器，在使用者選擇評分 3 和類別「汽車旅館」後，縮小先前的多面查詢結果範圍。

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  
} 

第三個範例設定查詢中唯一回傳詞的上限。 預設值是 10，但你可以利用 facet 屬性上的計數參數來增加或減少這個數值。 此範例回傳城市的屬性，限制為5個。

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

此範例顯示「Category」、「Tags」和「Rating」的三個 Facet，並對「Tags」設定計數覆寫，對「Rating」設定範圍覆寫，否則「Rating」在索引中會儲存為 double。

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
}

對於每個 Facet 導覽樹，查詢找到的前 10 個 Facet 執行個體有預設限制。 這種預設設定對於導航結構來說很合理，因為它能讓值清單保持在可管理的大小。 你可以透過為「count」設定值來覆蓋預設值。 例如，將 "Tags,count:5" 標籤區塊下的標籤數量減少到前五名。

僅針對數字值和日期時間值，你可以在面欄位（例如 facet=Rating,values:1|2|3|4|5）上明確設定值，將結果分成連續的範圍（可以是基於數值或時間段的範圍）。 或者，你也可以加上「區間」，如 facet=Rating,interval:1。

每個範圍以 0 作為起點建立，從清單中取一個值作為終點，然後從前一個範圍中修剪，形成離散區間。

不同價值範例

您可以制定查詢，傳回每個可 Facet 欄位的相異值計數。 這個範例會構建一個空或無限定的查詢"search": "*"，可以匹配所有文件，但通過將top設為零，您只會得到計數，而無結果。

為了簡潔起見，此查詢僅包含兩個在 hotels-sample index 中標示為 facetable 的欄位。

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

此查詢結果如下：

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

構面階層範例（預覽）

使用 最新預覽版 REST API 或 Azure 入口網站，你可以使用 > 和 ; 運算子來設定面層級結構。

包含面階層的面表達式中的操作順序為：

• 選項運算子 (逗號 ,) 會分隔 Facet 欄位的 Facet 參數，例如 Rooms/BaseRate,values 中的逗號
• 括號，例如包住 ((Rooms/BaseRate,values:50 ; Rooms/Type)) 的括號。
• 巢狀運算子 (角括號 >)
• 附加運算子 (分號 ;)，本區段第二個範例 "Tags>(Rooms/BaseRate,values:50 ; Rooms/Type)" 示範了此運算子，其中兩個子 Facet 是 Tags 父項下的對等項。

請注意，括號的處理優先於巢狀與附加操作：A > B ; C 的結果會與 A > (B ; C) 不同。

各種範例顯示層次結構。 第一個例子是一個只回傳少數文件的查詢，這對於查看完整回應很有幫助。 Facet 會計算父文件 (旅館)，而不是中繼子文件 (房間)，因此回應會判斷每個 Facet 貯體中具有任何房間的旅館數量。

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 
}

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

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

為簡潔而修剪的部分回應會顯示標籤，以及房間基本費率和類型的子 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

要回傳此階層，請建立一個查詢，其中 Category 與 Rating 在地址/城市下為兄弟。

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

若移除最內側括號，Category 和 Rating 將不再是同級，因為優先規則意味著>運算子在;之前被評估。

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

分面篩選範例（預覽）

你可以使用 latest preview REST API 或 Azure 入口網站來設定 facet 篩選器。

分面過濾功能使您能限縮回傳的分面值至僅符合規定的正則表達式之項目。 兩個新參數接受一個正則表達式，並應用於面面場：

• includeTermFilter 將面數值過濾為符合正則表達式的值
• excludeTermFilter 篩選出與正則表達式不相符的面向值

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

只有與正則表達式相符的屬性值會被回傳。 你可以將這些參數與其他多面選項（例如、 count、 sort、以及 階層式多面）在字串欄位中結合使用。

由於正則表達式巢狀於 JSON 字串值中，你必須跳脫雙引號（"）和反斜線\（）字元。 正則表達式本身以斜線/（）作為界定。 欲了解更多逃逸模式的資訊，請參閱 正則表達式搜尋。

以下範例展示了如何跳脫正則表達式中的特殊字元，例如反斜線、雙引號或正則表達式語法字元。

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

以下是一個 Facet 篩選器範例，它會比對「經濟型」與「長期住宿型」飯店，並將「評等」作為各個飯店類別的子項。

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 
} 

以下範例為簡短回應（為簡潔起見省略飯店文件）。

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

面聚合範例（預覽）

使用 最新預覽版 REST API 或 Azure 入口，你可以彙整各方面。

面數彙整可以讓你從面數值計算指標。 聚合功能可與現有的切割選項並行運作。

設定基數聚合的精確度閾值

在基數聚合中，你可以設定 precisionThreshold 一個選項作為分界線，分隔預期接近準確的計數與較不準確的計數。 最高價值是40,000。 預設值是3,000。

面向化是在記憶體中執行的。 增加 precisionThreshold 會增加記憶體消耗量（precisionThreshold 值乘以 8 位元組）。

範例：SUM Facet 彙總

你可以對任何數值資料型態的面表欄位求和（向量和地理座標除外）。

這裡有一個使用飯店樣本指數的例子。 Rooms/SleepsCount 欄位是面式且數字化的，因此我們選擇這個欄位來展示總和。 如果我們把這個欄位加總，就能得到整間飯店的睡眠人數。 請記住，Facet 會計算父文件 (Hotels)，而不是中繼子文件 (Rooms)，因此回應會加總整個旅館所有房間的 SleepsCount。 在這個查詢中，我們加入了一個篩選器，用來對某家飯店的 SleepsCount 進行加總。

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
}

對該問題的回應可能如下範例。 風海模式可容納共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
        }
      ]
    }
  ]
}

範例：所有彙總的組合

這裡有一個使用假設性「facets」索引的範例，該索引顯示每種聚合的語法。 請注意，基數有一個額外的 precisionThreshold 選項 (預設值為 3,000)，在此範例中設定為 40,000。

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

對該問題的回應可能如下範例。

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

範例：指定一個預設替換缺失值

所有指標都支援在文件中不包含某個值時指定預設值。

• 對於非字串類型（數字型、日期時間型、布林型），將參數設 default 為特定值： "default: 42" 。

• 對於字串類型，將參數設 default 為一個字串，並以單一撇號分隔符 "default: 'mystringhere'"分隔：。

如果文件中欄位有空，你可以新增預設值作為使用： "facets": [ "Rooms/SleepsCount, metric: sum, default:2"]。 如果房間的 Rooms/SleepsCount 欄位為空值，預設值會替換缺失值。

這裡有一個請求，說明每種欄位類型的預設規格。

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

對於字串欄位，預設值會以單引號字元來分隔。 要跳脫字符，請在前面加反斜線「\」。 所有字元在字串分隔符內皆有效。 結束字元不能是反斜線。

範例：同一欄位上的多個指標

如果底層資料支持使用案例，你可以在同一欄位指定多個指標。

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

對該問題的回應可能如下範例。

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

下一步

重新檢視工具與 API 的 分面導覽設定 ，並檢視程式碼中分面操作 的最佳實務 。

我們推薦 C#：在網頁應用程式中加入搜尋 ，作為包含呈現層程式碼的分面導航範例。 範例還包含篩選器、建議和自動補全功能。 它使用 JavaScript 和 React 作為呈現層。