你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure AI 搜索中的简单查询语法

对于全文搜索方案，Azure AI 搜索实现两种基于 Lucene 的查询语言，每个语言都与查询分析器保持一致。 简单查询分析器是默认值。 它涵盖常见用例，并会尝试解释请求，即使请求未完全组合。 另一个分析器是 Lucene 查询分析器 ，它支持更高级的查询构造。

本文是简单查询分析器的查询语法参考。

这两个分析器的查询语法都适用于通过参数在search中传递的查询表达式，不要与OData 语法混淆，后者在同一请求中的filter和orderby表达式具有其自己的语法和规则。

尽管简单分析器基于 Apache Lucene Simple Query Parser 类，但其实现Azure AI 搜索不包括模糊搜索。 如果需要模糊搜索，建议您考虑使用完整的 Lucene 查询语法作为替代。

示例（简单语法）

此示例展示了一个简单的查询，"queryType": "simple" 区分了该查询并使其语法有效。 虽然下面设置了查询类型，但它是默认值，除非你是从替代类型中进行还原，否则可以省略它。 以下示例是对独立词语的搜索，要求所有匹配的文档都必须包含“pool”。

POST https://{{service-name}}.search.windows.net/indexes/hotel-rooms-sample/docs/search?api-version=2026-04-01
{
  "queryType": "simple",
  "search": "budget hotel +pool",
  "searchMode": "all"
}

此参数 searchMode 与此示例相关。 每当布尔运算符位于查询中时，应通常设置 searchMode=all 以确保 匹配所有 条件。 否则，可以使用默认的searchMode=any，该默认值倾向于提高召回率而非精度。

有关更多示例，请参阅 简单查询语法示例。 有关查询请求和参数的详细信息，请参阅搜索文档（REST API）。

针对字词和短语的关键字搜索

传递给 search 参数的字符串可以包含任何受支持语言的术语或短语、布尔运算符、优先级运算符、用于“开头”查询的通配符或前缀字符、转义字符以及 URL 编码字符。 参数 search 是可选的。 未指定、搜索（search=* 或 search=" "）按任意顺序返回前 50 个文档。

  • 术语搜索是一个或多个字词的查询，其中任何字词都被视为匹配项。

  • 短语搜索是指搜索用引号 " " 引起来的精确短语。 例如，虽然 Roach Motel （没有引号）将按任意顺序搜索包含 Roach 和/或 Motel 任意位置的文档， "Roach Motel" 但（带引号）将仅匹配包含整个短语的文档，并按该顺序（词法分析仍然适用）。

可能需要在短语搜索中对引号进行转义，具体取决于你的搜索客户端。 例如，在某个 POST 请求中，请求正文中针对 "Roach Motel" 的短语搜索可能指定为 "\"Roach Motel\""。 如果你使用的是 Azure SDK，则搜索客户端在序列化搜索文本时会将引号转义。 搜索短语可以作为“Roach Motel”发送。

默认情况下，在参数中 search 传递的所有字符串都会进行词法分析。 请确保了解正在使用的分析器的标记化行为。 通常情况下，当查询结果不是预期的结果时，可以将原因追踪到在查询时对字词进行切分的方式。 可以 测试特定字符串的标记化 ，以确认输出。

任何包含一个或多个字词的文本输入都被视为查询执行的有效起点。 Azure AI 搜索将匹配包含任何或全部条款的文档，包括分析文本期间发现的任何变体。

尽管听起来很简单，但 Azure AI 搜索中的查询执行的一个方面可能会产生意外结果，导致搜索结果增加而不是减少，因为更多的词条和运算符被添加到输入字符串中。 此扩展是否真正发生取决于是否包含NOT运算符，以及如何通过searchMode参数设置来解释NOT在AND或OR行为中的意义。 有关详细信息，请查看布尔运算符下的 NOT 运算符。

布尔运算符

可以在查询字符串中嵌入布尔运算符，以提高匹配的精度。 在简单语法中，布尔运算符基于字符。 不支持文本运算符，如“AND”一词。

字符 例子 使用
+ pool + ocean AND 运算。 例如， pool + ocean 规定文档必须同时包含这两个术语。
| pool | ocean OR操作在找到任一项时即可匹配成功。 在此示例中，查询引擎将在包含pool或ocean或两者都有的文档中返回匹配项。 由于OR是默认的连词运算符，因此也可以将其排除在外，因此pool ocean等效。pool | ocean
- pool – ocean 操作 NOT 返回与不包含该术语的文档相匹配的结果。

查询请求中的 searchMode 参数控制具有 NOT 运算符的字词是通过 AND 运算符还是通过 OR 运算符与查询中的其他字词组合到一起（假定其他字词没有布尔运算符）。 有效值包括 any 或 all。

searchMode=any 通过包括更多结果来增加查询的召回率，默认情况下 - 将被解释为“OR NOT”。 例如， pool - ocean 将匹配包含术语 pool 的文档或不包含术语 ocean的文档。

searchMode=all 通过包括更少的结果来提高查询的精度，默认情况下 - 将被解释为“AND NOT”。 例如，对于 searchMode=any，查询 pool - ocean 将匹配包含术语“pool”的文档和不包含术语“ocean”的所有文档。 这可以说是运算符 - 更直观的行为方式。 因此，如果想要优化搜索的查准率（而非查全率），且用户在搜索中频繁使用 - 运算符，则应考虑使用 searchMode=all 而不是 searchMode=any。

在决定 searchMode 设置时，请考虑各种应用程序中查询的用户交互模式。 搜索信息的用户更有可能在查询中包含运算符，相对而言，电子商务网站具有更多的内置导航结构。

前缀查询

对于“以……开头”的查询，请添加后缀运算符（*）作为词项其余部分的占位符。 前缀查询必须以至少一个纯文本字符开头，然后才能添加后缀运算符。

字符 例子 使用
* lingui* 会匹配“linguistic”或“linguini” 星号 （*） 表示任意长度的一个或多个字符，忽略大小写。

与筛选器类似，前缀查询查找完全匹配项。 因此，没有相关性评分（所有结果都会收到 1.0 的搜索分数）。 请注意，前缀查询可能很慢，尤其是在索引较大且前缀包含少量字符时。 另一种方法（如“边缘 n 元语法标记化”）执行速度可能较快。 使用前缀搜索的字词不能超过 1000 个字符。

简单语法仅支持前缀匹配。 对于匹配字词末尾的后缀或字词中间的内缀，请使用完整的 Lucene 语法进行通配符搜索。

转义搜索运算符

在简单语法中，搜索运算符包含以下字符： + | " ( ) ' \

如果其中的任何字符是索引中的令牌的一部分，请在查询中为其添加一个反斜杠 (\) 作为前缀对其进行转义。 例如，假设你使用了自定义分析器进行整个术语标记化，索引包含字符串“Luxury+Hotel”。 要获得此令牌的完全匹配项，请插入转义字符：search=luxury\+hotel。

为了让更典型的情况变得简单，此规则有两个不需要进行转义的例外：

  • 仅当 NOT 运算符 - 是空格之后的第一个字符时才需要对其进行转义。 如果 - 位于中间（例如在 3352CDD0-EF30-4A2E-A512-3B30AF40F3FD 中），则不需要对其进行转义。

  • 仅当后缀运算符 * 是空格之前的最后一个字符时才需要对其进行转义。 如果 * 位于中间（例如在 4*4=16 中），则不需要对其进行转义。

注意

默认情况下，标准分析器将在词法分析期间根据连字符、空格、&符号和其他字符来删除和拆分单词。 如果需要特殊字符保留在查询字符串中，则可能需要一个分析器来保留索引中的字符。 某些选择包括Microsoft自然语言分析器，这些分析器会保留连字符字词，并且可以使用自定义分析器来处理更复杂的模式。 有关详细信息，请参阅 部分术语、模式和特殊字符。

在 URL 中对不安全字符和保留字符进行编码

确保所有不安全字符和保留字符都在 URL 中编码。 例如，“#”是不安全的字符，因为它是 URL 中的片段/定位点标识符。 如果在 URL 中使用，则必须将字符编码为 %23 该字符。 '&' 和 '=' 是保留字符的示例，因为它们用于分隔参数并指定 Azure AI 搜索 中的值。 有关详细信息，请参阅RFC1738：统一资源定位符（URL）。

不安全字符为 " ` < > # % { } | \ ^ ~ [ ]. 保留字符为 ; / ? : @ = + &.

特殊字符

特殊字符的范围可以是货币符号（如“$”或“€”）到表情符号。 许多分析器（包括默认标准分析器）将在索引期间排除特殊字符，这意味着它们不会在索引中表示。

如果需要特殊字符表示形式，可以分配保留它们的分析器：

  • 空格分析器将空格分隔的任何字符序列视为标记（因此“❤”表情符号将被视为令牌）。

  • 语言分析器，如Microsoft英语分析器（en.microsoft），会将“$”或“€”字符串识别为标记。

若要进行确认，可以 测试分析器 ，以查看为给定字符串生成了哪些令牌。 正如您所预料的，您可能无法通过单个分析器实现完整的令牌化。 解决方法是创建包含相同内容的多个字段，但为每个字段分配不同的分析器（例如，针对语言分析器的description_en、description_fr等）。

使用 Unicode 字符时，请确保在查询 URL 中正确转义了符号（例如，对于“❤”，将使用转义序列 %E2%9D%A4+）。 某些 Web 客户端会自动执行此转换。

优先级（分组）

可以使用括号创建子查询，包括括号语句中的运算符。 例如， motel+(wifi|luxury) 将搜索包含“motel”术语和“wifi”或“luxury”（或两者）的文档。

查询大小限制

如果应用程序以编程方式生成搜索查询，我们建议以这样的方式设计它，这样它就不会生成无限大小的查询。

  • 对于 GET，URL 的长度不能超过 8 KB。

  • 对于 POST（和任何其他请求），其中请求正文包含search其他参数，例如filterorderby，最大大小为 16 MB。 其他限制包括：

    • 搜索子句的最大长度为 100,000 个字符。
    • （由 AND 或 OR 分隔的表达式）中 search 的最大子句数为 1024。
    • 前缀 搜索的最大搜索词长度为 1000 个字符。
    • 查询中任何单个术语的大小也有大约 32 KB 的限制。

有关查询限制的详细信息，请参阅 API 请求限制。

后续步骤

如果要以编程方式构造查询，请查看 在 Azure AI 搜索 中的全文搜索 以了解查询处理的阶段和文本分析的影响。

还可以查看以下文章，了解有关查询构造的详细信息：

  • Last updated on