SearchClient Classe

  • Riferimento

Un client per interagire con un indice di ricerca di Azure esistente.

Ereditarietà
azure.search.documents._headers_mixin.HeadersMixin
SearchClient

Costruttore

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

Parametri

endpoint
str
Necessario

Endpoint URL di un servizio di ricerca di Azure

index_name
str
Necessario

Nome dell'indice da connettere

credential
AzureKeyCredential oppure TokenCredential
Necessario

Credenziali per autorizzare le richieste client di ricerca

api_version
str

Versione dell'API di ricerca da usare per le richieste.

audience
str

imposta Il gruppo di destinatari da usare per l'autenticazione con Azure Active Directory (AAD). Il gruppo di destinatari non viene considerato quando si usa una chiave condivisa. Se il pubblico non viene fornito, verrà assunto il pubblico del cloud.

Esempio

Creazione di SearchClient con una chiave 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))

Metodi

autocomplete

Ottenere i risultati del completamento automatico della ricerca dall'indice di ricerca di Azure.

raccolta che fa parte della definizione dell'indice. Modalità parola chiave: specifica la modalità di completamento automatico. Il valore predefinito è "oneTerm". Uso

"twoTerms" per ottenere shingles e "oneTermWithContext" per usare il contesto corrente, generando termini completati automaticamente. I valori possibili includono: 'oneTerm', 'twoTerms', 'oneTermWithContext'.
close

Chiudere la SearchClient sessione.
delete_documents

Eliminare documenti dall'indice di ricerca di Azure

Elimina rimuove il documento specificato dall'indice. Qualsiasi campo specificato in un'operazione di eliminazione, diverso dal campo chiave, verrà ignorato. Se si vuole rimuovere un singolo campo da un documento, usare merge_documents invece e impostare il campo in modo esplicito su Nessuno.

Le operazioni di eliminazione sono idempotenti. In altre parole, anche se non esiste una chiave del documento nell'indice, il tentativo di eseguire un'operazione di eliminazione con quella chiave produrrà un codice di stato 200.
get_document

Recuperare un documento dall'indice di ricerca di Azure in base alla chiave.
get_document_count

Restituisce il numero di documenti nell'indice di ricerca di Azure.
index_documents

Specificare un'operazione del documento da eseguire come batch.

:Genera RequestEntityTooLargeError
merge_documents

Unire i documenti in ai documenti esistenti nell'indice di ricerca di Azure.

Aggiorna un documento esistente con i campi specificati. Se il documento non esiste, l'unione ha esito negativo. I campi specificati in un'azione di unione sostituiscono i campi esistenti nel documento. Questo vale anche per le raccolte di tipi primitivi e complessi.
merge_or_upload_documents

Unire i documenti nei documenti esistenti nell'indice di ricerca di Azure o caricarli se non esistono ancora.

Questa azione si comporta come merge_documents se un documento con la chiave specificata esiste già nell'indice. Se il documento non esiste, si comporta come upload_documents con un nuovo documento.
search

Cercare l'indice di ricerca di Azure per i documenti.
suggest

Ottenere i risultati dei suggerimenti di ricerca dall'indice di ricerca di Azure.

carattere e non più di 100 caratteri. :p aram str suggester_name: obbligatorio. Nome del suggeritore come specificato nell'insieme di suggeritori che fa parte della definizione dell'indice. Filtro str :keyword: espressione OData che filtra i documenti considerati per i suggerimenti. :keyword bool use_fuzzy_matching: valore che indica se usare la corrispondenza fuzzy per i suggerimenti

. L'impostazione predefinita è false. Se impostato su true, la query troverà termini anche se nel testo di ricerca è presente un carattere sostituito o mancante. Anche se questo offre un'esperienza migliore in alcuni scenari, si tratta di un costo di prestazioni come le query di suggerimenti fuzzy sono più lente e utilizzano più risorse.
upload_documents

Caricare documenti nell'indice di ricerca di Azure.

Un'azione di caricamento è simile a un "upsert" in cui il documento verrà inserito se è nuovo e aggiornato/sostituito se esiste. Tutti i campi vengono sostituiti nel caso di aggiornamento.

autocomplete

Ottenere i risultati del completamento automatico della ricerca dall'indice di ricerca di Azure.

raccolta che fa parte della definizione dell'indice. Modalità parola chiave: specifica la modalità di completamento automatico. Il valore predefinito è "oneTerm". Uso

"twoTerms" per ottenere shingles e "oneTermWithContext" per usare il contesto corrente, generando termini completati automaticamente. I valori possibili includono: '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]

Parametri

filter
str

Espressione OData che filtra i documenti usati per produrre termini completati per il risultato completamento automatico.

use_fuzzy_matching
bool

Valore che indica se usare la corrispondenza fuzzy per la query di completamento automatico. L'impostazione predefinita è false. Se impostato su true, la query troverà termini anche se nel testo di ricerca è presente un carattere sostituito o mancante. Anche se questo offre un'esperienza migliore in alcuni scenari, si tratta di un costo di prestazioni come query di completamento automatico fuzzy sono più lente e utilizzano più risorse.

highlight_post_tag
str

Tag stringa accodato alle evidenziazioni di hit. Deve essere impostato con highlightPreTag. Se omesso, l'evidenziazione dei colpi è disabilitata.

highlight_pre_tag
str

Tag stringa prependato per l'evidenziazione. Deve essere impostato con highlightPostTag. Se omesso, l'evidenziazione dei colpi è disabilitata.

minimum_coverage
float

Numero compreso tra 0 e 100 che indica la percentuale dell'indice che deve essere coperta da una query di completamento automatico affinché la query venga segnalata come esito positivo. Questo parametro può essere utile per garantire la disponibilità di ricerca anche per i servizi con una sola replica. Il valore predefinito è 80.

search_fields
list[str]

Elenco di nomi di campi da considerare quando si esegue una query per i termini completati automaticamente. I campi di destinazione devono essere inclusi nel suggerimento specificato.

top
int

Numero di termini completati automaticamente da recuperare. Deve essere un valore compreso tra 1 e 100. Il valore predefinito è 5.

Tipo restituito

list[dict]

Esempio

Ottenere un completamento automatico.


   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

Chiudere la SearchClient sessione.

close() -> None

delete_documents

Eliminare documenti dall'indice di ricerca di Azure

Elimina rimuove il documento specificato dall'indice. Qualsiasi campo specificato in un'operazione di eliminazione, diverso dal campo chiave, verrà ignorato. Se si vuole rimuovere un singolo campo da un documento, usare merge_documents invece e impostare il campo in modo esplicito su Nessuno.

Le operazioni di eliminazione sono idempotenti. In altre parole, anche se non esiste una chiave del documento nell'indice, il tentativo di eseguire un'operazione di eliminazione con quella chiave produrrà un codice di stato 200.

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

Parametri

documents
list[dict]
Necessario

Elenco di documenti da eliminare.

Restituisce

Elenco di IndexingResult

Tipo restituito

list[IndexingResult]

Esempio

Eliminare documenti esistenti in un indice


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

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

get_document

Recuperare un documento dall'indice di ricerca di Azure in base alla chiave.

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

Parametri

key
str
Necessario

Valore della chiave primaria per il documento da recuperare

selected_fields
list[str]
Necessario

elenco di campi consentiti da includere nei risultati

Restituisce

Documento archiviato nell'indice di ricerca di Azure

Tipo restituito

dict

Esempio

Ottenere un documento specifico dall'indice di ricerca.


   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

Restituisce il numero di documenti nell'indice di ricerca di Azure.

get_document_count(**kwargs: Any) -> int

Restituisce

Numero di documenti nell'indice

Tipo restituito

int

index_documents

Specificare un'operazione del documento da eseguire come batch.

:Genera RequestEntityTooLargeError

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

Parametri

batch
IndexDocumentsBatch
Necessario

Batch di operazioni del documento da eseguire.

Restituisce

Elenco di IndexingResult

Tipo restituito

list[IndexingResult]

merge_documents

Unire i documenti in ai documenti esistenti nell'indice di ricerca di Azure.

Aggiorna un documento esistente con i campi specificati. Se il documento non esiste, l'unione ha esito negativo. I campi specificati in un'azione di unione sostituiscono i campi esistenti nel documento. Questo vale anche per le raccolte di tipi primitivi e complessi.

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

Parametri

documents
list[dict]
Necessario

Elenco di documenti da unire.

Restituisce

Elenco di IndexingResult

Tipo restituito

list[IndexingResult]

Esempio

Unire i campi in documenti esistenti in un indice


   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

Unire i documenti nei documenti esistenti nell'indice di ricerca di Azure o caricarli se non esistono ancora.

Questa azione si comporta come merge_documents se un documento con la chiave specificata esiste già nell'indice. Se il documento non esiste, si comporta come upload_documents con un nuovo documento.

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

Parametri

documents
list[dict]
Necessario

Elenco di documenti da unire o caricare.

Restituisce

Elenco di IndexingResult

Tipo restituito

list[IndexingResult]

Cercare l'indice di ricerca di Azure per i documenti.

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]

Parametri

search_text
str
Necessario

Espressione di query di ricerca full-text; Usare "*" o omettere questo parametro per corrispondere a tutti i documenti.

include_total_count
bool

Valore che specifica se recuperare il conteggio totale dei risultati. L'impostazione predefinita è false. L'impostazione di questo valore su true potrebbe avere un impatto sulle prestazioni. Si noti che il conteggio restituito è un'approssimazione.

facets
list[str]

Elenco di espressioni facet da applicare alla query di ricerca. Ogni espressione facet contiene un nome di campo, facoltativamente seguito da un elenco delimitato da virgole di coppie name:value.

filter
str

Espressione OData $filter da applicare alla query di ricerca.

highlight_fields
str

Elenco delimitato da virgole di nomi di campi da usare per le evidenziazioni di hit. Solo i campi ricercabili possono essere usati per l'evidenziazione di hit.

highlight_post_tag
str

Tag stringa accodato alle evidenziazioni di hit. Deve essere impostato con highlightPreTag. Il valore predefinito è .

highlight_pre_tag
str

Tag stringa prependato per l'evidenziazione. Deve essere impostato con highlightPostTag. Il valore predefinito è .

minimum_coverage
float

Numero compreso tra 0 e 100 che indica la percentuale dell'indice che deve essere coperta da una query di ricerca per poter segnalare la query come esito positivo. Questo parametro può essere utile per garantire la disponibilità di ricerca anche per i servizi con una sola replica. Il valore predefinito è 100.

order_by
list[str]

Elenco di espressioni di $orderby OData in base al quale ordinare i risultati. Ogni espressione può essere un nome di campo o una chiamata alle funzioni geo.distance() o search.score(). Ogni espressione può essere seguita da asc per indicare l'crescente e desc per indicare la desc decrescente. Per impostazione predefinita, l'ordinamento è crescente. Le situazioni di parità di priorità vengono risolte in base ai punteggi di corrispondenza dei documenti. Se non viene specificato orderBy, l'ordine di ordinamento predefinito è decrescente in base al punteggio di corrispondenza del documento. Possono essere presenti al massimo 32 clausole $orderby.

query_type
str oppure QueryType

Valore che specifica la sintassi della query di ricerca. Il valore predefinito è "semplice". Usare "full" se la query usa la sintassi della query Lucene. I valori possibili includono: 'simple', 'full', "semantic".

scoring_parameters
list[str]

Elenco dei valori dei parametri da usare nelle funzioni di assegnazione dei punteggi (ad esempio, referencePointParameter) usando i valori dei nomi di formato. Ad esempio, se il profilo di assegnazione dei punteggi definisce una funzione con un parametro denominato 'mylocation' la stringa di parametro sarebbe "mylocation-122.2.44.8" (senza virgolette).

scoring_profile
str

Nome di un profilo di punteggio da usare per la valutazione di punteggi di corrispondenza per i documenti corrispondenti, in modo da ordinare i risultati.

search_fields
list[str]

Elenco di nomi di campi a cui definire l'ambito della ricerca full-text. Quando si usa la ricerca in campi (fieldName:searchExpression) in una query Lucene completa, i nomi di campo di ogni espressione di ricerca a campi hanno la precedenza su tutti i nomi di campo elencati in questo parametro.

search_mode
str oppure SearchMode

Valore che specifica se qualsiasi o tutti i termini di ricerca devono essere corrispondenti per contare il documento come corrispondenza. I valori possibili includono: 'any', 'all'.

query_answer
str oppure QueryAnswerType

Questo parametro è valido solo se il tipo di query è "semantico". Se impostata, la query restituisce le risposte estratte dai passaggi chiave nei documenti classificati più alti. I valori possibili includono: "nessuno", "estratto".

query_answer_count
int

Questo parametro è valido solo se il tipo di query è 'semantico' e la risposta di query è 'estratto'. Configura il numero di risposte restituite. Il numero predefinito è 1.

query_answer_threshold
float

Questo parametro è valido solo se il tipo di query è 'semantico' e la risposta di query è 'estratto'. Configura il numero di soglia di attendibilità. Il conteggio predefinito è 0,7.

query_caption
str oppure QueryCaptionType

Questo parametro è valido solo se il tipo di query è "semantico". Se impostata, la query restituisce didascalie estratte dai passaggi chiave nei documenti classificati più alti. Il valore predefinito è "Nessuna". I valori possibili includono: "nessuno", "estratto".

query_caption_highlight_enabled
bool

Questo parametro è valido solo se il tipo di query è 'semantico' quando la query didascalia è impostata su 'estratto'. Determina se l'evidenziazione è abilitata. Il valore predefinito è "true".

semantic_configuration_name
str

Nome della configurazione semantica che verrà usata durante l'elaborazione dei documenti per le query di tipo semantica.

select
list[str]

Elenco di campi da recuperare. Se non è specificato, vengono inclusi tutti i campi contrassegnati come recuperabili nello schema.

skip
int

Numero di risultati della ricerca da ignorare. Questo valore non può essere maggiore di 100.000. Se è necessario analizzare i documenti in sequenza, ma non è possibile usare $skip a causa di questa limitazione, è consigliabile usare $orderby su una chiave completamente ordinata e $filter con una query di intervallo.

top
int

Numero di risultati della ricerca da recuperare. Questa operazione può essere usata in combinazione con $skip per implementare il paging lato client dei risultati della ricerca. Se i risultati vengono troncati a causa del paging lato server, la risposta includerà un token di continuazione che può essere usato per inviare un'altra richiesta di ricerca per la pagina successiva dei risultati.

scoring_statistics
str oppure ScoringStatistics

Valore che specifica se si desidera calcolare le statistiche di assegnazione dei punteggi (ad esempio la frequenza del documento) a livello globale per un punteggio più coerente o locale, per una latenza inferiore. Il valore predefinito è "local". Usare "globale" per aggregare le statistiche di assegnazione dei punteggi a livello globale prima di assegnare punteggi. L'uso delle statistiche di assegnazione dei punteggi globali può aumentare la latenza delle query di ricerca. I valori possibili includono: "local", "global".

session_id
str

Valore da usare per creare una sessione sticky, che può aiutare a ottenere risultati più coerenti. Purché venga usato lo stesso sessionId, verrà eseguito un tentativo di sforzo ottimale per indirizzare lo stesso set di repliche. Tenere presente che il riutilizzo degli stessi valori sessionID può interferire ripetutamente con il bilanciamento del carico delle richieste tra repliche e influire negativamente sulle prestazioni del servizio di ricerca. Il valore usato come sessionId non può iniziare con un carattere '_'.

semantic_error_mode
str oppure SemanticErrorMode

Consente all'utente di scegliere se una chiamata semantica deve avere esito negativo completamente (comportamento predefinito/corrente) o restituire risultati parziali. I valori noti sono: "parziale" e "fail".

semantic_max_wait_in_milliseconds
int

Consente all'utente di impostare un limite superiore per la quantità di tempo necessario per l'arricchimento semantico per completare l'elaborazione prima che la richiesta non riesca.

vector_queries
list[VectorQuery]

Parametri di query per query di ricerca ibrida e vettore.

vector_filter_mode
str oppure VectorFilterMode

Determina se i filtri vengono applicati prima o dopo l'esecuzione della ricerca del vettore. Il valore predefinito è 'preFilter'. I valori noti sono: "postFilter" e "preFilter".

Tipo restituito

SearchItemPaged[dict]

Esempio

Ottenere i facet dei risultati della ricerca.


   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

Ottenere i risultati dei suggerimenti di ricerca dall'indice di ricerca di Azure.

carattere e non più di 100 caratteri. :p aram str suggester_name: obbligatorio. Nome del suggeritore come specificato nell'insieme di suggeritori che fa parte della definizione dell'indice. Filtro str :keyword: espressione OData che filtra i documenti considerati per i suggerimenti. :keyword bool use_fuzzy_matching: valore che indica se usare la corrispondenza fuzzy per i suggerimenti

. L'impostazione predefinita è false. Se impostato su true, la query troverà termini anche se nel testo di ricerca è presente un carattere sostituito o mancante. Anche se questo offre un'esperienza migliore in alcuni scenari, si tratta di un costo di prestazioni come le query di suggerimenti fuzzy sono più lente e utilizzano più risorse.

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]

Parametri

highlight_post_tag
str

Tag stringa accodato alle evidenziazioni di hit. Deve essere impostato con highlightPreTag. Se omesso, l'evidenziazione dei suggerimenti è disabilitata.

highlight_pre_tag
str

Tag stringa prependato per l'evidenziazione. Deve essere impostato con highlightPostTag. Se omesso, l'evidenziazione dei suggerimenti è disabilitata.

minimum_coverage
float

Numero compreso tra 0 e 100 che indica la percentuale dell'indice che deve essere coperta da una query di suggerimenti per poter segnalare la query come esito positivo. Questo parametro può essere utile per garantire la disponibilità di ricerca anche per i servizi con una sola replica. Il valore predefinito è 80.

order_by
list[str]

Elenco di espressioni di $orderby OData in base al quale ordinare i risultati. Ogni espressione può essere un nome di campo o una chiamata alle funzioni geo.distance() o search.score(). Ogni espressione può essere seguita da asc per indicare l'crescente o il desc per indicare la decrescente. Per impostazione predefinita, l'ordinamento è crescente. Le situazioni di parità di priorità vengono risolte in base ai punteggi di corrispondenza dei documenti. Se non viene specificata alcuna $orderby, l'ordine di ordinamento predefinito è decrescente in base al punteggio di corrispondenza del documento. Possono essere presenti al massimo 32 clausole $orderby.

search_fields
list[str]

Elenco dei nomi dei campi da cercare il testo di ricerca specificato. I campi di destinazione devono essere inclusi nel suggerimento specificato.

select
list[str]

Elenco di campi da recuperare. Se non specificato, solo il campo chiave verrà incluso nei risultati.

top
int

Numero di suggerimenti da recuperare. Il valore deve essere un numero compreso tra 1 e 100. Il valore predefinito è 5.

Restituisce

Elenco di documenti.

Tipo restituito

list[dict]

Esempio

Ottenere suggerimenti per la ricerca.


   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

Caricare documenti nell'indice di ricerca di Azure.

Un'azione di caricamento è simile a un "upsert" in cui il documento verrà inserito se è nuovo e aggiornato/sostituito se esiste. Tutti i campi vengono sostituiti nel caso di aggiornamento.

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

Parametri

documents
list[dict]
Necessario

Elenco di documenti da caricare.

Restituisce

Elenco di IndexingResult

Tipo restituito

list[IndexingResult]

Esempio

Caricare nuovi documenti in un indice


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