分面导航示例

本部分通过示例扩展分面导航配置，这些示例展示了基本用法和其他场景。

可分面字段在索引中定义，但 facet 参数和表达式在查询请求中定义。 如果有具有可分面字段的索引，可以尝试对现有索引进行分面层次结构（预览）、分面聚合（预览）和分面筛选器（预览）。

Facet 参数和语法

根据 API，分面查询通常是应用于搜索结果的分面表达式数组。 每个 facet 表达式都包含一个可分面字段名称，可以选择后跟逗号分隔的名称值对列表。

• Facet 查询是包含 facet 属性的查询请求。
• 可分面字段 是具有 facetable 属性的搜索索引中的字段定义。
• count 是搜索结果中找到的每个方面的匹配项数。

下表介绍了示例中使用的分面参数。

count 和 sort 可以在同一属性规格中组合，但不能与 interval 或 values 组合。

interval 和 values 不能一起结合。

如果未指定 timeoffset，日期时间的间隔分面将基于 UTC 时间计算。 例如， "facet=lastRenovationDate,interval:day"日边界从 00：00：00 UTC 开始。

基本方面示例

以下分面查询适用于 hotels-sample 索引。 可以在搜索资源管理器中使用 JSON 视图 粘贴 JSON 查询。 如需入门帮助，请参阅 向搜索结果添加分面导航。

此第一个查询检索类别、评级、标记和具有特定范围内的 baseRate 值的会议室的 facet。 请注意，最后一个 facet 位于会议室集合的子字段上。 Facet 将计算父文档（酒店）而不是中间子文档（房间），因此响应确定每个定价类别中具有任何房间的酒店数。

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 
}  

第二个示例使用筛选器在用户选择“Rating 3”和“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  
} 

第三个示例设置查询中返回的唯一术语的上限。 默认值为 10，但可以使用 facet 属性上的 count 参数增加或减少此值。 此示例返回城市的分面，最多限为 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”应用范围覆盖，此外，在索引中它们以双精度数存储。

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
}

对于每个分面导航树，系统默认限制为查询发现的前 10 个 facet 实例。 此默认值对于导航结构有意义，因为它会将值列表保留为可管理的大小。 可以通过将值赋给“count”来替代默认值。 例如， "Tags,count:5" 将“标记”部分下的标记数减少到前五名。

仅对于 Numeric 和 DateTime 值，可以在分面字段上显式设置值（例如，facet=Rating,values:1|2|3|4|5），从而将结果分隔为连续范围（根据数值或时间段确定范围）。 或者，可以添加“interval”，如中所示 facet=Rating,interval:1。

每个范围都是使用 0 作为起点构建的，列表中的一个值作为终结点，然后剪裁上一个范围以创建离散间隔。

不同值示例

可以构建一个查询，该查询将返回每个“facetable”字段中唯一值的计数。 本示例构建一个空查询或不限定的查询（"search": "*"），该查询会匹配所有文档，但通过将 top 设置为零，只能获取计数，而不返回结果。

为了简洁起见，此查询仅包含两个在 hotels-sample 索引中标记为 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": []
}

Facet 层次结构示例（预览版）

使用 latest preview REST API 或 Azure 门户，可以使用 > 和 ; 运算符配置分面层次结构。

分面表达式中包括分面层次结构的操作顺序如下：

• 选项运算符（逗号 ,）用于分隔 facet 字段的 facet 参数，例如 Rooms/BaseRate,values 中的逗号
• 括号，如将 (Rooms/BaseRate,values:50 ; Rooms/Type) 括起来的符号。
• 嵌套运算符（尖括号 >）
• 追加运算符（分号 ;），如本部分中第二个示例 "Tags>(Rooms/BaseRate,values:50 ; Rooms/Type)" 中所示，其中两个子 facet 是标记父级下面的对等方。

请注意，在嵌套和追加操作之前处理括号： A > B ; C 将不同于 A > (B ; C)。

分面层次结构有几个示例。 第一个示例是只返回几个文档的查询，这有助于查看完整响应。 Facet 对父文档（Hotels）而不是中间子文档（会议室）进行计数，因此响应确定每个 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

若要返回此层次结构，请创建一个查询，其中类别和分级是地址/城市下的同级。

  { 
    "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 筛选，可以将返回的 facet 值限制为符合指定正则表达式的值。 两个新参数接受应用于 facet 字段的正则表达式：

• includeTermFilter 将分面值筛选为与正则表达式匹配的值
• excludeTermFilter 将分面值筛选为与正则表达式不匹配的值

如果 facet 字段同时满足两个条件，则优先使用 excludeTermFilter，因为存储桶字段组是先使用 includeTermFilter 进行评估，然后通过 excludeTermFilter 排除的。

仅返回与正则表达式匹配的分面值。 可以将这些参数与其他分面选项（例如，countsort和分层分面）组合在字符串字段上。

由于正则表达式嵌套在 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 门户聚合维度。

分面聚合允许从分面值计算指标。 聚合功能可与现有的 facet 选项一起使用。

设置基数聚合的精度阈值

在基数聚合中，可以将选项 precisionThreshold 设置为一个界限，以区分那些预期能够接近准确的计数和那些可能不太准确的计数。 最大值为 40,000。 默认值为 3,000。

分面操作在内存中进行。 增加 precisionThreshold 会导致内存消耗量增加（ precisionThreshold 值乘以 8 字节）。

示例：对分面聚合求和

您可以对数值数据类型的任何可分面字段（矢量和地理坐标除外）求和。

下面是使用 hotels-sample 索引的示例。 Room/SleepsCount 字段可分面且具有数值，因此我们选择此字段来演示总和。 如果我们对该字段求和，我们将获取整个酒店睡眠计数。 回想一下，facet 对父文档（酒店）而不是中间子文档（房间）进行计数，因此响应对整个酒店的所有房间的 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 
            } 
        ] 
    } 
}

示例：指定默认值以替换缺失值

当文档不包含值时，所有指标都支持指定默认值。

• 对于非字符串类型（numeric、datetime、boolean），请将default参数设置为特定值： "default: 42"

• 对于字符串类型，请将 default 参数设置为使用单个撇号分隔符分隔的字符串： "default: 'mystringhere'".

如果文档包含该字段的 null，则可以添加要使用的默认值： "facets": [ "Rooms/SleepsCount, metric: sum, default:2"] 如果房间的 Rooms/SleepsCount 字段为 null，则默认值将替代缺失值。

下面是一个说明每个字段类型的默认规范的请求。

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#：将搜索添加到 Web 应用，以获取包含表示层代码的分面导航示例。 此示例还包括筛选器、建议和自动完成。 它对呈现层使用 JavaScript 和 React。