SearchClient Classe
Un client pour interagir avec un index recherche Azure existant.
- Héritage
-
azure.search.documents._headers_mixin.HeadersMixinSearchClient
Constructeur
SearchClient(endpoint: str, index_name: str, credential: AzureKeyCredential | AsyncTokenCredential, **kwargs: Any)Paramètres
- credential
- AzureKeyCredential ou AsyncTokenCredential
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.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))
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 Recherche Azure. |
| suggest |
Obtenez les résultats des suggestions de recherche à partir de l’index recherche Azure. et pas plus de 100 caractères. :p aram str suggester_name : Obligatoire. Nom du suggesteur tel que spécifié dans la collection de 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. 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 suggestions approximatives sont plus lentes et consomment plus de ressources. |
| upload_documents |
Chargez des documents dans l’index recherche Azure. Une action de chargement est similaire à un « 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 ».
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]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.
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
Exemples
Obtenir une saisie semi-automatique.
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
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.
async delete_documents(documents: List[Dict], **kwargs: Any) -> List[IndexingResult]Paramètres
Retours
Liste d’IndexingResult
Type de retour
Exemples
Supprimer des documents existants dans un index
result = await search_client.upload_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é.
async get_document(key: str, selected_fields: List[str] | None = None, **kwargs: Any) -> DictParamètres
Retours
Document qui correspond à la clé spécifiée
Type de retour
Exemples
Obtenez un document spécifique à partir de l’index de recherche.
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
Retourne le nombre de documents dans l’index recherche Azure.
async get_document_count(**kwargs: Any) -> intRetours
Nombre de documents dans l’index
Type de retour
index_documents
Spécifiez une opération de document à effectuer en tant que lot.
:Soulève RequestEntityTooLargeError
async index_documents(batch: IndexDocumentsBatch, **kwargs: Any) -> List[IndexingResult]Paramètres
Retours
Liste d’IndexingResult
Type de retour
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.
async merge_documents(documents: List[Dict], **kwargs: Any) -> List[IndexingResult]Paramètres
Retours
Liste d’IndexingResult
Type de retour
Exemples
Fusionner des champs dans des documents existants dans un index
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
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.
async merge_or_upload_documents(documents: List[Dict], **kwargs: Any) -> List[IndexingResult]Paramètres
Retours
Liste d’IndexingResult
Type de retour
search
Recherchez des documents dans l’index Recherche 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]Paramètres
- search_text
- str
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.
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.
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.
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'.
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.
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 champs 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 en tant que correspondance. Les valeurs possibles sont les suivantes : « 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 de clés dans les documents les plus classés. Les valeurs possibles sont les suivantes : « none », « extractif ».
- query_answer_count
- int
Ce paramètre est valide uniquement si le type de requête est « sémantique » et la réponse de 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 est valide uniquement si le type de requête est « sémantique » et la réponse de 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 des légendes extraites des passages clés dans les documents classés les plus élevés. 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 la légende de requête est définie 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.
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 devez 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 les 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 le scoring. L’utilisation de statistiques de scoring globales 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, qui peut vous aider à obtenir des résultats plus cohérents. Tant que le même sessionId est utilisé, une tentative de la meilleure façon est effectuée pour cibler le même réplica défini. Veillez à ce que la réutilisation répétée des mêmes valeurs sessionID puisse 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 les suivantes : « 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 requête.
- 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 « postFilter » et « preFilter ».
Retours
Liste de documents (dicts) correspondant aux critères de recherche spécifiés.
Type de retour
Exemples
Obtenir les facettes des résultats de la recherche.
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
Obtenez les résultats des suggestions de recherche à partir de l’index recherche Azure.
et pas plus de 100 caractères. :p aram str suggester_name : Obligatoire. Nom du suggesteur tel que spécifié dans la collection de 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. 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 suggestions approximatives sont plus lentes et consomment plus de ressources.
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]Paramètres
- highlight_post_tag
- str
Balise de chaîne qui est 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 précédée pour atteindre les surlignages. 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 une seule réplica. La valeur par défaut est 80.
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 d’asc pour indiquer l’ordre croissant ou de desc pour indiquer une valeur 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.
Liste des noms de champs à rechercher pour le texte de recherche spécifié. Les champs cibles doivent être inclus dans le suggesteur spécifié.
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
Exemples
Obtenez des suggestions de recherche.
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
Chargez des documents dans l’index recherche Azure.
Une action de chargement est similaire à un « 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.
async upload_documents(documents: List[Dict], **kwargs: Any) -> List[IndexingResult]Paramètres
Retours
Liste d’IndexingResult
Type de retour
Exemples
Charger de nouveaux documents dans un index
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))
Azure SDK for Python