Azure 认知搜索中的 OData 全文搜索函数 - search.ismatchsearch.ismatchscoringOData full-text search functions in Azure Cognitive Search - search.ismatch and search.ismatchscoring

Azure 认知搜索支持使用 search.ismatchsearch.ismatchscoring 函数在 OData 筛选器表达式上下文中进行全文搜索。Azure Cognitive Search supports full-text search in the context of OData filter expressions via the search.ismatch and search.ismatchscoring functions. 可以通过这些函数将全文搜索与严格的布尔筛选配合使用,所用方式在仅仅使用 搜索 API 的顶级 search 参数的情况下无法实现。These functions allow you to combine full-text search with strict Boolean filtering in ways that are not possible just by using the top-level search parameter of the Search API.


search.ismatchsearch.ismatchscoring 函数只在搜索 API 的筛选器中受支持。The search.ismatch and search.ismatchscoring functions are only supported in filters in the Search API. 它们在建议 API 或自动完成 API 中不受支持。They are not supported in the Suggest or Autocomplete APIs.


以下 EBNF(扩展巴科斯-瑙尔范式)定义了 search.ismatchsearch.ismatchscoring 函数的语法:The following EBNF (Extended Backus-Naur Form) defines the grammar of the search.ismatch and search.ismatchscoring functions:

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

下面还提供了交互式语法图:An interactive syntax diagram is also available:


search.ismatch 函数将全文搜索查询作为筛选表达式的一部分进行求值。The search.ismatch function evaluates a full-text search query as a part of a filter expression. 与搜索查询匹配的文档将在结果集中返回。The documents that match the search query will be returned in the result set. 此函数的以下重载可用:The following overloads of this function are available:

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

下表定义了这些参数:The parameters are defined in the following table:

参数名称Parameter name 类型Type 说明Description
search Edm.String 搜索查询(采用简单完整 Lucene 查询语法)。The search query (in either simple or full Lucene query syntax).
searchFields Edm.String 要在其中进行搜索的可搜索字段的逗号分隔列表;默认为索引中的所有可搜索字段。Comma-separated list of searchable fields to search in; defaults to all searchable fields in the index. search 参数中使用字段搜索时,在 Lucene 查询中指定的字段会覆盖在此参数中指定的任何字段。When using fielded search in the search parameter, the field specifiers in the Lucene query override any fields specified in this parameter.
queryType Edm.String 'simple''full';默认为 'simple''simple' or 'full'; defaults to 'simple'. 指定 search 参数中使用的查询语言。Specifies what query language was used in the search parameter.
searchMode Edm.String 'any''all',默认为 'any''any' or 'all', defaults to 'any'. 指示必须匹配 search 参数中的任意搜索词还是全部搜索词才能将文档视为匹配。Indicates whether any or all of the search terms in the search parameter must be matched in order to count the document as a match. search 参数中使用 Lucene 布尔运算符时,这些运算符的优先级高于该参数。When using the Lucene Boolean operators in the search parameter, they will take precedence over this parameter.

所有上述参数均相当于搜索 API 中的相应搜索请求参数All the above parameters are equivalent to the corresponding search request parameters in the Search API.

search.ismatch 函数返回类型为 Edm.Boolean 的值,这样你就可以使用布尔逻辑运算符通过其他筛选器子表达式对其进行编辑。The search.ismatch function returns a value of type Edm.Boolean, which allows you to compose it with other filter sub-expressions using the Boolean logical operators.


Azure 认知搜索不支持在 lambda 表达式中使用 search.ismatchsearch.ismatchscoringAzure Cognitive Search does not support using search.ismatch or search.ismatchscoring inside lambda expressions. 这意味着,如果对象集合可以将全文搜索匹配项与同一对象上严格的筛选器匹配项相关联,则不能基于该对象集合编写筛选器。This means it is not possible to write filters over collections of objects that can correlate full-text search matches with strict filter matches on the same object. 若要更详细地了解此限制和相关示例,请参阅排查 Azure 认知搜索中的集合筛选器问题For more details on this limitation as well as examples, see Troubleshooting collection filters in Azure Cognitive Search. 若要更深入地了解为何存在此限制,请参阅了解 Azure 认知搜索中的集合筛选器For more in-depth information on why this limitation exists, see Understanding collection filters in Azure Cognitive Search.


search.ismatch 函数一样,对于与作为参数传递的全文搜索查询匹配的文档,search.ismatchscoring 函数会返回 trueThe search.ismatchscoring function, like the search.ismatch function, returns true for documents that match the full-text search query passed as a parameter. 它们之间的区别在于,与 search.ismatchscoring 查询匹配的文档的相关性分数与文档整体分数有关,而对于 search.ismatch,文档分数不会发生更改。The difference between them is that the relevance score of documents matching the search.ismatchscoring query will contribute to the overall document score, while in the case of search.ismatch, the document score won't be changed. 此函数的以下重载可用于与 search.ismatch 的参数相同的参数:The following overloads of this function are available with parameters identical to those of search.ismatch:

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

可以在同一筛选器表达式中使用 search.ismatchsearch.ismatchscoring 函数。Both the search.ismatch and search.ismatchscoring functions can be used in the same filter expression.


查找包含“waterfront”一词的文档。Find documents with the word "waterfront". 此筛选器查询与包含 search=waterfront搜索请求相同。This filter query is identical to a search request with search=waterfront.


查找带有“hostel”一词且评分大于或等于 4 分的文档,或带有“motel”一词且评分等于 5 分的文档。Find documents with the word "hostel" and rating greater or equal to 4, or documents with the word "motel" and rating equal to 5. 请注意,如果没有 search.ismatchscoring 函数,则无法表达此请求。Note, this request could not be expressed without the search.ismatchscoring function.

    search.ismatchscoring('hostel') and Rating ge 4 or search.ismatchscoring('motel') and Rating eq 5

查找没有“luxury”一词的文档。Find documents without the word "luxury".

    not search.ismatch('luxury')

查找包含短语“ocean view”或评分等于 5 分的文档。Find documents with the phrase "ocean view" or rating equal to 5. search.ismatchscoring 查询仅针对 HotelNameRooms/Description 字段执行。The search.ismatchscoring query will be executed only against fields HotelName and Rooms/Description.

仅与析取的第二个子句匹配的文档也将被返回,即 Rating 等于 5 分的酒店。Documents that matched only the second clause of the disjunction will be returned too -- hotels with Rating equal to 5. 为了清楚地表明这些文档与表达式的任何得分部分都不匹配,它们返回的分数将为零。To make it clear that those documents didn't match any of the scored parts of the expression, they will be returned with score equal to zero.

    search.ismatchscoring('"ocean view"', 'Rooms/Description,HotelName') or Rating eq 5

在酒店描述中查找词条“hotel”和“airport”相距不超过 5 个字词且不允许吸烟(至少部分房间是这样)的文档。Find documents where the terms "hotel" and "airport" are within 5 words from each other in the description of the hotel, and where smoking is not allowed in at least some of the rooms. 此查询使用完整 Lucene 查询语言This query uses the full Lucene query language.

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

后续步骤Next steps