Azure AI 搜索中的 OData 全文搜索函数 - `search.ismatch` 和 `search.ismatchscoring`

2025-08-25

Azure AI 搜索支持使用和 search.ismatch 函数在 search.ismatchscoring上下文中进行全文搜索。通过这些函数，可以使用搜索 API 的顶级search参数，将全文搜索与严格的布尔筛选组合在一起。

注意

search.ismatch 和 search.ismatchscoring 函数只在搜索 API 的筛选器中受支持。建议或自动完成 API 不支持它们。

语法

以下 EBNF（扩展巴科斯-瑙尔范式）定义了 search.ismatch 和 search.ismatchscoring 函数的语法：

search_is_match_call ::=
    'search.ismatch'('scoring')?'(' search_is_match_parameters ')'

search_is_match_parameters ::=
    string_literal(',' string_literal(',' query_type ',' search_mode)?)?

query_type ::= "'full'" | "'simple'"

search_mode ::= "'any'" | "'all'"

下面还提供了交互式语法图：

Azure AI 搜索的 OData 语法图

注意

请参阅适用于 Azure AI 搜索的 OData 表达式语法参考以获取完整的 EBNF。

search.ismatch

search.ismatch 函数将全文搜索查询作为筛选表达式的一部分进行求值。结果集中返回匹配的文档。此函数的以下重载可用：

search.ismatch(search)
search.ismatch(search, searchFields)
search.ismatch(search, searchFields, queryType, searchMode)

下表定义了这些参数：

参数名称	类型	说明
`search`	`Edm.String`	搜索查询（采用简单或完整 Lucene 查询语法）。
`searchFields`	`Edm.String`	要在其中进行搜索的可搜索字段的逗号分隔列表；默认为索引中的所有可搜索字段。在参数中使用字段搜索`search`时，Lucene 查询中的字段说明符将替代此参数中指定的任何字段。
`queryType`	`Edm.String`	`'simple'` 或 `'full'`；默认为 `'simple'`。指定 `search` 参数中使用的查询语言。
`searchMode`	`Edm.String`	`'any'` 或 `'all'`，默认为 `'any'`。指示必须匹配 `search` 参数中的任意搜索词还是全部搜索词才能将文档视为匹配。在参数中使用 Lucene 布尔运算符`search`时，它们优先于此参数。

所有上述参数均相当于搜索 API 中的相应搜索请求参数。

该 search.ismatch 函数返回一个类型的 Edm.Boolean值，它允许你使用布尔逻辑运算符与其他筛选器子表达式一起组合它。

注意

Azure AI 搜索不支持使用 search.ismatch 或 search.ismatchscoring 内部 lambda 表达式。这意味着无法针对对象集合编写筛选器，这些对象集合可以将全文搜索匹配项与同一对象的严格筛选器匹配项相关联。有关此限制以及示例的详细信息，请参阅 Azure AI 搜索中的收集筛选器疑难解答。若要更深入地了解为何存在此限制，请参阅了解 Azure AI 搜索中的集合筛选器。

search.ismatchscoring

与 search.ismatchscoring 函数一样，对于与作为参数传递的全文搜索查询匹配的文档，search.ismatch 函数会返回 true。它们的区别在于，与查询匹配 search.ismatchscoring 的文档的相关性分数对整体文档分数有所贡献，而对于 search.ismatch文档分数，文档分数不会更改。此函数的以下重载可用于与 search.ismatch 的参数相同的参数：

search.ismatchscoring(search)
search.ismatchscoring(search, searchFields)
search.ismatchscoring(search, searchFields, queryType, searchMode)

可以在同一筛选器表达式中使用 search.ismatch 和 search.ismatchscoring 函数。

示例

查找包含“waterfront”一词的文档。此筛选器查询与包含的search=waterfront相同。

    search.ismatchscoring('waterfront')

下面是此请求的完整查询语法，可在 Azure 门户中的搜索资源管理器中运行。输出由海滨、水和正面的比赛组成。

{
  "search": "*",
  "select": "HotelId, HotelName, Description",
  "searchMode": "all",
  "queryType": "simple",
  "count": true,
  "filter": "search.ismatchscoring('waterfront')"
}

查找“池”一词的文档，评级大于或等于 4，或者包含单词“motel”且等于 3.2 的文档。请注意，在没有函数的情况下 search.ismatchscoring 无法表示此请求。

    search.ismatchscoring('pool') and Rating ge 4 or search.ismatchscoring('motel') and Rating eq 3.2

下面是此搜索资源管理器请求的完整查询语法。输出包括对池评级大于 4 或评级等于 3.2 的汽车旅馆的匹配项。

{
  "search": "*",
  "select": "HotelId, HotelName, Description, Tags, Rating",
  "searchMode": "all",
  "queryType": "simple",
  "count": true,
  "filter": "search.ismatchscoring('pool') and Rating ge 4 or search.ismatchscoring('motel') and Rating eq 3.2"
}

查找没有“luxury”一词的文档。

    not search.ismatch('luxury')

下面是此请求的完整查询语法。输出由术语豪华的匹配组成。

{
  "search": "*",
  "select": "HotelId, HotelName, Description, Tags, Rating",
  "searchMode": "all",
  "queryType": "simple",
  "count": true,
  "filter": "not search.ismatch('luxury')"
}

查找短语“ocean”或 rating 等于 3.2 的文档。查询 search.ismatchscoring 仅针对字段 HotelName 执行，并且 Description。

下面是此请求的完整查询语法。仅与解除禁令的第二个子句匹配的文档也返回（具体而言，等于Rating3.2的酒店）。为了明确说明这些文档与表达式的任何评分部分不匹配，它们将返回分数等于零。

{
  "search": "*",
  "select": "HotelId, HotelName, Description, Rating",
  "searchMode": "all",
  "queryType": "full",
  "count": true,
  "filter": "search.ismatchscoring('ocean', 'Description,HotelName') or Rating eq 3.2"
}

输出由 4 场比赛组成：在说明或酒店名称中提及“海洋”的酒店，或评级为 3.2 的酒店。请注意第二个子句上匹配项的搜索分数为零。

{
  "@odata.count": 4,
  "value": [
    {
      "@search.score": 1.6076145,
      "HotelId": "18",
      "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.",
      "Rating": 4.2
    },
    {
      "@search.score": 1.0594962,
      "HotelId": "41",
      "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.",
      "Rating": 3.5
    },
    {
      "@search.score": 0,
      "HotelId": "40",
      "HotelName": "Trails End Motel",
      "Description": "Only 8 miles from Downtown. On-site bar/restaurant, Free hot breakfast buffet, Free wireless internet, All non-smoking hotel. Only 15 miles from airport.",
      "Rating": 3.2
    },
    {
      "@search.score": 0,
      "HotelId": "26",
      "HotelName": "Planetary Plaza & Suites",
      "Description": "Extend Your Stay. Affordable home away from home, with amenities like free Wi-Fi, full kitchen, and convenient laundry service.",
      "Rating": 3.2
    }
  ]
}

在酒店描述中查找术语“酒店”和“机场”在 5 个字以内的文档，以及至少部分房间不允许吸烟的文档。

    search.ismatch('"hotel airport"~5', 'Description', 'full', 'any') and Rooms/any(room: not room/SmokingAllowed)

下面是完整的查询语法。若要在搜索资源管理器中运行，请使用反斜杠字符转义内部引号。

{
  "search": "*",
  "select": "HotelId, HotelName, Description, Tags, Rating",
  "searchMode": "all",
  "queryType": "simple",
  "count": true,
  "filter": "search.ismatch('\"hotel airport\"~5', 'Description', 'full', 'any') and Rooms/any(room: not room/SmokingAllowed)"
}

输出包含一个文档，其中字词“hotel”和“airport”在 5 个单词的距离内。大多数酒店允许吸烟，包括此搜索结果中的房间。

{
  "@odata.count": 1,
  "value": [
    {
      "@search.score": 1,
      "HotelId": "40",
      "HotelName": "Trails End Motel",
      "Description": "Only 8 miles from Downtown. On-site bar/restaurant, Free hot breakfast buffet, Free wireless internet, All non-smoking hotel. Only 15 miles from airport.",
      "Tags": [
        "bar",
        "free wifi",
        "restaurant"
      ],
      "Rating": 3.2
    }
  ]
}

查找在“说明”字段中包含以字母“lux”开头的单词的文档。此查询结合使用前缀搜索和 search.ismatch。

    search.ismatch('lux*', 'Description')

下面是完整查询：

{
  "search": "*",
  "select": "HotelId, HotelName, Description, Tags, Rating",
  "searchMode": "all",
  "queryType": "simple",
  "count": true,
  "filter": "search.ismatch('lux*', 'Description')"
}

输出由以下匹配项组成。

{
  "@odata.count": 4,
  "value": [
    {
      "@search.score": 1,
      "HotelId": "18",
      "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"
      ],
      "Rating": 4.2
    },
    {
      "@search.score": 1,
      "HotelId": "13",
      "HotelName": "Luxury Lion Resort",
      "Description": "Unmatched Luxury. Visit our downtown hotel to indulge in luxury accommodations. Moments from the stadium and transportation hubs, we feature the best in convenience and comfort.",
      "Tags": [
        "bar",
        "concierge",
        "restaurant"
      ],
      "Rating": 4.1
    },
    {
      "@search.score": 1,
      "HotelId": "16",
      "HotelName": "Double Sanctuary Resort",
      "Description": "5 star Luxury Hotel - Biggest Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.",
      "Tags": [
        "view",
        "pool",
        "restaurant",
        "bar",
        "continental breakfast"
      ],
      "Rating": 4.2
    },
    {
      "@search.score": 1,
      "HotelId": "14",
      "HotelName": "Twin Vortex Hotel",
      "Description": "New experience in the making. Be the first to experience the luxury of the Twin Vortex. Reserve one of our newly-renovated guest rooms today.",
      "Tags": [
        "bar",
        "restaurant",
        "concierge"
      ],
      "Rating": 4.4
    }
  ]
}

共用方式為

Azure AI 搜索中的 OData 全文搜索函数 - search.ismatch 和 search.ismatchscoring

语法

search.ismatch

search.ismatchscoring

示例

后续步骤

其他資源

Azure AI 搜索中的 OData 全文搜索函数 - `search.ismatch` 和 `search.ismatchscoring`