在 Azure 认知搜索中创建简单的查询Create a simple query in Azure Cognitive Search

在 Azure 认知搜索中,简单查询语法调用默认查询分析器,用于对索引执行全文搜索查询。In Azure Cognitive Search, the simple query syntax invokes the default query parser for executing full text search queries against an index. 此分析程序速度快,处理对象是全文搜索、筛选及分面搜索和地理搜索等常见方案。This parser is fast and handles common scenarios, including full text search, filtered and faceted search, and geo-search.

在本文中,我们将使用示例来阐释简单语法,并填写搜索文档操作的 search= 参数。In this article, we use examples to illustrate the simple syntax, populating the search= parameter of a Search Documents operation.

备选的查询语法是完整的 Lucene,它支持模糊搜索和通配符搜索等更复杂的查询结构,而这可能需要额外的处理时间。An alternative query syntax is Full Lucene, supporting more complex query structures, such as fuzzy and wildcard search, which can take additional time to process. 要获取完整语法的详细信息和演示示例,请参阅使用完整的 Lucene 语法For more information and examples demonstrating full syntax, see Use the full Lucene syntax.

在 Postman 中创建请求Formulate requests in Postman

下面的示例使用“纽约工作岗位”搜索索引,它包含基于纽约市开放数据计划提供的数据集得出的岗位。The following examples leverage a NYC Jobs search index consisting of jobs available based on a dataset provided by the City of New York OpenData initiative. 此数据不应认为是最新或完整数据。This data should not be considered current or complete. 该索引位于 Microsoft 提供的一项沙盒服务上,也就是说无需 Azure 订阅或 Azure 认知搜索即可试用这些查询。The index is on a sandbox service provided by Microsoft, which means you do not need an Azure subscription or Azure Cognitive Search to try these queries.

要在 GET 上发出 HTTP 请求,需具备 Postman 或其等效工具。What you do need is Postman or an equivalent tool for issuing HTTP request on GET. 有关详细信息,请参阅快速入门:探索 Azure 认知搜索 REST APIFor more information, see Quickstart: Explore Azure Cognitive Search REST API.

设置请求标头Set the request header

  1. 在请求标头中,将“Content-Type”设为 application/jsonIn the request header, set Content-Type to application/json.

  2. 添加 api-key,并将其设为此字符串:252044BE3886FE4A8E3BAA4F595114BBAdd an api-key, and set it to this string: 252044BE3886FE4A8E3BAA4F595114BB. 它是托管“纽约工作岗位”索引的沙盒搜索服务的查询密钥。This is a query key for the sandbox search service hosting the NYC Jobs index.

指定请求标头后,只需更改“search=”字符串即可在本文中的各项查询中重复使用 。After you specify the request header, you can reuse it for all of the queries in this article, swapping out only the search= string.

Postman 请求头设置参数

设置请求 URLSet the request URL

请求是一个与包含 Azure 认知搜索终结点和搜索字符串的 URL 配对的 GET 命令。Request is a GET command paired with a URL containing the Azure Cognitive Search endpoint and search string.

Postman 请求头 GET

URL 组合具备以下元素:URL composition has the following elements:

  • https://azs-playground.search.azure.cn/ 是由 Azure 认知搜索开发团队维护的沙盒搜索服务 。https://azs-playground.search.azure.cn/ is a sandbox search service maintained by the Azure Cognitive Search development team.
  • indexes/nycjobs/ 是该服务的索引集合中的“纽约工作岗位”索引 。indexes/nycjobs/ is the NYC Jobs index in the indexes collection of that service. 请求中需同时具备服务名称和索引。Both the service name and index are required on the request.
  • docs 是包含所有可搜索内容的文档集合 。docs is the documents collection containing all searchable content. 请求标头中提供的查询 api-key 仅适用于针对文档集合的读取操作。The query api-key provided in the request header only works on read operations targeting the documents collection.
  • api-version=2020-06-30 设置了 api-version(每个请求都需具备此参数) 。api-version=2020-06-30 sets the api-version, which is a required parameter on every request.
  • search=* 是查询字符串,此元素在初始查询中为 NULL,返回前 50 个结果(此为默认情况) 。search=* is the query string, which in the initial query is null, returning the first 50 results (by default).

发送自己的第一个查询Send your first query

进行验证,将以下请求粘贴至 GET 并单击“发送” 。As a verification step, paste the following request into GET and click Send. 结果以详细的 JSON 文档形式返回。Results are returned as verbose JSON documents. 将返回整个文档,这样就可以查看所有字段和所有值。Entire documents are returned, which allows you to see all fields and all values.

将此 URL 作为验证步骤粘贴到 REST 客户端中并查看文档结构。Paste this URL into a REST client as a validation step and to view document structure.


查询字符串 search=* 是一个未指定的搜索,它与 NULL 或空搜索等效 。The query string, search=*, is an unspecified search equivalent to null or empty search. 它的用处不大,但却是你能执行的最简单的搜索。It's not especially useful, but it is the simplest search you can do.

可选择将 $count=true 添加到 URL,以便返回一个符合搜索条件的文档的计数 。Optionally, you can add $count=true to the URL to return a count of the documents matching the search criteria. 在空搜索字符串上,这就是索引中的所有文档(在“纽约工作岗位”例子中,数量约为 2800)。On an empty search string, this is all the documents in the index (about 2800 in the case of NYC Jobs).

如何调用简单查询分析How to invoke simple query parsing

如果是交互式查询,无需指定任何内容:默认为简单查询。For interactive queries, you don't have to specify anything: simple is the default. 在代码中,如果之前调用过 queryType=full 以选择完整查询语法,可以使用 queryType=simple 重置默认值。In code, if you previously invoked queryType=full for full query syntax, you could reset the default with queryType=simple.

示例 1:字段范围查询Example 1: Field-scoped query

第一个示例并未特定于分析器,但我们将先使用它来介绍第一个基本查询概念,即“包含”。This first example is not parser-specific, but we lead with it to introduce the first fundamental query concept: containment. 本示例显示查询执行情况以及对几个特定字段的响应。This example scopes query execution and the response to just a few specific fields. 当你的工具是 Postman 或搜索资源管理器时,了解如何构建可读的 JSON 响应非常重要。Knowing how to structure a readable JSON response is important when your tool is Postman or Search explorer.

出于简洁目的,该查询仅针对 business_title 字段并指定仅返回职位 。For brevity, the query targets only the business_title field and specifies only business titles are returned. 语法是 searchFields 和 select,前者将查询执行限制为只执行 business_title 字段,后者指定响应中包含哪些字段 。The syntax is searchFields to restrict query execution to just the business_title field, and select to specify which fields are included in the response.

部分查询字符串Partial query string


下面是同一查询,在逗号分隔列表中具有多个字段。Here is the same query with multiple fields in a comma-delimited list.

search=*&searchFields=business_title, posting_type&$select=business_title, posting_type

完整 URLFull URL


此查询的响应应与以下屏幕截图类似。Response for this query should look similar to the following screenshot.

Postman 示例响应

你可能已经注意到响应中的搜索分数。You might have noticed the search score in the response. 由于搜索不是全文搜索或者没有应用条件,因此不存在排名时评分统统为 1。Uniform scores of 1 occur when there is no rank, either because the search was not full text search, or because no criteria was applied. 对于不带条件的空搜索,按任意顺序返回行。For null search with no criteria, rows come back in arbitrary order. 包括实际条件时,能看到搜索分数变成有意义的值。When you include actual criteria, you will see search scores evolve into meaningful values.

示例 2:按 ID 查找Example 2: Look up by ID

本示例不太典型,但在评估搜索行为时,可以检查特定文档的整个内容,以理解它为何包含或不包含在结果中。This example is a bit atypical, but when evaluating search behaviors, you might want to inspect the entire contents of a specific document to understand why it was included or excluded from results. 若要返回整个文档,请使用查找操作传入文档 ID。To return a single document in its entirety, use a Lookup operation to pass in the document ID.

所有文档都有一个唯一标识符。All documents have a unique identifier. 要在查找查询中试用此语法,请先返回一个文档 ID 列表,以便找到要使用的文档。To try out the syntax for a lookup query, first return a list of document IDs so that you can find one to use. 对于纽约工作岗位,标识符存储在 id 字段中。For NYC Jobs, the identifiers are stored in the id field.


下面的示例是基于 id“9E1E3AF9-0660-4E00-AF51-9B654925A2D5”返回特定文档的查找查询,最早出现在前面的响应中。The next example is a lookup query returning a specific document based on id "9E1E3AF9-0660-4E00-AF51-9B654925A2D5", which appeared first in the previous response. 以下查询返回整个文档,而不仅是所选字段。The following query returns the entire document, not just selected fields.


示例 3:筛选器查询Example 3: Filter queries

筛选器语法是可以配合 search 使用或单独使用的 OData 表达式。Filter syntax is an OData expression that you can use with search or by itself. 如果筛选表达式能够完全限定所需的文档,则不带 search 参数的单独筛选器很有用。A standalone filter, without a search parameter, is useful when the filter expression is able to fully qualify documents of interest. 不使用查询字符串也就不会执行词法或语言分析、评分(所有评分为 1)和排名。Without a query string, there is no lexical or linguistic analysis, no scoring (all scores are 1), and no ranking. 请注意,搜索字符串为空。Notice the search string is empty.

POST /indexes/nycjobs/docs/search?api-version=2020-06-30
      "search": "",
      "filter": "salary_frequency eq 'Annual' and salary_range_from gt 90000",
      "select": "job_id, business_title, agency, salary_range_from",
      "count": "true"

如果一起使用,则会先对整个索引应用 filter,再对筛选结果执行 search。Used together, the filter is applied first to the entire index, and then the search is performed on the results of the filter. filter 可减少 search 查询需要处理的文档集,因此是一种非常有用的技术,可用于提高查询性能。Filters can therefore be a useful technique to improve query performance since they reduce the set of documents that the search query needs to process.


若要使用 GET 在 Postman 中尝试此查询,可以粘贴以下字符串:If you want to try this out in Postman using GET, you can paste in this string:

https://azs-playground.search.azure.cn/indexes/nycjobs/docs?api-version=2020-06-30&$count=true&$select=job_id,business_title,agency,salary_range_from&search=&$filter=salary_frequency eq 'Annual' and salary_range_from gt 90000

另一种合并筛选器和搜索的有效方法是通过筛选表达式中的 search.ismatch*() ,在其中可以使用筛选器中的搜索查询。Another powerful way to combine filter and search is through search.ismatch*() in a filter expression, where you can use a search query within the filter. 此筛选表达式使用计划中的通配符来选择包含字词 plan、planner、planning 等的 business_title。 This filter expression uses a wildcard on plan to select business_title including the term plan, planner, planning, and so forth.

https://azs-playground.search.azure.cn/indexes/nycjobs/docs?api-version=2020-06-30&$count=true&$select=job_id,business_title,agency&search=&$filter=search.ismatch('plan*', 'business_title', 'full', 'any')

有关该函数的详细信息,请参阅“筛选器示例”中的 search.ismatchFor more information about the function, see search.ismatch in "Filter examples".

示例 4:范围筛选器Example 4: Range filters

通过任何数据类型的 $filter 表达式支持范围筛选。Range filtering is supported through $filter expressions for any data type. 以下示例搜索数字和字符串字段。The following examples search over numeric and string fields.

数据类型在范围筛选器中很重要,当数字数据位于数字字段且字符串数据位于字符串字段中时效果最佳。Data types are important in range filters and work best when numeric data is in numeric fields, and string data in string fields. 由于 Azure 认知搜索中的数字字符串不可比较,因此字符串字段中的数字数据不适用于范围。Numeric data in string fields is not suitable for ranges because numeric strings are not comparable in Azure Cognitive Search.

为方便阅读,以下示例采用 POST 格式(数字范围后接文本范围):The following examples are in POST format for readability (numeric range, followed by text range):

POST /indexes/nycjobs/docs/search?api-version=2020-06-30
      "search": "",
      "filter": "num_of_positions ge 5 and num_of_positions lt 10",
      "select": "job_id, business_title, num_of_positions, agency",
      "orderby": "agency",
      "count": "true"


POST /indexes/nycjobs/docs/search?api-version=2020-06-30
      "search": "",
      "filter": "business_title ge 'A*' and business_title lt 'C*'",
      "select": "job_id, business_title, agency",
      "orderby": "business_title",
      "count": "true"


也可以使用 GET 在 Postman 中尝试这些查询:You can also try these out in Postman using GET:

https://azs-playground.search.azure.cn/indexes/nycjobs/docs?api-version=2020-06-30&search=&$filter=num_of_positions ge 5 and num_of_positions lt 10&$select=job_id, business_title, num_of_positions, agency&$orderby=agency&$count=true
https://azs-playground.search.azure.cn/indexes/nycjobs/docs?api-version=2020-06-30&search=&$filter=business_title ge 'A*' and business_title lt 'C*'&$select=job_id, business_title, agency&$orderby=business_title&$count=true


基于值的范围分面是常见的搜索应用程序要求。Faceting over ranges of values is a common search application requirement. 有关为分面导航结构生成筛选器的详细信息和示例,请参阅 如何实现分面导航 中的“基于范围的筛选器”For more information and examples on building filters for facet navigation structures, see "Filter based on a range" in How to implement faceted navigation.

示例索引包含带有纬度和经度坐标的 geo_location 字段。The sample index includes a geo_location field with latitude and longitude coordinates. 此示例使用 geo.distance 函数来筛选从起点开始,直到所提供的任意距离(以公里为单位)圆周范围内的文档。This example uses the geo.distance function that filters on documents within the circumference of a starting point, out to an arbitrary distance (in kilometers) that you provide. 可以调整查询 (4) 中的最后一个值,以缩小或放大查询的表面积。You can adjust the last value in the query (4) to reduce or enlarge the surface area of the query.

为方便阅读,以下示例采用 POST 格式:The following example is in POST format for readability:

POST /indexes/nycjobs/docs/search?api-version=2020-06-30
      "search": "",
      "filter": "geo.distance(geo_location, geography'POINT(-74.11734 40.634384)') le 4",
      "select": "job_id, business_title, work_location",
      "count": "true"

为方便阅读结果,搜索结果已剪裁,只包含职位 ID、职务和工位。For more readable results, search results are trimmed to include a job ID, job title, and the work location. 起始坐标是从索引中的随机文档(在本例中,为斯塔顿岛上的某个工位)获取的。The starting coordinates were obtained from a random document in the index (in this case, for a work location on Staten island.

也可以使用 GET 在 Postman 中尝试此查询:You can also try this out in Postman using GET:

https://azs-playground.search.azure.cn/indexes/nycjobs/docs?api-version=2020-06-30&$count=true&search=&$select=job_id, business_title, work_location&$filter=geo.distance(geo_location, geography'POINT(-74.11734 40.634384)') le 4

示例 6:搜索精度Example 6: Search precision

字词查询是独立评估的单个字词(可能很多是这样)。Term queries are single terms, perhaps many of them, that are evaluated independently. 短语查询用引号括起来,作为逐字字符串进行评估。Phrase queries are enclosed in quotation marks and evaluated as a verbatim string. 匹配精度由运算符和 searchMode 控制。Precision of the match is controlled by operators and searchMode.

示例 1:&search=fire 返回 150 个结果,即整个文档中包含“fire”一词的所有匹配项 。Example 1: &search=fire returns 150 results, where all matches contain the word fire somewhere in the document.


示例 2:&search=fire department 返回 2002 个结果 。Example 2: &search=fire department returns 2002 results. 针对此文档返回了包含“fire”或“department”的匹配项。Matches are returned for documents containing either fire or department.

https://azs-playground.search.azure.cn/indexes/nycjobs/docs?api-version=2020-06-30&$count=true&search=fire department

示例 3:&search="fire department" 返回 82 个结果 。Example 3: &search="fire department" returns 82 results. 将该字符串用引号引起来,构成对这两个词的逐字搜索,在索引中包含该组合词的已标记化的字词中查找匹配项。Enclosing the string in quotation marks is a verbatim search on both terms, and matches are found on tokenized terms in the index consisting of the combined terms. 这就解释了为何诸如 search=+fire +department 之类的搜索是不等效的 。This explains why a search like search=+fire +department is not equivalent. 需具备两个字词,但独立扫描它们。Both terms are required, but are scanned for independently.

https://azs-playground.search.azure.cn/indexes/nycjobs/docs?api-version=2020-06-30&$count=true&search="fire department"

示例 7:使用 searchMode 的布尔值Example 7: Booleans with searchMode

简单语法支持字符形式的布尔运算符 (+, -, |) 。Simple syntax supports boolean operators in the form of characters (+, -, |). searchMode 参数用于在精准率和召回率之间做出权衡,其中 searchMode=any 倾向于召回率(符合任何条件的文档都能进入结果集),而 searchMode=all 倾向于精准率(符合所有条件的文档才能进入结果集)。The searchMode parameter informs tradeoffs between precision and recall, with searchMode=any favoring recall (matching on any criteria qualifies a document for the result set), and searchMode=all favoring precision (all criteria must be matched). 默认为 searchMode=any;在使用多个运算符堆叠查询并获取更广泛而不是更窄的结果时,这可能会产生混淆。The default is searchMode=any, which can be confusing if you are stacking a query with multiple operators and getting broader instead of narrower results. 在使用 NOT 时尤为如此,该运算符导致结果包括所有“不含”特定字词的文档。This is particularly true with NOT, where results include all documents "not containing" a specific term.

使用默认的 searchMode (any) 时,返回了 2800 个文档:其中有包含多部分字词“fire department”的文档,以及所有不带有字词“Metrotech Center”的文档。Using the default searchMode (any), 2800 documents are returned: those containing the multi-part term "fire department", plus all documents that do not have the term "Metrotech Center".

https://azs-playground.search.azure.cn/indexes/nycjobs/docs?api-version=2020-06-30&$count=true&searchMode=any&search="fire department"  -"Metrotech Center"

搜索模式 - any

若将 searchMode 更改为 all,会强制累积条件并返回一个较小的结果集,它只有 21 个文档,其文档数是包含完整短语“fire department”的文档减去 Metrotech Center 工作岗位数之差。Changing searchMode to all enforces a cumulative effect on criteria and returns a smaller result set - 21 documents - consisting of documents containing the entire phrase "fire department", minus those jobs at the Metrotech Center address.

https://azs-playground.search.azure.cn/indexes/nycjobs/docs?api-version=2020-06-30&$count=true&searchMode=all&search="fire department"  -"Metrotech Center"

搜索模式 - all

示例 8:构建结果Example 8: Structuring results

有多个参数控制着搜索结果中包括哪些字段、每批返回多少文档以及排列顺序。Several parameters control which fields are in the search results, the number of documents returned in each batch, and sort order. 此示例重新设置了上述几个示例,使用 $select 语句和逐字搜索条件将结果限制为仅包含特定字段,返回了 82 个匹配项 This example resurfaces a few of the previous examples, limiting results to specific fields using the $select statement and verbatim search criteria, returning 82 matches

https://azs-playground.search.azure.cn/indexes/nycjobs/docs?api-version=2020-06-30&$count=true&$select=job_id,agency,business_title,civil_service_title,work_location,job_description&search="fire department"

将此改动追加到上一示例,即可按职位排序。Appended onto the previous example, you can sort by title. 这种排序是可行的,因为在该索引中 civil_service_title 是可排序的 。This sort works because civil_service_title is sortable in the index.

https://azs-playground.search.azure.cn/indexes/nycjobs/docs?api-version=2020-06-30&$count=true&$select=job_id,agency,business_title,civil_service_title,work_location,job_description&search="fire department"&$orderby=civil_service_title

使用 $top 参数可实现结果分页,本例中返回了前 5 个文档 :Paging results is implemented using the $top parameter, in this case returning the top 5 documents:

https://azs-playground.search.azure.cn/indexes/nycjobs/docs?api-version=2020-06-30&$count=true&$select=job_id,agency,business_title,civil_service_title,work_location,job_description&search="fire department"&$orderby=civil_service_title&$top=5&$skip=0

要获取后续 5 个文档,请跳过第一批:To get the next 5, skip the first batch:

https://azs-playground.search.azure.cn/indexes/nycjobs/docs?api-version=2020-06-30&$count=true&$select=job_id,agency,business_title,civil_service_title,work_location,job_description&search="fire department"&$orderby=civil_service_title&$top=5&$skip=5

后续步骤Next steps

尝试在代码中指定查询。Try specifying queries in your code. 以下链接介绍如何使用默认的简单语法为 .NET 和 REST API 设置搜索查询。The following links explain how to set up search queries for both .NET and the REST API using the default simple syntax.

可在以下链接找到其他语法参考、查询体系结构和示例:Additional syntax reference, query architecture, and examples can be found in the following links: