Partager via

SearchClient Classe

  • Référence

Un client pour interagir avec un index de recherche Azure existant.

Héritage
azure.search.documents._headers_mixin.HeadersMixin
SearchClient

Constructeur

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

Paramètres

endpoint
str
Obligatoire

Point de terminaison d’URL d’un service Recherche Azure

index_name
str
Obligatoire

Nom de l’index auquel se connecter

credential
AzureKeyCredential ou TokenCredential
Obligatoire

Informations d’identification permettant d’autoriser les demandes de client de recherche

api_version
str

Version de l’API De recherche à utiliser pour les requêtes.

audience
str

définit l’audience à utiliser pour l’authentification avec Azure Active Directory (AAD). L’audience n’est pas prise en compte lors de l’utilisation d’une clé partagée. Si l’audience n’est pas fournie, l’audience du cloud public est supposée.

Exemples

Création du SearchClient avec une clé API.


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

Méthodes

autocomplete

Obtenez les résultats de la saisie semi-automatique de recherche à partir de l’index recherche Azure.

collection qui fait partie de la définition d’index. :mot clé mode : spécifie le mode de saisie semi-automatique. La valeur par défaut est « oneTerm ». Utilisation

« twoTerms » pour obtenir des shingles et « oneTermWithContext » pour utiliser le contexte actuel lors de la production de termes remplis automatiquement. Les valeurs possibles sont les suivantes : « oneTerm », « twoTerms », « oneTermWithContext ».
close

Fermez la SearchClient session.
delete_documents

Supprimer des documents de l’index Recherche Azure

Supprimer supprime le document spécifié de l’index. Tout champ que vous spécifiez dans une opération de suppression, autre que le champ de clé, sera ignoré. Si vous souhaitez supprimer un champ individuel d’un document, utilisez merge_documents à la place et définissez le champ explicitement sur Aucun.

Les opérations de suppression sont idempotentes. Autrement dit, même si une clé de document n’existe pas dans l’index, une tentative d’opération de suppression avec cette clé générera le code d’état 200.
get_document

Récupérez un document à partir de l’index recherche Azure par sa clé.
get_document_count

Retourne le nombre de documents dans l’index recherche Azure.
index_documents

Spécifiez une opération de document à effectuer en tant que lot.

:Soulève RequestEntityTooLargeError
merge_documents

Fusionnez des documents dans avec des documents existants dans l’index recherche Azure.

La fusion met à jour un document existant avec les champs spécifiés. Si le document n'existe pas, la fusion échoue. N'importe quel champ que vous spécifiez dans une fusion remplace le champ existant dans le document. Cela s’applique également aux collections de types primitifs et complexes.
merge_or_upload_documents

Fusionnez des documents dans dans des documents existants dans l’index recherche Azure, ou chargez-les s’ils n’existent pas encore.

Cette action se comporte comme merge_documents si un document avec la clé donnée existe déjà dans l’index. Si le document n’existe pas, il se comporte comme upload_documents avec un nouveau document.
search

Recherchez des documents dans l’index de recherche Azure.
suggest

Obtenez les résultats des suggestions de recherche à partir de l’index de recherche Azure.

caractère et pas plus de 100 caractères. :p aram str suggester_name : Obligatoire. Nom du suggesteur tel que spécifié dans la collection suggesteurs qui fait partie de la définition d’index. :mot clé str filter : expression OData qui filtre les documents pris en compte pour les suggestions. :mot clé bool use_fuzzy_matching : valeur indiquant s’il faut utiliser la correspondance approximative pour les suggestions

base de données élastique La valeur par défaut est false. Lorsqu’elle est définie sur true, la requête trouve des termes même s’il existe un caractère remplacé ou manquant dans le texte de recherche. Bien que cela offre une meilleure expérience dans certains scénarios, il s’agit d’un coût de performances, car les requêtes de suggestions approximatives sont plus lentes et consomment plus de ressources.
upload_documents

Chargez des documents dans l’index de recherche Azure.

Une action de chargement est similaire à une « upsert » où le document est inséré s’il est nouveau et mis à jour/remplacé s’il existe. Tous les champs sont remplacés dans le cas de mise à jour.

autocomplete

Obtenez les résultats de la saisie semi-automatique de recherche à partir de l’index recherche Azure.

collection qui fait partie de la définition d’index. :mot clé mode : spécifie le mode de saisie semi-automatique. La valeur par défaut est « oneTerm ». Utilisation

« twoTerms » pour obtenir des shingles et « oneTermWithContext » pour utiliser le contexte actuel lors de la production de termes remplis automatiquement. Les valeurs possibles sont les suivantes : « 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]

Paramètres

filter
str

Expression OData qui filtre les documents utilisés pour produire des termes terminés pour le résultat de la saisie semi-automatique.

use_fuzzy_matching
bool

Valeur indiquant s’il faut utiliser une correspondance approximative pour la requête d’autocomplétion. La valeur par défaut est false. Lorsque la valeur est true, la requête trouve les termes même s’il existe un caractère remplacé ou manquant dans le texte de recherche. Bien que cela offre une meilleure expérience dans certains scénarios, cela a un coût de performances, car les requêtes de saisie semi-automatique approximatives sont plus lentes et consomment plus de ressources.

highlight_post_tag
str

Balise de chaîne qui est ajoutée aux surbrillances d’accès. Doit être défini avec highlightPreTag. S’il est omis, la mise en surbrillance des correspondances est désactivée.

highlight_pre_tag
str

Balise de chaîne qui est précédée pour atteindre les surlignages. Doit être défini avec highlightPostTag. S’il est omis, la mise en surbrillance des correspondances est désactivée.

minimum_coverage
float

Nombre compris entre 0 et 100 indiquant le pourcentage de l’index qui doit être couvert par une requête de saisie semi-automatique pour que la requête soit signalée comme une réussite. Ce paramètre peut être utile pour garantir la disponibilité de la recherche, même pour les services avec une seule réplica. La valeur par défaut est 80.

search_fields
list[str]

Liste des noms de champs à prendre en compte lors de l’interrogation de termes remplis automatiquement. Les champs cibles doivent être inclus dans le suggesteur spécifié.

top
int

Nombre de termes remplis automatiquement à récupérer. Il doit s’agir d’une valeur comprise entre 1 et 100. La valeur par défaut est 5.

Type de retour

list[dict]

Exemples

Obtenir une saisie semi-automatique.


   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

Fermez la SearchClient session.

close() -> None

delete_documents

Supprimer des documents de l’index Recherche Azure

Supprimer supprime le document spécifié de l’index. Tout champ que vous spécifiez dans une opération de suppression, autre que le champ de clé, sera ignoré. Si vous souhaitez supprimer un champ individuel d’un document, utilisez merge_documents à la place et définissez le champ explicitement sur Aucun.

Les opérations de suppression sont idempotentes. Autrement dit, même si une clé de document n’existe pas dans l’index, une tentative d’opération de suppression avec cette clé générera le code d’état 200.

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

Paramètres

documents
list[dict]
Obligatoire

Liste des documents à supprimer.

Retours

Liste d’IndexingResult

Type de retour

list[IndexingResult]

Exemples

Supprimer des documents existants dans un index


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

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

get_document

Récupérez un document à partir de l’index recherche Azure par sa clé.

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

Paramètres

key
str
Obligatoire

Valeur de clé primaire pour le document à récupérer

selected_fields
list[str]
Obligatoire

liste verte des champs à inclure dans les résultats

Retours

Document tel qu’il est stocké dans l’index recherche Azure

Type de retour

dict

Exemples

Obtenez un document spécifique à partir de l’index de recherche.


   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

Retourne le nombre de documents dans l’index recherche Azure.

get_document_count(**kwargs: Any) -> int

Retours

Nombre de documents dans l’index

Type de retour

int

index_documents

Spécifiez une opération de document à effectuer en tant que lot.

:Soulève RequestEntityTooLargeError

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

Paramètres

batch
IndexDocumentsBatch
Obligatoire

Lot d’opérations de document à effectuer.

Retours

Liste d’IndexingResult

Type de retour

list[IndexingResult]

merge_documents

Fusionnez des documents dans avec des documents existants dans l’index recherche Azure.

La fusion met à jour un document existant avec les champs spécifiés. Si le document n'existe pas, la fusion échoue. N'importe quel champ que vous spécifiez dans une fusion remplace le champ existant dans le document. Cela s’applique également aux collections de types primitifs et complexes.

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

Paramètres

documents
list[dict]
Obligatoire

Liste des documents à fusionner.

Retours

Liste d’IndexingResult

Type de retour

list[IndexingResult]

Exemples

Fusionner des champs dans des documents existants dans un index


   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

Fusionnez des documents dans dans des documents existants dans l’index recherche Azure, ou chargez-les s’ils n’existent pas encore.

Cette action se comporte comme merge_documents si un document avec la clé donnée existe déjà dans l’index. Si le document n’existe pas, il se comporte comme upload_documents avec un nouveau document.

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

Paramètres

documents
list[dict]
Obligatoire

Liste des documents à fusionner ou à charger.

Retours

Liste d’IndexingResult

Type de retour

list[IndexingResult]

Recherchez des documents dans l’index de recherche 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]

Paramètres

search_text
str
Obligatoire

Une expression de requête de recherche en texte intégral ; Utilisez « * » ou omettez ce paramètre pour faire correspondre tous les documents.

include_total_count
bool

Valeur qui spécifie s’il faut extraire le nombre total de résultats. La valeur par défaut est false. La définition de cette valeur sur true peut avoir un impact sur les performances. Notez que le nombre retourné est une approximation.

facets
list[str]

Liste des expressions de facettes à appliquer à la requête de recherche. Chaque expression de facette contient un nom de champ, éventuellement suivi d’une liste séparée par des virgules de paires nom :valeur.

filter
str

L’expression OData $filter à appliquer à la requête de recherche.

highlight_fields
str

Liste séparée par des virgules des noms de champs à utiliser pour les surlignages d’accès. Seuls les champs pouvant faire l’objet d’une recherche peuvent être utilisés pour la mise en surbrillance des correspondances.

highlight_post_tag
str

Balise de chaîne qui est ajoutée aux surbrillances d’accès. Doit être défini avec highlightPreTag. La valeur par défaut est .

highlight_pre_tag
str

Balise de chaîne qui est précédée pour atteindre les surlignages. Doit être défini avec highlightPostTag. La valeur par défaut est .

minimum_coverage
float

Nombre compris entre 0 et 100 indiquant le pourcentage de l’index qui doit être couvert par une requête de recherche pour que la requête soit signalée comme une réussite. Ce paramètre peut être utile pour garantir la disponibilité de la recherche, même pour les services avec une seule réplica. La valeur par défaut est 100.

order_by
list[str]

Liste des expressions $orderby OData pour trier les résultats. Chaque expression peut être un nom de champ ou un appel aux fonctions geo.distance() ou search.score(). Chaque expression peut être suivie de asc pour indiquer l’ordre croissant et de desc pour indiquer la valeur décroissante. La valeur par défaut est l'ordre croissant. Les liens seront rompus par les scores de correspondance des documents. Si aucun orderBy n’est spécifié, l’ordre de tri par défaut est décroissant par score de correspondance de document. Il peut y avoir au maximum 32 clauses $orderby.

query_type
str ou QueryType

Valeur qui spécifie la syntaxe de la requête de recherche. La valeur par défaut est « simple ». Utilisez « full » si votre requête utilise la syntaxe de requête Lucene. Les valeurs possibles sont les suivantes : 'simple', 'full', 'semantic'.

scoring_parameters
list[str]

Liste des valeurs de paramètres à utiliser dans les fonctions de scoring (par exemple, referencePointParameter) à l’aide du format name-values. Par exemple, si le profil de scoring définit une fonction avec un paramètre appelé « mylocation », la chaîne de paramètre est « mylocation–122.2,44.8 » (sans les guillemets).

scoring_profile
str

Nom du profil de calcul de score utilisé pour évaluer les scores de correspondance des documents correspondants afin de trier les résultats.

search_fields
list[str]

Liste des noms de champs auxquels étendre la recherche en texte intégral. Lorsque vous utilisez la recherche sur champ (fieldName :searchExpression) dans une requête Lucene complète, les noms de champ de chaque expression de recherche avec champ sont prioritaires sur les noms de champs répertoriés dans ce paramètre.

search_mode
str ou SearchMode

Valeur qui spécifie si tout ou partie des termes de recherche doivent être mis en correspondance pour compter le document comme une correspondance. Les valeurs possibles incluent : 'any', 'all'.

query_answer
str ou QueryAnswerType

Ce paramètre n’est valide que si le type de requête est « sémantique ». Si elle est définie, la requête retourne des réponses extraites des passages clés dans les documents classés le plus haut. Les valeurs possibles sont les suivantes : « none », « extractif ».

query_answer_count
int

Ce paramètre n’est valide que si le type de requête est « sémantique » et si la réponse à la requête est « extractif ». Configure le nombre de réponses retournées. Le nombre par défaut est 1.

query_answer_threshold
float

Ce paramètre n’est valide que si le type de requête est « sémantique » et si la réponse à la requête est « extractif ». Configure le nombre de seuils de confiance. Le nombre par défaut est 0,7.

query_caption
str ou QueryCaptionType

Ce paramètre n’est valide que si le type de requête est « sémantique ». Si la valeur est définie, la requête retourne les légendes extraites des passages clés dans les documents classés le plus haut. La valeur par défaut est « None ». Les valeurs possibles sont les suivantes : « none », « extractif ».

query_caption_highlight_enabled
bool

Ce paramètre n’est valide que si le type de requête est « sémantique » lorsque légende de requête est défini sur « extractif ». Détermine si la mise en surbrillance est activée. La valeur par défaut est « true ».

semantic_configuration_name
str

Nom de la configuration sémantique qui sera utilisée lors du traitement de documents pour des requêtes de type sémantique.

select
list[str]

Liste des champs à récupérer. Si aucune valeur n'est spécifiée, tous les champs marqués comme récupérables dans le schéma sont inclus.

skip
int

Nombre de résultats de recherche à ignorer. Cette valeur ne peut pas être supérieure à 100 000. Si vous avez besoin d’analyser des documents dans l’ordre, mais que vous ne pouvez pas utiliser $skip en raison de cette limitation, envisagez d’utiliser $orderby sur une clé entièrement ordonnée et $filter avec une requête de plage à la place.

top
int

Nombre de résultats de recherche à récupérer. Cela peut être utilisé conjointement avec $skip pour implémenter la pagination côté client des résultats de la recherche. Si les résultats sont tronqués en raison de la pagination côté serveur, la réponse inclut un jeton de continuation qui peut être utilisé pour émettre une autre demande de recherche pour la page de résultats suivante.

scoring_statistics
str ou ScoringStatistics

Valeur qui spécifie si nous voulons calculer des statistiques de scoring (telles que la fréquence des documents) globalement pour un scoring plus cohérent, ou localement, pour une latence plus faible. La valeur par défaut est « local ». Utilisez « global » pour agréger les statistiques de scoring à l’échelle mondiale avant de scorer. L’utilisation des statistiques de scoring global peut augmenter la latence des requêtes de recherche. Les valeurs possibles sont les suivantes : « local », « global ».

session_id
str

Valeur à utiliser pour créer une session collante, ce qui peut vous aider à obtenir des résultats plus cohérents. Tant que le même sessionId est utilisé, une tentative optimale est effectuée pour cibler le même réplica ensemble. Méfiez-vous que la réutilisation répétée des mêmes valeurs sessionID peut interférer avec l’équilibrage de charge des requêtes entre les réplicas et nuire aux performances du service de recherche. La valeur utilisée comme sessionId ne peut pas commencer par un caractère « _ ».

semantic_error_mode
str ou SemanticErrorMode

Permet à l’utilisateur de choisir si un appel sémantique doit échouer complètement (comportement par défaut/actuel) ou de retourner des résultats partiels. Les valeurs connues sont : « partial » et « fail ».

semantic_max_wait_in_milliseconds
int

Permet à l’utilisateur de définir une limite supérieure sur le temps nécessaire à l’enrichissement sémantique pour terminer le traitement avant l’échec de la demande.

vector_queries
list[VectorQuery]

Paramètres de requête pour les requêtes de recherche vectorielle et hybride.

vector_filter_mode
str ou VectorFilterMode

Détermine si les filtres sont appliqués avant ou après l’exécution de la recherche vectorielle. La valeur par défaut est « preFilter ». Les valeurs connues sont les suivantes : « postFilter » et « preFilter ».

Type de retour

SearchItemPaged[dict]

Exemples

Obtenir les facettes des résultats de la recherche.


   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

Obtenez les résultats des suggestions de recherche à partir de l’index de recherche Azure.

caractère et pas plus de 100 caractères. :p aram str suggester_name : Obligatoire. Nom du suggesteur tel que spécifié dans la collection suggesteurs qui fait partie de la définition d’index. :mot clé str filter : expression OData qui filtre les documents pris en compte pour les suggestions. :mot clé bool use_fuzzy_matching : valeur indiquant s’il faut utiliser la correspondance approximative pour les suggestions

base de données élastique La valeur par défaut est false. Lorsqu’elle est définie sur true, la requête trouve des termes même s’il existe un caractère remplacé ou manquant dans le texte de recherche. Bien que cela offre une meilleure expérience dans certains scénarios, il s’agit d’un coût de performances, car les requêtes de suggestions approximatives sont plus lentes et consomment plus de ressources.

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]

Paramètres

highlight_post_tag
str

Balise de chaîne ajoutée aux surbrillances d’accès. Doit être défini avec highlightPreTag. En cas d’omission, la mise en surbrillance des suggestions est désactivée.

highlight_pre_tag
str

Balise de chaîne qui est ajoutée pour atteindre les surbrillances. Doit être défini avec highlightPostTag. En cas d’omission, la mise en surbrillance des suggestions est désactivée.

minimum_coverage
float

Nombre compris entre 0 et 100 indiquant le pourcentage de l’index qui doit être couvert par une requête de suggestions pour que la requête soit signalée comme une réussite. Ce paramètre peut être utile pour garantir la disponibilité de la recherche, même pour les services avec un seul réplica. La valeur par défaut est 80.

order_by
list[str]

Liste des expressions OData $orderby selon lesquelles trier les résultats. Chaque expression peut être un nom de champ ou un appel aux fonctions geo.distance() ou search.score(). Chaque expression peut être suivie d’asc pour indiquer l’ordre croissant, ou de desc pour indiquer la décroissante. La valeur par défaut est l'ordre croissant. Les liens seront rompus par les scores de correspondance des documents. Si aucune $orderby n’est spécifiée, l’ordre de tri par défaut est décroissant par score de correspondance de document. Il peut y avoir au maximum 32 clauses $orderby.

search_fields
list[str]

Liste des noms de champs à rechercher pour le texte de recherche spécifié. Les champs cibles doivent être inclus dans le suggesteur spécifié.

select
list[str]

Liste des champs à récupérer. S’il n’est pas spécifié, seul le champ clé est inclus dans les résultats.

top
int

Nombre de suggestions à récupérer. La valeur doit être un nombre compris entre 1 et 100. La valeur par défaut est 5.

Retours

Liste des documents.

Type de retour

list[dict]

Exemples

Obtenez des suggestions de recherche.


   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

Chargez des documents dans l’index de recherche Azure.

Une action de chargement est similaire à une « upsert » où le document est inséré s’il est nouveau et mis à jour/remplacé s’il existe. Tous les champs sont remplacés dans le cas de mise à jour.

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

Paramètres

documents
list[dict]
Obligatoire

Liste des documents à charger.

Retours

Liste d’IndexingResult

Type de retour

list[IndexingResult]

Exemples

Charger de nouveaux documents dans un index


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