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

Documents - Suggest Post

建议索引中的文档与给定的部分查询文本匹配。

POST {endpoint}/indexes('{indexName}')/docs/search.post.suggest?api-version=2024-07-01

URI 参数

名称 必需 类型 说明
endpoint
path True

string

搜索服务的终结点 URL。

indexName
path True

string

索引的名称。

api-version
query True

string

客户端 API 版本。

请求头

名称 必需 类型 说明
x-ms-client-request-id

string

uuid

随请求一起发送的跟踪 ID,以帮助进行调试。

请求正文

名称 必需 类型 说明
search True

string

用于建议文档的搜索文本。 必须至少为 1 个字符,且不超过 100 个字符。

suggesterName True

string

作为索引定义的一部分的建议器集合中指定的建议器的名称。

filter

string

一个 OData 表达式,用于筛选针对建议考虑的文档。

fuzzy

boolean

一个值,该值指示是否对建议查询使用模糊匹配。 默认值为 false。 如果设置为 true,查询将查找建议,即使搜索文本中有替换字符或缺失字符。 尽管在某些方案中提供了更好的体验,但由于模糊建议搜索速度较慢且消耗更多资源,因此会降低性能成本。

highlightPostTag

string

追加到命中突出显示的字符串标记。 必须使用 highlightPreTag 进行设置。 如果省略,将禁用突出显示建议。

highlightPreTag

string

前面追加的字符串标记以命中突出显示。 必须使用 highlightPostTag 进行设置。 如果省略,将禁用突出显示建议。

minimumCoverage

number

介于 0 和 100 之间的数字,指示建议查询必须涵盖的索引百分比,以便将查询报告为成功。 此参数可用于确保仅包含一个副本的服务的搜索可用性。 默认值为 80。

orderby

string

OData 的逗号分隔列表$orderby用于对结果进行排序的表达式。 每个表达式可以是字段名称,也可以是对 geo.distance() 或 search.score() 函数的调用。 每个表达式后跟 asc 以指示升序,或 desc 表示降序。 默认值为升序。 关系将由匹配文档的分数中断。 如果未指定$orderby,则默认排序顺序按文档匹配分数降序。 最多可以有 32 个$orderby子句。

searchFields

string

要搜索指定搜索文本的字段名称的逗号分隔列表。 目标字段必须包含在指定的建议器中。

select

string

要检索的字段的逗号分隔列表。 如果未指定,则只会在结果中包含键字段。

top

integer

要检索的建议数。 此值必须是介于 1 和 100 之间的值。 默认值为 5。

响应

名称 类型 说明
200 OK

SuggestDocumentsResult

包含与部分输入匹配的建议文档的响应。

Other Status Codes

ErrorResponse

错误响应。

示例

SearchIndexSuggestDocumentsPost

示例请求

POST https://myservice.search.windows.net/indexes('myindex')/docs/search.post.suggest?api-version=2024-07-01

{
  "filter": "rating gt 4.0",
  "highlightPostTag": "</em>",
  "highlightPreTag": "<em>",
  "minimumCoverage": 80,
  "orderby": "rating desc",
  "search": "hote",
  "searchFields": "title",
  "select": "docId,title,description",
  "suggesterName": "sg",
  "top": 10
}

示例响应

{
  "value": [
    {
      "@search.text": "Nice <em>Hotel</em>",
      "description": "Cheapest hotel in town",
      "docId": "1",
      "title": "Nice Hotel"
    },
    {
      "@search.text": "Fancy <em>Hotel</em>",
      "description": "Best hotel in town",
      "docId": "2",
      "title": "Fancy Hotel"
    }
  ]
}

定义

名称 说明
ErrorAdditionalInfo

资源管理错误附加信息。

ErrorDetail

错误详细信息。

ErrorResponse

错误响应

SuggestDocumentsResult

包含来自索引的建议查询结果的响应。

SuggestRequest

用于筛选、排序、模糊匹配和其他建议查询行为的参数。

SuggestResult

包含由建议查询找到的文档的结果,以及关联的元数据。

ErrorAdditionalInfo

资源管理错误附加信息。

名称 类型 说明
info

object

其他信息。

type

string

其他信息类型。

ErrorDetail

错误详细信息。

名称 类型 说明
additionalInfo

ErrorAdditionalInfo[]

错误附加信息。

code

string

错误代码。

details

ErrorDetail[]

错误详细信息。

message

string

错误消息。

target

string

错误目标。

ErrorResponse

错误响应

名称 类型 说明
error

ErrorDetail

错误对象。

SuggestDocumentsResult

包含来自索引的建议查询结果的响应。

名称 类型 说明
@search.coverage

number

一个值,该值指示查询中包含的索引百分比;如果未在请求中设置 minimumCoverage,则为 null。

value

SuggestResult[]

查询返回的结果序列。

SuggestRequest

用于筛选、排序、模糊匹配和其他建议查询行为的参数。

名称 类型 说明
filter

string

一个 OData 表达式,用于筛选针对建议考虑的文档。

fuzzy

boolean

一个值,该值指示是否对建议查询使用模糊匹配。 默认值为 false。 如果设置为 true,查询将查找建议,即使搜索文本中有替换字符或缺失字符。 尽管在某些方案中提供了更好的体验,但由于模糊建议搜索速度较慢且消耗更多资源,因此会降低性能成本。

highlightPostTag

string

追加到命中突出显示的字符串标记。 必须使用 highlightPreTag 进行设置。 如果省略,将禁用突出显示建议。

highlightPreTag

string

前面追加的字符串标记以命中突出显示。 必须使用 highlightPostTag 进行设置。 如果省略,将禁用突出显示建议。

minimumCoverage

number

介于 0 和 100 之间的数字,指示建议查询必须涵盖的索引百分比,以便将查询报告为成功。 此参数可用于确保仅包含一个副本的服务的搜索可用性。 默认值为 80。

orderby

string

OData 的逗号分隔列表$orderby用于对结果进行排序的表达式。 每个表达式可以是字段名称,也可以是对 geo.distance() 或 search.score() 函数的调用。 每个表达式后跟 asc 以指示升序,或 desc 表示降序。 默认值为升序。 关系将由匹配文档的分数中断。 如果未指定$orderby,则默认排序顺序按文档匹配分数降序。 最多可以有 32 个$orderby子句。

search

string

用于建议文档的搜索文本。 必须至少为 1 个字符,且不超过 100 个字符。

searchFields

string

要搜索指定搜索文本的字段名称的逗号分隔列表。 目标字段必须包含在指定的建议器中。

select

string

要检索的字段的逗号分隔列表。 如果未指定,则只会在结果中包含键字段。

suggesterName

string

作为索引定义的一部分的建议器集合中指定的建议器的名称。

top

integer

要检索的建议数。 此值必须是介于 1 和 100 之间的值。 默认值为 5。

SuggestResult

包含由建议查询找到的文档的结果,以及关联的元数据。

名称 类型 说明
@search.text

string

建议结果的文本。