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

Documents - Search Get

在索引中搜索文档。

GET {endpoint}/indexes('{indexName}')/docs?api-version=2023-11-01
GET {endpoint}/indexes('{indexName}')/docs?search={search}&$count={$count}&facet={facet}&$filter={$filter}&highlight={highlight}&highlightPostTag={highlightPostTag}&highlightPreTag={highlightPreTag}&minimumCoverage={minimumCoverage}&$orderby={$orderby}&queryType={queryType}&scoringParameter={scoringParameter}&scoringProfile={scoringProfile}&searchFields={searchFields}&searchMode={searchMode}&scoringStatistics={scoringStatistics}&sessionId={sessionId}&$select={$select}&$skip={$skip}&$top={$top}&api-version=2023-11-01&semanticConfiguration={semanticConfiguration}&semanticErrorHandling={semanticErrorHandling}&semanticMaxWaitInMilliseconds={semanticMaxWaitInMilliseconds}&answers={answers}&captions={captions}

URI 参数

名称 必需 类型 说明
endpoint
path True

string

搜索服务的终结点 URL。

indexName
path True

string

索引的名称。

api-version
query True

string

客户端 API 版本。

$count
query

boolean

一个 值,该值指定是否提取结果的总计数。 默认值为 false。 将此值设置为 true 可能会影响性能。 请注意,返回的计数是一个近似值。

$filter
query

string

要应用于搜索查询的 OData $filter表达式。

$orderby
query

string[]

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

$select
query

string[]

要检索的字段列表。 如果未指定,将包含架构中标记为可检索的所有字段。

$skip
query

integer

int32

要跳过的搜索结果数。 此值不能大于 100,000。 如果需要按顺序扫描文档,但由于此限制而无法使用$skip,请考虑对完全有序的键使用$orderby,并改为使用范围查询$filter。

$top
query

integer

int32

要检索的搜索结果数。 这可以与 $skip 结合使用,以实现搜索结果的客户端分页。 如果结果由于服务器端分页而被截断,则响应将包含一个继续标记,该令牌可用于针对下一页结果发出另一个搜索请求。

answers
query

QueryAnswerType

仅当查询类型为 semantic时,此参数才有效。 如果设置,查询将返回从排名最高的文档中的关键段落中提取的答案。 可以通过在 answers 参数值后面追加管道字符 | 后跟 count-<number of answers> 选项来配置返回的答案数,例如 extractive|count-3。 默认计数为 1。 可以通过在 answers 参数值后面追加管道字符 |threshold-<confidence threshold> 跟 选项来配置置信度阈值,例如 extractive|threshold-0.9。 默认阈值为 0.7。

captions
query

QueryCaptionType

仅当查询类型为 semantic时,此参数才有效。 如果设置,查询将返回从排名最高的文档中的关键段落中提取的标题。 当 Captions 设置为 extractive时,默认情况下会启用突出显示,并且可以通过追加管道字符 | 后跟 highlight-<true/false> 选项(例如 extractive|highlight-true)来配置。 默认为 None

facet
query

string[]

要应用于搜索查询的分面表达式的列表。 每个分面表达式都包含一个字段名称,可以选择后跟逗号分隔的 name:value 对列表。

highlight
query

string[]

要用于命中突出显示的字段名称列表。 仅可搜索字段可用于突出显示命中。

highlightPostTag
query

string

追加到命中突出显示的字符串标记。 必须使用 highlightPreTag 进行设置。 默认值为 </em>。

highlightPreTag
query

string

一个字符串标记,在前面追加到命中突出显示。 必须使用 highlightPostTag 进行设置。 默认值为 <em>。

minimumCoverage
query

number

double

一个介于 0 和 100 之间的数字,指示搜索查询必须涵盖的索引百分比,以便将查询报告为成功。 即使只有一个副本 (replica) 的服务,此参数也可用于确保搜索可用性。 默认值为 100。

queryType
query

QueryType

一个 值,该值指定搜索查询的语法。 默认值为“simple”。 如果查询使用 Lucene 查询语法,请使用“full”。

scoringParameter
query

string[]

评分函数中使用的参数值列表 (例如,使用格式 name-values 的 referencePointParameter) 。 例如,如果评分配置文件定义了一个名为“mylocation”的参数的函数,则参数字符串将为“mylocation--122.2,44.8” (不带引号) 。

scoringProfile
query

string

用于为匹配的文档评估匹配分数以便对结果进行排序的评分配置文件的名称。

scoringStatistics
query

ScoringStatistics

一个 值,该值指定我们是要计算评分统计信息 (,例如全局) 文档频率,以便获得更一致的评分,还是在本地计算以降低延迟。

search
query

string

全文搜索查询表达式;使用“*”或省略此参数以匹配所有文档。

searchFields
query

string[]

将全文搜索范围限定为的字段名称列表。 在完整的 Lucene 查询中使用字段搜索 (fieldName:searchExpression) 时,每个字段搜索表达式的字段名称优先于此参数中列出的任何字段名称。

searchMode
query

SearchMode

一个 值,该值指定是否必须匹配任何或所有搜索词才能将文档计数为匹配项。

semanticConfiguration
query

string

语义配置的名称,其中列出了哪些字段应用于语义排名、标题、突出显示和答案

semanticErrorHandling
query

SemanticErrorMode

允许用户选择语义调用应完全失败还是返回部分结果。

semanticMaxWaitInMilliseconds
query

integer

int32

允许用户设置语义扩充在请求失败之前完成处理所需的时间上限。

sessionId
query

string

一个值,用于创建粘滞会话,这有助于获得更一致的结果。 只要使用相同的 sessionId,就会尽力尝试以相同的副本 (replica) 集为目标。 请注意,重复重复使用相同的 sessionID 值可能会干扰跨副本的请求负载均衡,并会对搜索服务的性能产生不利影响。 用作 sessionId 的值不能以“_”字符开头。

请求头

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

string

uuid

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

响应

名称 类型 说明
200 OK

SearchDocumentsResult

包含与搜索条件匹配的文档的响应。

Other Status Codes

SearchError

错误响应。

示例

SearchIndexSearchDocumentsGet
SearchIndexSearchDocumentsSemanticGet

SearchIndexSearchDocumentsGet

Sample Request

GET https://myservice.search.windows.net/indexes('myindex')/docs?search=nice hotels&$count=True&facet=category,count:10,sort:count&$filter=rating gt 10&highlight=title&highlightPostTag=</em>&highlightPreTag=<em>&minimumCoverage=80&$orderby=search.score() desc,rating desc&queryType=simple&scoringProfile=sp&searchFields=title,description&searchMode=any&scoringStatistics=global&sessionId=mysessionid&$select=docId,title,description&$skip=100&$top=10&api-version=2023-11-01

Sample Response

{
  "@odata.count": 25,
  "@search.coverage": 80,
  "@search.facets": {
    "category": [
      {
        "count": 1,
        "value": "Economy"
      },
      {
        "count": 1,
        "value": "Luxury"
      }
    ]
  },
  "value": [
    {
      "@search.score": 1.5,
      "@search.highlights": {
        "title": [
          "<em>Nice</em> <em>Hotel</em>"
        ]
      },
      "description": "Cheapest hotel in town",
      "docId": "1",
      "title": "Nice Hotel"
    },
    {
      "@search.score": 0.7,
      "@search.highlights": {
        "title": [
          "Fancy <em>Hotel</em>"
        ]
      },
      "description": "Best hotel in town",
      "docId": "2",
      "title": "Fancy Hotel"
    }
  ]
}

SearchIndexSearchDocumentsSemanticGet

Sample Request

GET https://myservice.search.windows.net/indexes('myindex')/docs?search=how do clouds form&$count=True&highlightPostTag=</em>&highlightPreTag=<em>&queryType=semantic&api-version=2023-11-01&semanticConfiguration=my-semantic-config&semanticErrorHandling=partial&semanticMaxWaitInMilliseconds=780&answers=extractive|count-3&captions=extractive|highlight-true

Sample Response

{
  "@odata.count": 25,
  "@search.answers": [
    {
      "key": "4123",
      "text": "Sunlight heats the land all day, warming that moist air and causing it to rise high into the   atmosphere until it cools and condenses into water droplets. Clouds generally form where air is ascending (over land in this case),   but not where it is descending (over the river).",
      "highlights": "Sunlight heats the land all day, warming that moist air and causing it to rise high into the   atmosphere until it cools and condenses into water droplets. Clouds generally form<em> where air is ascending</em> (over land in this case),   but not where it is<em> descending</em> (over the river).",
      "score": 0.94639826
    }
  ],
  "value": [
    {
      "@search.score": 0.5479723,
      "@search.rerankerScore": 1.0321671911515296,
      "@search.captions": [
        {
          "text": "Like all clouds, it forms when the air reaches its dew point—the temperature at which an air mass is cool enough for its water vapor to condense into liquid droplets. This false-color image shows valley fog, which is common in the Pacific Northwest of North America.",
          "highlights": "Like all<em> clouds</em>, it<em> forms</em> when the air reaches its dew point—the temperature at    which an air mass is cool enough for its water vapor to condense into liquid droplets. This false-color image shows valley<em> fog</em>, which is common in the Pacific Northwest of North America."
        }
      ],
      "id": "4123",
      "title": "Earth Atmosphere",
      "content": "Fog is essentially a cloud lying on the ground. Like all clouds, it forms when the air reaches its dew point—the temperature at  \n\nwhich an air mass is cool enough for its water vapor to condense into liquid droplets.\n\nThis false-color image shows valley fog, which is common in the Pacific Northwest of North America. On clear winter nights, the \n\nground and overlying air cool off rapidly, especially at high elevations. Cold air is denser than warm air, and it sinks down into the \n\nvalleys. The moist air in the valleys gets chilled to its dew point, and fog forms. If undisturbed by winds, such fog may persist for \n\ndays. The Terra satellite captured this image of foggy valleys northeast of Vancouver in February 2010.\n\n\n",
      "locations": [
        "Pacific Northwest",
        "North America",
        "Vancouver"
      ]
    }
  ]
}

定义

名称 说明
AnswerResult

答案是从与查询匹配的最相关文档的内容中提取的文本段落。 从顶部搜索结果中提取答案。 对考生的答案进行评分,并选择排名靠前的答案。

CaptionResult

标题是相对于搜索查询而言,文档中最具代表性的段落。 它们通常用作文档摘要。 仅为 类型的 semantic查询返回标题。

QueryAnswerType

一个 值,该值指定是否应作为搜索响应的一部分返回答案。

QueryCaptionType

一个 值,该值指定是否应将字幕作为搜索响应的一部分返回。

QueryType

指定搜索查询的语法。 默认值为“simple”。 如果查询使用 Lucene 查询语法,请使用“full”。

RawVectorQuery

提供原始矢量值时用于矢量搜索的查询参数。

ScoringStatistics

一个 值,该值指定我们是要计算评分统计信息 ((例如全局) 文档频率)以提高评分的一致性,还是在本地计算以降低延迟。 默认值为“local”。 在评分之前,使用“global”聚合全局评分统计信息。 使用全局评分统计信息会增加搜索查询的延迟。

SearchDocumentsResult

包含索引中搜索结果的响应。

SearchError

描述 API 的错误条件。

SearchMode

指定要将文档算作匹配项,是必须匹配任一搜索词还是必须匹配所有搜索词。

SearchRequest

用于筛选、排序、分面、分页和其他搜索查询行为的参数。

SearchResult

包含搜索查询找到的文档以及关联的元数据。

SemanticErrorMode

允许用户选择语义调用应完全失败 (默认/当前行为) ,还是返回部分结果。

SemanticErrorReason

为语义排名请求返回部分响应的原因。

SemanticSearchResultsType

为语义排名请求返回的部分响应的类型。

VectorFilterMode

确定在执行矢量搜索之前还是之后应用筛选器。

VectorQueryKind

正在执行的向量查询的类型。

AnswerResult

答案是从与查询匹配的最相关文档的内容中提取的文本段落。 从顶部搜索结果中提取答案。 对考生的答案进行评分,并选择排名靠前的答案。

名称 类型 说明
highlights

string

与 Text 属性中的文本段落相同,突出显示了与查询最相关的文本短语。

key

string

从中提取答案的文档的密钥。

score

number

分数值表示答案与查询相对于为查询返回的其他答案的相关性。

text

string

从文档内容中提取的文本段落作为答案。

CaptionResult

标题是相对于搜索查询而言,文档中最具代表性的段落。 它们通常用作文档摘要。 仅为 类型的 semantic查询返回标题。

名称 类型 说明
highlights

string

与 Text 属性中的文本段落相同,其中突出显示了与查询最相关的短语。

text

string

从与搜索查询最相关的文档中提取的代表性文本段落。

QueryAnswerType

一个 值,该值指定是否应作为搜索响应的一部分返回答案。

名称 类型 说明
extractive

string

从响应以自然语言表示为问题的查询而返回的文档内容中提取答案候选项。

none

string

不要返回查询的答案。

QueryCaptionType

一个 值,该值指定是否应将字幕作为搜索响应的一部分返回。

名称 类型 说明
extractive

string

从包含与搜索查询相关的段落的匹配文档中提取标题。

none

string

不要返回查询的标题。

QueryType

指定搜索查询的语法。 默认值为“simple”。 如果查询使用 Lucene 查询语法,请使用“full”。

名称 类型 说明
full

string

使用完整的 Lucene 查询语法进行搜索。 搜索文本使用 Lucene 查询语言进行解释,该语言允许字段特定和加权搜索以及其他高级功能。

semantic

string

最适合用自然语言而不是关键字表示的查询。 通过使用在 Web 料料库上训练的排名模型重新排名排名靠前的搜索结果,提高搜索结果的精度。

simple

string

使用简单的查询语法进行搜索。 搜索文本使用一种简单的查询语言进行解释,该语言允许使用诸如 +、* 和“”等符号。 默认情况下,查询将跨所有可搜索字段进行评估,除非指定了 searchFields 参数。

RawVectorQuery

提供原始矢量值时用于矢量搜索的查询参数。

名称 类型 说明
exhaustive

boolean

如果为 true,则对向量索引中的所有向量触发一个详尽的 k 最近邻搜索。 适用于精确匹配至关重要的方案,例如确定基本真实值。

fields

string

集合 (Edm.Single 类型的向量字段) 包含在搜索的矢量中。

k

integer

要作为热门命中数返回的最近邻居的数目。

kind string:

vector

正在执行的向量查询的类型。

vector

number[]

搜索查询的向量表示形式。

ScoringStatistics

一个 值,该值指定我们是要计算评分统计信息 ((例如全局) 文档频率)以提高评分的一致性,还是在本地计算以降低延迟。 默认值为“local”。 在评分之前,使用“global”聚合全局评分统计信息。 使用全局评分统计信息会增加搜索查询的延迟。

名称 类型 说明
global

string

将全局计算评分统计信息,以便获得更一致的评分。

local

string

评分统计信息将在本地计算,以降低延迟。

SearchDocumentsResult

包含索引中搜索结果的响应。

名称 类型 说明
@odata.count

integer

搜索操作找到的结果总数;如果未请求计数,则为 null。 如果存在,计数可能大于此响应中的结果数。 如果使用$top或$skip参数,或者查询无法在单个响应中返回所有请求的文档,则可能会发生这种情况。

@odata.nextLink

string

当查询无法在单个响应中返回所有请求的结果时返回的延续 URL。 可以使用此 URL 来构建另一个 GET 或 POST 搜索请求,以获取搜索响应的下一部分。 请确保使用与生成此响应的请求相同的谓词 (GET 或 POST) 。

@search.answers

AnswerResult[]

搜索操作的答案查询结果;如果未指定 answers 查询参数或设置为“none”,则为 null。

@search.coverage

number

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

@search.facets

object

搜索操作的 facet 查询结果,组织为每个分面字段的存储桶集合;如果查询不包含任何分面表达式,则为 null。

@search.nextPageParameters

SearchRequest

当查询无法在单个响应中返回所有请求的结果时返回的继续 JSON 有效负载。 可以将此 JSON 与 一起使用 @odata.nextLink 来制定另一个 POST 搜索请求,以获取搜索响应的下一部分。

@search.semanticPartialResponseReason

SemanticErrorReason

为语义排名请求返回部分响应的原因。

@search.semanticPartialResponseType

SemanticSearchResultsType

为语义排名请求返回的部分响应的类型。

value

SearchResult[]

查询返回的结果序列。

SearchError

描述 API 的错误条件。

名称 类型 说明
code

string

服务器定义的一组错误代码中的一个。

details

SearchError[]

有关导致此项报告错误的特定错误的详细信息数组。

message

string

错误的用户可读表示形式。

SearchMode

指定要将文档算作匹配项,是必须匹配任一搜索词还是必须匹配所有搜索词。

名称 类型 说明
all

string

必须匹配所有搜索词,才能将文档计数为匹配项。

any

string

必须匹配任何搜索词,才能将文档计数为匹配项。

SearchRequest

用于筛选、排序、分面、分页和其他搜索查询行为的参数。

名称 类型 说明
answers

QueryAnswerType

一个 值,该值指定是否应作为搜索响应的一部分返回答案。

captions

QueryCaptionType

一个 值,该值指定是否应将标题作为搜索响应的一部分返回。

count

boolean

一个 值,该值指定是否提取结果的总计数。 默认值为 false。 将此值设置为 true 可能会影响性能。 请注意,返回的计数是一个近似值。

facets

string[]

要应用于搜索查询的分面表达式的列表。 每个分面表达式都包含一个字段名称,后跟一个逗号分隔的 name:value 对列表。

filter

string

要应用于搜索查询的 OData $filter表达式。

highlight

string

用于命中突出显示的字段名称的逗号分隔列表。 仅可搜索字段可用于命中突出显示。

highlightPostTag

string

追加到命中突出显示的字符串标记。 必须使用 highlightPreTag 进行设置。 默认值为 </em>。

highlightPreTag

string

一个字符串标记,在前面附加以命中突出显示。 必须使用 highlightPostTag 进行设置。 默认值为 <em>。

minimumCoverage

number

介于 0 和 100 之间的数字,指示搜索查询必须涵盖的索引百分比才能将查询报告为成功。 此参数可用于确保搜索可用性,即使只有一个副本 (replica) 的服务也是如此。 默认值为 100。

orderby

string

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

queryType

QueryType

一个 值,该值指定搜索查询的语法。 默认值为“simple”。 如果查询使用 Lucene 查询语法,请使用“full”。

scoringParameters

string[]

要用于评分函数的参数值列表 (例如,referencePointParameter) 使用格式 name-values。 例如,如果评分配置文件定义了一个具有名为“mylocation”的参数的函数,则参数字符串将为“mylocation--122.2,44.8” (不带引号) 。

scoringProfile

string

用于为匹配的文档评估匹配分数以便对结果进行排序的评分配置文件的名称。

scoringStatistics

ScoringStatistics

一个 值,该值指定我们是要计算评分统计信息 ((例如全局) 文档频率)以提高评分的一致性,还是在本地计算以降低延迟。 默认值为“local”。 在评分之前,使用“global”聚合全局评分统计信息。 使用全局评分统计信息会增加搜索查询的延迟。

search

string

全文搜索查询表达式;使用“*”或省略此参数以匹配所有文档。

searchFields

string

要确定全文搜索的范围的字段名称的逗号分隔列表。 在完整的 Lucene 查询中使用字段搜索 (fieldName:searchExpression) 时,每个字段搜索表达式的字段名称优先于此参数中列出的任何字段名称。

searchMode

SearchMode

一个 值,该值指定是否必须匹配任何或所有搜索词才能将文档计数为匹配项。

select

string

要检索的字段的逗号分隔列表。 如果未指定,将包含架构中标记为可检索的所有字段。

semanticConfiguration

string

在处理语义类型查询的文档时将使用的语义配置的名称。

semanticErrorHandling

SemanticErrorMode

允许用户选择语义调用应完全失败 (默认/当前行为) ,还是返回部分结果。

semanticMaxWaitInMilliseconds

integer

允许用户设置语义扩充在请求失败之前完成处理所需的时间上限。

sessionId

string

一个值,用于创建粘滞会话,这有助于获得更一致的结果。 只要使用相同的 sessionId,就会尽力尝试以相同的副本 (replica) 集为目标。 请注意,重复重复使用相同的 sessionID 值可能会干扰跨副本的请求负载均衡,并会对搜索服务的性能产生负面影响。 用作 sessionId 的值不能以“_”字符开头。

skip

integer

要跳过的搜索结果数。 此值不能大于 100,000。 如果需要按顺序扫描文档,但由于此限制而无法使用 skip,请考虑对完全排序的键使用 orderby,并改为使用范围查询进行筛选。

top

integer

要检索的搜索结果数。 这可以与 $skip 结合使用,以实现搜索结果的客户端分页。 如果结果由于服务器端分页而被截断,则响应将包含一个继续标记,该令牌可用于针对下一页结果发出另一个搜索请求。

vectorFilterMode

VectorFilterMode

确定在执行矢量搜索之前还是之后应用筛选器。 对于新索引,默认值为“preFilter”。

vectorQueries VectorQuery[]:

RawVectorQuery[]

矢量和混合搜索查询的查询参数。

SearchResult

包含搜索查询找到的文档以及关联的元数据。

名称 类型 说明
@search.captions

CaptionResult[]

标题是相对于搜索查询而言,文档中最具代表性的段落。 它们通常用作文档摘要。 仅为 类型的 semantic查询返回标题。

@search.highlights

object

文档中指示匹配搜索词的文本片段,按每个适用字段组织;如果查询未启用命中突出显示,则为 null。

@search.rerankerScore

number

语义排名器为排名靠前的搜索结果计算的相关性分数。 搜索结果先按 RerankerScore 排序,然后按分数排序。 RerankerScore 仅返回类型 semantic为 的查询。

@search.score

number

与查询返回的其他文档相比,文档的相关性分数。

SemanticErrorMode

允许用户选择语义调用应完全失败 (默认/当前行为) ,还是返回部分结果。

名称 类型 说明
fail

string

如果在语义处理步骤期间出现异常,则查询将失败并返回相应的 HTTP 代码,具体取决于错误。

partial

string

如果语义处理失败,仍返回部分结果。 部分结果的定义取决于失败的语义步骤以及失败的原因。

SemanticErrorReason

为语义排名请求返回部分响应的原因。

名称 类型 说明
capacityOverloaded

string

请求被限制。 仅返回基本结果。

maxWaitExceeded

string

如果 semanticMaxWaitInMilliseconds 设置了 ,并且语义处理持续时间超过了该值。 仅返回基本结果。

transient

string

语义过程至少有一个步骤失败。

SemanticSearchResultsType

为语义排名请求返回的部分响应的类型。

名称 类型 说明
baseResults

string

没有任何语义扩充或重新进行的结果。

rerankedResults

string

结果已使用重排器模型重新进行,并将包含语义标题。 它们不包括任何答案、答案要点或描述文字要点。

VectorFilterMode

确定在执行矢量搜索之前还是之后应用筛选器。

名称 类型 说明
postFilter

string

在返回候选的向量结果集后,将应用该筛选器。 根据筛选器选择性,这可能会导致比参数“k”请求的结果少。

preFilter

string

筛选器将在搜索查询之前应用。

VectorQueryKind

正在执行的向量查询的类型。

名称 类型 说明
vector

string

提供原始矢量值的矢量查询。