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

SearchClient 类

用于与现有 Azure 搜索索引交互的客户端。

继承

azure.search.documents._headers_mixin.HeadersMixin

SearchClient

构造函数

SearchClient(endpoint: str, index_name: str, credential: AzureKeyCredential | TokenCredential, **kwargs: Any)

参数

endpoint

str

必需

Azure 搜索服务的 URL 终结点

index_name

str

必需

要连接到的索引的名称

credential

AzureKeyCredential 或 TokenCredential

必需

用于授权搜索客户端请求的凭据

api_version

str

要用于请求的搜索 API 版本。

audience

str

设置用于 Azure Active Directory (AAD) 身份验证的受众。 使用共享密钥时，不考虑受众。 如果未提供受众，将假定为公有云受众。

示例

使用 API 密钥创建 SearchClient。

   from azure.core.credentials import AzureKeyCredential
   from azure.search.documents import SearchClient

   service_endpoint = os.environ["AZURE_SEARCH_SERVICE_ENDPOINT"]
   index_name = os.environ["AZURE_SEARCH_INDEX_NAME"]
   key = os.environ["AZURE_SEARCH_API_KEY"]

   search_client = SearchClient(service_endpoint, index_name, AzureKeyCredential(key))

方法

autocomplete	从 Azure 搜索索引获取搜索自动完成结果。 属于索引定义的集合。 ：关键字 (keyword) 模式：指定自动完成的模式。 默认值为“oneTerm”。 使用 “twoTerms”，用于获取带状线和“oneTermWithContext”，以在生成自动完成的术语时使用当前上下文。 可能的值包括：“oneTerm”、“twoTerms”、“oneTermWithContext”。
close	SearchClient关闭会话。
delete_documents	从 Azure 搜索索引中删除文档 删除从索引中删除指定的文档。 除键字段外，在删除操作中指定的任何字段都将被忽略。 如果要从文档中删除单个字段，请改用 merge_documents ，并将该字段显式设置为“无”。 删除操作是幂等的。 即，即使索引中不存在文档键，使用该键尝试执行删除操作仍将导致 200 状态代码。
get_document	按键从 Azure 搜索索引中检索文档。
get_document_count	返回 Azure 搜索索引中的文档数。
index_documents	指定要作为批处理执行的文档操作。 ：提高 RequestEntityTooLargeError
merge_documents	将 中的文档合并到 Azure 搜索索引中的现有文档。 Merge 使用指定字段更新现有文档。 如果文档不存在，合并将失败。 merge 中指定的任何字段都将替换文档中的现有字段。 这也适用于基元和复杂类型的集合。
merge_or_upload_documents	将 中的文档合并到 Azure 搜索索引中的现有文档，或者上传它们（如果尚不存在）。 如果索引中已存在具有给定键的文档，则此操作的行为类似于 merge_documents 。 如果文档不存在，则其行为类似于与新文档 upload_documents 。
search	在 Azure 搜索索引中搜索文档。
suggest	从 Azure 搜索索引获取搜索建议结果。 字符，且不超过 100 个字符。 :p aram str suggester_name：必需。 建议器集合中指定的建议器的名称，该集合是索引定义的一部分。 ：关键字 (keyword) str 筛选器：一个 OData 表达式，用于筛选考虑建议的文档。 ：关键字 (keyword) bool use_fuzzy_matching：指示是否对建议使用模糊匹配的值 查询。 默认值为 false。 如果设置为 true，则查询将查找字词，即使搜索文本中有替换字符或缺失字符也是如此。 虽然这在某些方案中提供了更好的体验，但由于模糊建议的查询速度较慢并消耗更多资源，这会带来性能成本。
upload_documents	将文档上传到 Azure 搜索索引。 上传操作类似于“更新插入”，其中将插入文档（如果文档为新文档），如果文档存在，则将其更新/替换。 在更新案例中，将替换所有字段。

autocomplete

从 Azure 搜索索引获取搜索自动完成结果。

属于索引定义的集合。 ：关键字 (keyword) 模式：指定自动完成的模式。 默认值为“oneTerm”。 使用

“twoTerms”，用于获取带状线和“oneTermWithContext”，以在生成自动完成的术语时使用当前上下文。 可能的值包括：“oneTerm”、“twoTerms”、“oneTermWithContext”。

autocomplete(search_text: str, suggester_name: str, *, mode: str | AutocompleteMode | None = None, use_fuzzy_matching: bool | None = None, highlight_post_tag: str | None = None, highlight_pre_tag: str | None = None, minimum_coverage: float | None = None, search_fields: List[str] | None = None, top: int | None = None, **kwargs) -> List[Dict]

参数

filter

str

一个 OData 表达式，用于筛选用于为自动完成结果生成已完成字词的文档。

use_fuzzy_matching

bool

一个 值，该值指示是否对自动完成查询使用模糊匹配。 默认值为 false。 设置为 true 时，即使搜索文本中存在替换字符或缺失字符，查询也会查找字词。 虽然这在某些情况下提供更好的体验，但会降低性能，因为模糊的自动完成查询速度较慢，会消耗更多资源。

highlight_post_tag

str

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

highlight_pre_tag

str

一个字符串标记，在前面追加到命中突出显示。 必须使用 highlightPostTag 进行设置。 如果省略，则禁用命中突出显示。

minimum_coverage

float

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

search_fields

list[str]

查询自动完成的术语时要考虑的字段名称列表。 目标字段必须包含在指定的建议器中。

top

int

要检索的自动完成的术语数。 此值必须是介于 1 和 100 之间的值。默认值为 5。

返回类型

list[dict]

示例

获取自动完成。

   from azure.core.credentials import AzureKeyCredential
   from azure.search.documents import SearchClient

   search_client = SearchClient(service_endpoint, index_name, AzureKeyCredential(key))

   results = search_client.autocomplete(search_text="bo", suggester_name="sg")

   print("Autocomplete suggestions for 'bo'")
   for result in results:
       print("    Completion: {}".format(result["text"]))

close

SearchClient关闭会话。

close() -> None

delete_documents

从 Azure 搜索索引中删除文档

删除从索引中删除指定的文档。 除键字段外，在删除操作中指定的任何字段都将被忽略。 如果要从文档中删除单个字段，请改用 merge_documents ，并将该字段显式设置为“无”。

删除操作是幂等的。 即，即使索引中不存在文档键，使用该键尝试执行删除操作仍将导致 200 状态代码。

delete_documents(documents: List[Dict], **kwargs: Any) -> List[IndexingResult]

参数

documents

list[dict]

必需

要删除的文档的列表。

返回

IndexingResult 列表

返回类型

list[IndexingResult]

示例

将现有文档删除到索引

   result = search_client.delete_documents(documents=[{"hotelId": "1000"}])

   print("Delete new document succeeded: {}".format(result[0].succeeded))

get_document

按键从 Azure 搜索索引中检索文档。

get_document(key: str, selected_fields: List[str] | None = None, **kwargs: Any) -> Dict

参数

key

str

必需

要检索的文档的主键值

selected_fields

list[str]

必需

要包含在结果中的字段的允许列表

返回

存储在 Azure 搜索索引中的文档

返回类型

dict

示例

从搜索索引获取特定文档。

   from azure.core.credentials import AzureKeyCredential
   from azure.search.documents import SearchClient

   search_client = SearchClient(service_endpoint, index_name, AzureKeyCredential(key))

   result = search_client.get_document(key="23")

   print("Details for hotel '23' are:")
   print("        Name: {}".format(result["hotelName"]))
   print("      Rating: {}".format(result["rating"]))
   print("    Category: {}".format(result["category"]))

get_document_count

返回 Azure 搜索索引中的文档数。

get_document_count(**kwargs: Any) -> int

返回

索引中的文档计数

返回类型

int

index_documents

指定要作为批处理执行的文档操作。

：提高 RequestEntityTooLargeError

index_documents(batch: IndexDocumentsBatch, **kwargs: Any) -> List[IndexingResult]

参数

batch

IndexDocumentsBatch

必需

要执行的一批文档操作。

返回

IndexingResult 列表

返回类型

list[IndexingResult]

merge_documents

将 中的文档合并到 Azure 搜索索引中的现有文档。

Merge 使用指定字段更新现有文档。 如果文档不存在，合并将失败。 merge 中指定的任何字段都将替换文档中的现有字段。 这也适用于基元和复杂类型的集合。

merge_documents(documents: List[Dict], **kwargs: Any) -> List[IndexingResult]

参数

documents

list[dict]

必需

要合并的文档的列表。

返回

IndexingResult 列表

返回类型

list[IndexingResult]

示例

将字段合并到现有文档中的索引

   result = search_client.merge_documents(documents=[{"hotelId": "1000", "rating": 4.5}])

   print("Merge into new document succeeded: {}".format(result[0].succeeded))

merge_or_upload_documents

将 中的文档合并到 Azure 搜索索引中的现有文档，或者上传它们（如果尚不存在）。

如果索引中已存在具有给定键的文档，则此操作的行为类似于 merge_documents 。 如果文档不存在，则其行为类似于与新文档 upload_documents 。

merge_or_upload_documents(documents: List[Dict], **kwargs: Any) -> List[IndexingResult]

参数

documents

list[dict]

必需

要合并或上传的文档列表。

返回

IndexingResult 列表

返回类型

list[IndexingResult]

search

在 Azure 搜索索引中搜索文档。

search(search_text: str | None = None, *, include_total_count: bool | None = None, facets: List[str] | None = None, filter: str | None = None, highlight_fields: str | None = None, highlight_post_tag: str | None = None, highlight_pre_tag: str | None = None, minimum_coverage: float | None = None, order_by: List[str] | None = None, query_type: str | QueryType | None = None, scoring_parameters: List[str] | None = None, scoring_profile: str | None = None, search_fields: List[str] | None = None, search_mode: str | SearchMode | None = None, query_answer: str | QueryAnswerType | None = None, query_answer_count: int | None = None, query_answer_threshold: float | None = None, query_caption: str | QueryCaptionType | None = None, query_caption_highlight_enabled: bool | None = None, semantic_configuration_name: str | None = None, select: List[str] | None = None, skip: int | None = None, top: int | None = None, scoring_statistics: str | ScoringStatistics | None = None, session_id: str | None = None, vector_queries: List[VectorQuery] | None = None, vector_filter_mode: str | VectorFilterMode | None = None, semantic_error_mode: str | SemanticErrorMode | None = None, semantic_max_wait_in_milliseconds: int | None = None, **kwargs: Any) -> SearchItemPaged[Dict]

参数

search_text

str

必需

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

include_total_count

bool

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

facets

list[str]

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

filter

str

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

highlight_fields

str

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

highlight_post_tag

str

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

highlight_pre_tag

str

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

minimum_coverage

float

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

order_by

list[str]

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

query_type

str 或 QueryType

一个 值，该值指定搜索查询的语法。 默认值为“simple”。 如果查询使用 Lucene 查询语法，请使用“full”。 可能的值包括：“simple”、“full”、“semantic”。

scoring_parameters

list[str]

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

scoring_profile

str

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

search_fields

list[str]

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

search_mode

str 或 SearchMode

一个 值，该值指定是否必须匹配任何或所有搜索词才能将文档计数为匹配项。 可能的值包括：“any”、“all”。

query_answer

str 或 QueryAnswerType

仅当查询类型为“semantic”时，此参数才有效。 如果设置，查询将返回从排名靠前的文档中的关键段落中提取的答案。 可能的值包括：“none”、“extractive”。

query_answer_count

int

仅当查询类型为“semantic”且查询答案为“extractive”时，此参数才有效。 配置返回的答案数。 默认计数为 1。

query_answer_threshold

float

仅当查询类型为“semantic”且查询答案为“extractive”时，此参数才有效。 配置置信度阈值数。 默认计数为 0.7。

query_caption

str 或 QueryCaptionType

仅当查询类型为“semantic”时，此参数才有效。 如果设置，查询将返回从排名靠前的文档中的关键段落中提取的标题。 默认为“无”。 可能的值包括：“none”、“extractive”。

query_caption_highlight_enabled

bool

仅当查询描述文字设置为“extractive”时，查询类型为“semantic”时，此参数才有效。 确定是否启用突出显示。 默认为“true”。

semantic_configuration_name

str

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

select

list[str]

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

skip

int

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

top

int

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

scoring_statistics

str 或 ScoringStatistics

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

session_id

str

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

semantic_error_mode

str 或 SemanticErrorMode

允许用户选择语义调用应完全失败 (默认/当前行为) ，还是返回部分结果。 已知值为：“partial”和“fail”。

semantic_max_wait_in_milliseconds

int

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

vector_queries

list[VectorQuery]

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

vector_filter_mode

str 或 VectorFilterMode

确定是否在执行向量搜索之前或之后应用筛选器。 默认值为“preFilter”。 已知值为：“postFilter”和“preFilter”。

返回类型

SearchItemPaged[dict]

示例

获取搜索结果方面。

   from azure.core.credentials import AzureKeyCredential
   from azure.search.documents import SearchClient

   search_client = SearchClient(service_endpoint, index_name, AzureKeyCredential(key))

   results = search_client.search(search_text="WiFi", facets=["category,count:3", "parkingIncluded"])

   facets: Dict[str, List[str]] = cast(Dict[str, List[str]], results.get_facets())

   print("Catgory facet counts for hotels:")
   for facet in facets["category"]:
       print("    {}".format(facet))

suggest

从 Azure 搜索索引获取搜索建议结果。

字符，且不超过 100 个字符。 :p aram str suggester_name：必需。 建议器集合中指定的建议器的名称，该集合是索引定义的一部分。 ：关键字 (keyword) str 筛选器：一个 OData 表达式，用于筛选考虑建议的文档。 ：关键字 (keyword) bool use_fuzzy_matching：指示是否对建议使用模糊匹配的值

查询。 默认值为 false。 如果设置为 true，则查询将查找字词，即使搜索文本中有替换字符或缺失字符也是如此。 虽然这在某些方案中提供了更好的体验，但由于模糊建议的查询速度较慢并消耗更多资源，这会带来性能成本。

suggest(search_text: str, suggester_name: str, *, use_fuzzy_matching: bool | None = None, highlight_post_tag: str | None = None, highlight_pre_tag: str | None = None, minimum_coverage: float | None = None, order_by: List[str] | None = None, search_fields: List[str] | None = None, select: List[str] | None = None, top: int | None = None, **kwargs) -> List[Dict]

参数

highlight_post_tag

str

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

highlight_pre_tag

str

一个字符串标记，在前面附加以命中突出显示。 必须使用 highlightPostTag 进行设置。 如果省略，则禁用建议的点击突出显示。

minimum_coverage

float

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

order_by

list[str]

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

search_fields

list[str]

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

select

list[str]

要检索的字段列表。 如果未指定，则结果中仅包含键字段。

top

int

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

返回

文档列表。

返回类型

list[dict]

示例

获取搜索建议。

   from azure.core.credentials import AzureKeyCredential
   from azure.search.documents import SearchClient

   search_client = SearchClient(service_endpoint, index_name, AzureKeyCredential(key))

   results = search_client.suggest(search_text="coffee", suggester_name="sg")

   print("Search suggestions for 'coffee'")
   for result in results:
       hotel = search_client.get_document(key=result["hotelId"])
       print("    Text: {} for Hotel: {}".format(repr(result["text"]), hotel["hotelName"]))

upload_documents

将文档上传到 Azure 搜索索引。

上传操作类似于“更新插入”，其中将插入文档（如果文档为新文档），如果文档存在，则将其更新/替换。 在更新案例中，将替换所有字段。

upload_documents(documents: List[Dict], **kwargs: Any) -> List[IndexingResult]

参数

documents

list[dict]

必需

要上传的文档列表。

返回

IndexingResult 列表

返回类型

list[IndexingResult]

示例

将新文档上传到索引

   DOCUMENT = {
       "category": "Hotel",
       "hotelId": "1000",
       "rating": 4.0,
       "rooms": [],
       "hotelName": "Azure Inn",
   }

   result = search_client.upload_documents(documents=[DOCUMENT])

   print("Upload of new document succeeded: {}".format(result[0].succeeded))