SearchClient 類別

參考

要與現有 Azure 搜尋服務索引互動的用戶端。

繼承: azure.search.documents._headers_mixin.HeadersMixin

SearchClient

建構函式

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

參數

endpoint: str

必要

Azure 搜尋服務的 URL 端點

index_name: str

必要

要連線的索引名稱

credential: AzureKeyCredential 或 AsyncTokenCredential

必要

用來授權搜尋用戶端要求的認證

api_version: str

要用於要求的搜尋 API 版本。

audience: str

會設定要用於 Azure Active Directory (AAD) 驗證的物件。使用共用金鑰時，不會考慮物件。如果未提供物件，則會假設公用雲端物件。

範例

使用 API 金鑰建立 SearchClient。


   from azure.core.credentials import AzureKeyCredential
   from azure.search.documents.aio 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 mode：指定自動完成的模式。預設值為 'oneTerm'。使用 'twoTerms' 可取得 shingles 和 'oneTermWithCoNtext'，以在產生自動完成字詞時使用目前的內容。可能的值包括：'oneTerm'、'twoTerms'、'oneTermWithCoNtext'。
close	SearchClient關閉會話。
delete_documents	從 Azure 搜尋服務索引中刪除檔 Delete 會從索引中移除指定的檔。您在刪除作業中指定的任何欄位，除了索引鍵欄位之外，將會忽略。如果您想要從檔中移除個別欄位，請改用 merge_documents ，並將欄位明確設定為 [無]。刪除作業為等冪。也就是說，即使文件索引鍵不存在於索引中，使用該索引鍵嘗試進行刪除作業會導致 200 狀態碼。
get_document	依索引鍵從 Azure 搜尋服務索引擷取檔。
get_document_count	傳回 Azure 搜尋服務索引中的檔數目。
index_documents	指定要做為批次執行的檔作業。：提高 RequestEntityTooLargeError
merge_documents	將中的檔合併至 Azure 搜尋服務索引中的現有檔。 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 搜尋服務索引。上傳動作類似于「upsert」，如果檔是新的，則會插入檔，如果檔存在，則會更新/取代。更新案例中會取代所有欄位。

autocomplete

從 Azure 搜尋服務索引取得搜尋自動完成結果。

屬於索引定義的集合。：keyword mode：指定自動完成的模式。預設值為 'oneTerm'。使用

'twoTerms' 可取得 shingles 和 'oneTermWithCoNtext'，以在產生自動完成字詞時使用目前的內容。可能的值包括：'oneTerm'、'twoTerms'、'oneTermWithCoNtext'。

async 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 之間的數位，表示自動完成查詢必須涵蓋的索引百分比，以便將查詢回報為成功。即使只有一個複本的服務，此參數也有助於確保搜尋可用性。預設值為 80。

search_fields: list[str]

查詢自動完成字詞時要考慮的功能變數名稱清單。目標欄位必須包含在指定的建議工具中。

top: int

要擷取的自動完成字詞數目。這必須是介於 1 到 100 之間的值。預設值為 5。

傳回類型

list[Dict]

範例

取得自動完成。


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

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

   async with search_client:
       results = await 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關閉會話。

async close() -> None

傳回

無

傳回類型

None

delete_documents

從 Azure 搜尋服務索引中刪除檔

Delete 會從索引中移除指定的檔。您在刪除作業中指定的任何欄位，除了索引鍵欄位之外，將會忽略。如果您想要從檔中移除個別欄位，請改用 merge_documents ，並將欄位明確設定為 [無]。

刪除作業為等冪。也就是說，即使文件索引鍵不存在於索引中，使用該索引鍵嘗試進行刪除作業會導致 200 狀態碼。

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

參數

documents: list[dict]

必要

要刪除的檔案清單。

傳回

IndexingResult 清單

傳回類型

list[IndexingResult]

範例

將現有的檔刪除至索引


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

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

get_document

依索引鍵從 Azure 搜尋服務索引擷取檔。

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

參數

key: str

必要

要擷取之檔的主鍵值

selected_fields: list[str]

必要

要包含在結果中的欄位允許清單

傳回

符合指定索引鍵的檔

傳回類型

dict

範例

從搜尋索引取得特定檔。


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

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

   async with search_client:
       result = await 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 搜尋服務索引中的檔數目。

async get_document_count(**kwargs: Any) -> int

傳回

索引中的檔計數

傳回類型

int

index_documents

指定要做為批次執行的檔作業。

：提高 RequestEntityTooLargeError

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

參數

batch: IndexDocumentsBatch

必要

要執行的檔作業批次。

傳回

IndexingResult 清單

傳回類型

list[IndexingResult]

merge_documents

將中的檔合併至 Azure 搜尋服務索引中的現有檔。

Merge 功能會更新現有文件的指定欄位。如果文件不存在，合併就會失敗。您在合併中指定的任何欄位將取代文件中現有的欄位。這也適用于基本型別和複雜類型的集合。

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

參數

documents: list[dict]

必要

要合併的檔案清單。

傳回

IndexingResult 清單

傳回類型

list[IndexingResult]

範例

將欄位合併至現有檔至索引


   result = await search_client.upload_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。

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

參數

documents: list[dict]

必要

要合併或上傳的檔案清單。

傳回

IndexingResult 清單

傳回類型

list[IndexingResult]

search

搜尋檔的 Azure 搜尋索引。

async 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) -> AsyncSearchItemPaged[Dict]

參數

search_text: str

必要

全文檢索搜尋查詢運算式;使用「*」或省略此參數來比對所有檔。

include_total_count: bool

值，指定是否擷取結果總數。預設值為 false。將此值設定為 true 可能會影響效能。請注意，傳回的計數是一個近似值。

facets: list[str]

要套用至搜尋查詢的 Facet 運算式清單。每個 Facet 運算式都包含功能變數名稱，選擇性地後面接著以逗號分隔的名稱：值組清單。

filter: str

要套用至搜尋查詢的 OData $filter運算式。

highlight_fields: str

要用於點擊醒目提示的功能變數名稱逗號分隔清單。只有可搜尋的欄位可用於點擊醒目提示。

highlight_post_tag: str

附加至點擊醒目提示的字串標籤。必須使用 highlightPreTag 進行設定。預設為。

highlight_pre_tag: str

前面加上叫用醒目提示的字串標記。必須使用 highlightPostTag 來設定。預設為。

minimum_coverage

float

介於 0 到 100 之間的數位，表示搜尋查詢必須涵蓋的索引百分比，以便將查詢回報為成功。即使只有一個複本的服務，此參數也有助於確保搜尋可用性。預設值為 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) 格式名稱值，用於評分函式 (的參數值清單。例如，如果評分設定檔使用名為 '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' 且查詢答案為「擷取」時，此參數才有效。設定傳回的答案數目。預設計數為 1。

query_answer_threshold

float

只有當查詢類型為 'semantic' 且查詢答案為「擷取」時，此參數才有效。設定信賴閾值的數目。預設計數為 0.7。

query_caption

str 或 QueryCaptionType

只有當查詢類型為 'semantic' 時，這個參數才有效。如果設定，查詢會傳回從最高排名檔中索引鍵段落擷取的標題。預設為 'None'。可能的值包括：「none」、「extractive」。

query_caption_highlight_enabled

bool

只有當查詢標題設定為「擷取」時，此參數才有效。判斷是否啟用醒目提示。預設為 '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，就會嘗試以相同的複本集為目標。請小心重複重複使用相同的 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」。

傳回

符合指定搜尋準則的檔案清單 (聽寫) 。

傳回類型

AsyncSearchItemPaged[dict]

範例

取得搜尋結果 Facet。

from azure.core.credentials import AzureKeyCredential from azure.search.documents.aio import SearchClient search_client = SearchClient(service_endpoint, index_name, AzureKeyCredential(key)) async with search_client: results = await search_client.search(search_text="WiFi", facets=["category,count:3", "parkingIncluded"]) facets: Dict[str, List[str]] = cast(Dict[str, List[str]], await 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 時，即使搜尋文字中有替代字元或遺漏字元，查詢還是會尋找字詞。雖然這在某些案例中提供較佳的體驗，但因為模糊建議查詢速度較慢，且耗用更多資源，因此會產生效能成本。

async 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 之間的數位，表示建議查詢必須涵蓋的索引百分比，以便將查詢回報為成功。即使只有一個複本的服務，此參數也有助於確保搜尋可用性。預設值為 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.aio import SearchClient search_client = SearchClient(service_endpoint, index_name, AzureKeyCredential(key)) async with search_client: results = await search_client.suggest(search_text="coffee", suggester_name="sg") print("Search suggestions for 'coffee'") for result in results: hotel = await search_client.get_document(key=result["hotelId"]) print(" Text: {} for Hotel: {}".format(repr(result["text"]), hotel["hotelName"]))

upload_documents

將檔上傳至 Azure 搜尋服務索引。

上傳動作類似于「upsert」，如果檔是新的，則會插入檔，如果檔存在，則會更新/取代。更新案例中會取代所有欄位。

async 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 = await search_client.upload_documents(documents=[DOCUMENT]) print("Upload of new document succeeded: {}".format(result[0].succeeded))

共用方式為

SearchClient 類別

建構函式

參數

範例

方法

autocomplete

參數

傳回類型

範例

close

傳回

傳回類型

delete_documents

參數

傳回

傳回類型

範例

get_document

參數

傳回

傳回類型

範例

get_document_count

傳回

傳回類型

index_documents

參數

傳回

傳回類型

merge_documents

參數

傳回

傳回類型

範例

merge_or_upload_documents

參數

傳回

傳回類型

search

參數

傳回

傳回類型

範例

suggest

參數

傳回

傳回類型

範例

upload_documents

參數

傳回

傳回類型

範例

其他資源