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

要求に使用する Search 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 Search インデックスからドキュメントを削除する削除すると、指定したドキュメントがインデックスから削除されます。キーフィールド以外の削除操作で指定したフィールドは無視されます。ドキュメントから個々のフィールドを削除する場合は、代わりに merge_documents を使用し、フィールドを明示的に None に設定します。削除操作はべき等です。つまり、インデックスにドキュメントキーが存在しない場合でも、そのキーを使用した削除操作に対して状態コード 200 が返されます。
get_document	キーを使用して Azure 検索インデックスからドキュメントを取得します。
get_document_count	Azure 検索インデックス内のドキュメントの数を返します。
index_documents	バッチとして実行するドキュメント操作を指定します。：発生させます RequestEntityTooLargeError
merge_documents	内のドキュメントを Azure 検索インデックス内の既存のドキュメントにマージします。マージによって、指定したフィールドで既存のドキュメントが更新されます。ドキュメントが存在しない場合、マージは失敗します。マージで指定したすべてのフィールドは、ドキュメント内の既存のフィールドを置き換えます。これは、プリミティブ型と複合型のコレクションにも適用されます。
merge_or_upload_documents	内のドキュメントを Azure 検索インデックス内の既存のドキュメントにマージするか、まだ存在しない場合はアップロードします。このアクションは、指定されたキーを持つドキュメントが既にインデックスに存在する場合、 merge_documents のように動作します。ドキュメントが存在しない場合は、新しいドキュメントで upload_documents のように動作します。
search	Azure Search インデックスでドキュメントを検索します。
suggest	Azure 検索インデックスから検索候補の結果を取得します。文字、および 100 文字以下。 :p aram str suggester_name: 必須。インデックス定義の一部である suggesters コレクションで指定された suggester の名前。 :キーワード (keyword) str filter: 候補と見なされるドキュメントをフィルター処理する OData 式。 :キーワード (keyword) bool use_fuzzy_matching: 提案にあいまい一致を使用するかどうかを示す値。既定値は false です。 true に設定すると、検索テキストに置換文字または欠落文字がある場合でも、クエリは用語を検索します。一部のシナリオではエクスペリエンスが向上しますが、あいまい候補クエリの速度が低下し、リソースが多く消費されるため、パフォーマンスコストがかかります。
upload_documents	Azure Search インデックスにドキュメントをアップロードします。アップロードアクションは、ドキュメントが新しい場合は挿入され、存在する場合は更新/置換される "アップサート" に似ています。更新ケースでは、すべてのフィールドが置き換えられます。

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 の範囲の数値。このパラメーターは、レプリカが 1 つだけのサービスでも検索の可用性を確保するのに役立ちます。既定値は 80 です。

search_fields: list[str]

オートコンプリート用語のクエリを実行するときに考慮するフィールド名の一覧。ターゲットフィールドは、指定した suggester に含まれている必要があります。

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 Search インデックスからドキュメントを削除する

削除すると、指定したドキュメントがインデックスから削除されます。キーフィールド以外の削除操作で指定したフィールドは無視されます。ドキュメントから個々のフィールドを削除する場合は、代わりに merge_documents を使用し、フィールドを明示的に None に設定します。

削除操作はべき等です。つまり、インデックスにドキュメントキーが存在しない場合でも、そのキーを使用した削除操作に対して状態コード 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_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(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 の範囲の数値。このパラメーターは、レプリカが 1 つだけのサービスでも検索の可用性を確保するのに役立ちます。既定値は 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]

name-values 形式を使用してスコアリング関数 (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' で、クエリ応答が 'extractive' の場合にのみ有効です。返される回答の数を構成します。既定の数は 1 です。

query_answer_threshold: float

このパラメーターは、クエリの種類が 'semantic' で、クエリ応答が 'extractive' の場合にのみ有効です。信頼度のしきい値の数を構成します。既定の数は 0.7 です。

query_caption: str または QueryCaptionType

このパラメーターは、クエリの種類が 'semantic' の場合にのみ有効です。設定されている場合、クエリは、最上位のランク付けされたドキュメント内の主要な部分から抽出されたキャプションを返します。既定値は 'None' です。使用できる値は、"none"、"extractive" です。

query_caption_highlight_enabled: bool

このパラメーターは、クエリのキャプションが 'extractive' に設定されている場合に、クエリの種類が "セマンティック" である場合にのみ有効です。強調表示を有効にするかどうかを指定します。既定値は 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" です。

の戻り値の型 :

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: 必須。インデックス定義の一部である suggesters コレクションで指定された suggester の名前。 :キーワード (keyword) str filter: 候補と見なされるドキュメントをフィルター処理する 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 の範囲の数値。このパラメーターは、レプリカが 1 つだけのサービスでも検索の可用性を確保するのに役立ちます。既定値は 80 です。

order_by: list[str]

結果を並べ替える OData $orderby式の一覧。各式には、フィールド名または geo.distance() 関数または search.score() 関数の呼び出しを指定できます。各式の後に asc を付けて昇順を示し、降順を示す desc を指定できます。既定値は昇順です。結び付きは、ドキュメントの一致スコアによって切り離されます。 $orderbyが指定されていない場合、既定の並べ替え順序はドキュメント一致スコアの降順になります。最大で 32 個の$orderby句を指定できます。

search_fields: list[str]

指定した検索テキストを検索するフィールド名の一覧。ターゲットフィールドは、指定した suggester に含まれている必要があります。

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 Search インデックスにドキュメントをアップロードします。

アップロードアクションは、ドキュメントが新しい場合は挿入され、存在する場合は更新/置換される "アップサート" に似ています。更新ケースでは、すべてのフィールドが置き換えられます。

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))

次の方法で共有

SearchClient クラス

コンストラクター

パラメーター

例

メソッド

autocomplete

パラメーター

の戻り値の型 :

例

close

delete_documents

パラメーター

戻り値

の戻り値の型 :

例

get_document

パラメーター

戻り値

の戻り値の型 :

例

get_document_count

戻り値

の戻り値の型 :

index_documents

パラメーター

戻り値

の戻り値の型 :

merge_documents

パラメーター

戻り値

の戻り値の型 :

例

merge_or_upload_documents

パラメーター

戻り値

の戻り値の型 :

search

パラメーター

の戻り値の型 :

例

suggest

パラメーター

戻り値

の戻り値の型 :

例

upload_documents

パラメーター

戻り値

の戻り値の型 :

例

フィードバック

その他のリソース