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

要求に使用する Search 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) モード: オートコンプリートのモードを指定します。 既定値は '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 検索インデックスにアップロードします。 アップロード アクションは、ドキュメントが新しい場合は挿入され、存在する場合は更新/置換される "アップサート" に似ています。 更新ケースでは、すべてのフィールドが置き換えられます。

autocomplete

Azure 検索インデックスから検索の自動入力候補の結果を取得します。

インデックス定義の一部である コレクション。 :キーワード (keyword) モード: オートコンプリートのモードを指定します。 既定値は 'oneTerm' です。 用途

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

search_fields

list[str]

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

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

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

削除操作はべき等です。 つまり、インデックスにドキュメント キーが存在しない場合でも、そのキーを使用した削除操作に対して状態コード 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 検索インデックス内の既存のドキュメントにマージします。

マージによって、指定したフィールドで既存のドキュメントが更新されます。 ドキュメントが存在しない場合、マージは失敗します。 マージで指定したすべてのフィールドは、ドキュメント内の既存のフィールドを置き換えます。 これは、プリミティブ型と複合型のコレクションにも適用されます。

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 Search インデックスでドキュメントを検索します。

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]

検索クエリに適用するファセット式の一覧。 各ファセット式にはフィールド名が含まれます。必要に応じて、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' に設定されている場合に、クエリの種類が '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 が使用されている限り、同じレプリカ セットをターゲットにするためのベスト エフォート試行が行われます。 同じ 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]

例

検索結果ファセットを取得します。

   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: 必須。 インデックス定義の一部である suggesters コレクションで指定された suggester の名前。 :キーワード (keyword) str filter: 候補と見なされるドキュメントをフィルター処理する 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 の範囲の数値。 このパラメーターは、レプリカが 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.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 検索インデックスにアップロードします。

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

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