SearchClient Clase

Un cliente para interactuar con un índice de Azure Search existente.

Herencia

azure.search.documents._headers_mixin.HeadersMixin

SearchClient

Constructor

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

Parámetros

endpoint

str

Requerido

Punto de conexión de dirección URL de un servicio de Azure Search

index_name

str

Requerido

Nombre del índice al que se va a conectar.

credential

AzureKeyCredential o AsyncTokenCredential

Requerido

Una credencial para autorizar solicitudes de cliente de búsqueda

api_version

str

La versión de Search API que se va a usar para las solicitudes.

audience

str

establece la audiencia que se va a usar para la autenticación con Azure Active Directory (AAD). La audiencia no se considera cuando se usa una clave compartida. Si no se proporciona audiencia, se supone que la audiencia de la nube pública.

Ejemplos

Creación de SearchClient con una clave de 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étodos

autocomplete	Obtenga los resultados de autocompletar de búsqueda del índice de Azure Search. colección que forma parte de la definición de índice. :keyword mode: especifica el modo para Autocompletar. El valor predeterminado es "oneTerm". Uso 'twoTerms' para obtener shingles y 'oneTermWithContext' para usar el contexto actual mientras se generan términos autocompletados. Entre los valores posibles se incluyen: "oneTerm", "twoTerms", "oneTermWithContext".
close	Cierre la SearchClient sesión.
delete_documents	Eliminación de documentos del índice de Azure Search Eliminar quita el documento especificado del índice. Cualquier campo que especifique en una operación de eliminación, que no sea el campo de clave, se omitirá. Si desea quitar un campo individual de un documento, use merge_documents en su lugar y establezca el campo explícitamente en Ninguno. Las operaciones de eliminación son idempotentes. Es decir, incluso si no existe una clave de documento en el índice, intentar una operación de eliminación con esa clave producirá un código de estado 200.
get_document	Recupere un documento del índice de Azure Search por su clave.
get_document_count	Devuelve el número de documentos en el índice de Azure Search.
index_documents	Especifique una operación de documento que se va a realizar como un lote. :Plantea RequestEntityTooLargeError
merge_documents	Combinar documentos en documentos existentes en el índice de Azure Search. La combinación actualiza un documento existente con los campos especificados. Si el documento no existe, se producirá un error en la combinación. Cualquier campo que se especifica en una combinación reemplazará al campo existente en el documento. Esto también se aplica a colecciones de tipos primitivos y complejos.
merge_or_upload_documents	Combine documentos en en documentos existentes en el índice de Azure Search o cárguelos si aún no existen. Esta acción se comporta como merge_documents si ya existe un documento con la clave especificada en el índice. Si el documento no existe, se comporta como upload_documents con un nuevo documento.
search	Busque documentos en el índice de Azure Search.
suggest	Obtenga los resultados de sugerencias de búsqueda del índice de Azure Search. carácter y no más de 100 caracteres. :p aram str suggester_name: Obligatorio. Nombre del proveedor de sugerencias tal y como se especifica en la colección suggesters que forma parte de la definición del índice. :keyword str filter: expresión OData que filtra los documentos que se consideran para obtener sugerencias. :keyword bool use_fuzzy_matching: valor que indica si se debe usar la coincidencia aproximada para las sugerencias. . El valor predeterminado es False. Cuando se establece en true, la consulta encontrará términos incluso si hay un carácter sustituido o que falta en el texto de búsqueda. Aunque esto proporciona una mejor experiencia en algunos escenarios, se produce un costo de rendimiento, ya que las consultas de sugerencias aproximadas son más lentas y consumen más recursos.
upload_documents	Cargue documentos en el índice de Azure Search. Una acción de carga es similar a una "upsert" donde se insertará el documento si es nuevo y actualizado o reemplazado si existe. Todos los campos se reemplazan en el caso de actualización.

autocomplete

Obtenga los resultados de autocompletar de búsqueda del índice de Azure Search.

colección que forma parte de la definición de índice. :keyword mode: especifica el modo para Autocompletar. El valor predeterminado es "oneTerm". Uso

'twoTerms' para obtener shingles y 'oneTermWithContext' para usar el contexto actual mientras se generan términos autocompletados. Entre los valores posibles se incluyen: "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]

Parámetros

filter

str

Expresión de OData que filtra los documentos usados para generar términos completados para el resultado autocompletar.

use_fuzzy_matching

bool

Valor que indica si se va a usar la coincidencia aproximada para la consulta de autocompletar. El valor predeterminado es False. Cuando se establece en true, la consulta encontrará términos incluso si hay un carácter sustituido o ausente en el texto de búsqueda. Aunque esto proporciona una mejor experiencia en algunos escenarios, conlleva un costo de rendimiento, ya que las consultas de autocompletar aproximadas son más lentas y consumen más recursos.

highlight_post_tag

str

Etiqueta de cadena que se anexa para alcanzar los resaltados. Debe establecerse con highlightPreTag. Si se omite, el resaltado de aciertos está deshabilitado.

highlight_pre_tag

str

Etiqueta de cadena que se antepone a los resaltados. Debe establecerse con highlightPostTag. Si se omite, el resaltado de aciertos está deshabilitado.

minimum_coverage

float

Número comprendido entre 0 y 100 que indica el porcentaje del índice que debe estar cubierto por una consulta de autocompletar para que la consulta se notifique como correcta. Este parámetro puede ser útil para garantizar la disponibilidad de búsqueda incluso para los servicios con una sola réplica. El valor predeterminado es 80.

search_fields

list[str]

Lista de nombres de campo que se deben tener en cuenta al consultar los términos de autocompletar. Los campos de destino deben incluirse en el proveedor de sugerencias especificado.

top

int

Número de términos completados automáticamente que se van a recuperar. Debe ser un valor entre 1 y 100. El valor predeterminado es 5.

Tipo de valor devuelto

list[Dict]

Ejemplos

Obtiene las finalizaciones automáticas.

   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

Cierre la SearchClient sesión.

async close() -> None

Devoluciones

None

Tipo de valor devuelto

None

delete_documents

Eliminación de documentos del índice de Azure Search

Eliminar quita el documento especificado del índice. Cualquier campo que especifique en una operación de eliminación, que no sea el campo de clave, se omitirá. Si desea quitar un campo individual de un documento, use merge_documents en su lugar y establezca el campo explícitamente en Ninguno.

Las operaciones de eliminación son idempotentes. Es decir, incluso si no existe una clave de documento en el índice, intentar una operación de eliminación con esa clave producirá un código de estado 200.

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

Parámetros

documents

list[dict]

Requerido

Lista de documentos que se van a eliminar.

Devoluciones

Lista de IndexingResult

Tipo de valor devuelto

list[IndexingResult]

Ejemplos

Eliminación de documentos existentes en un índice

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

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

get_document

Recupere un documento del índice de Azure Search por su clave.

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

Parámetros

key

str

Requerido

Valor de clave principal del documento que se va a recuperar

selected_fields

list[str]

Requerido

una lista de campos permitidos que se van a incluir en los resultados

Devoluciones

Documento que coincide con la clave especificada

Tipo de valor devuelto

dict

Ejemplos

Obtenga un documento específico del índice de búsqueda.

   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

Devuelve el número de documentos en el índice de Azure Search.

async get_document_count(**kwargs: Any) -> int

Devoluciones

Recuento de documentos en el índice

Tipo de valor devuelto

int

index_documents

Especifique una operación de documento que se va a realizar como un lote.

:Plantea RequestEntityTooLargeError

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

Parámetros

batch

IndexDocumentsBatch

Requerido

Un lote de operaciones de documento que se van a realizar.

Devoluciones

Lista de IndexingResult

Tipo de valor devuelto

list[IndexingResult]

merge_documents

Combinar documentos en documentos existentes en el índice de Azure Search.

La combinación actualiza un documento existente con los campos especificados. Si el documento no existe, se producirá un error en la combinación. Cualquier campo que se especifica en una combinación reemplazará al campo existente en el documento. Esto también se aplica a colecciones de tipos primitivos y complejos.

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

Parámetros

documents

list[dict]

Requerido

Lista de documentos que se van a combinar.

Devoluciones

Lista de IndexingResult

Tipo de valor devuelto

list[IndexingResult]

Ejemplos

Combinar campos en documentos existentes en un índice

   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

Combine documentos en en documentos existentes en el índice de Azure Search o cárguelos si aún no existen.

Esta acción se comporta como merge_documents si ya existe un documento con la clave especificada en el índice. Si el documento no existe, se comporta como upload_documents con un nuevo documento.

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

Parámetros

documents

list[dict]

Requerido

Lista de documentos que se van a combinar o cargar.

Devoluciones

Lista de IndexingResult

Tipo de valor devuelto

list[IndexingResult]

search

Busque documentos en el índice de 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]

Parámetros

search_text

str

Requerido

Expresión de consulta de búsqueda de texto completo; Use "*" o omita este parámetro para que coincida con todos los documentos.

include_total_count

bool

Valor que especifica si se va a capturar el recuento total de resultados. El valor predeterminado es False. Establecer este valor en true puede tener un impacto en el rendimiento. Tenga en cuenta que el número devuelto será una aproximación.

facets

list[str]

Lista de expresiones de faceta que se van a aplicar a la consulta de búsqueda. Cada expresión de faceta contiene un nombre de campo, seguido opcionalmente de una lista separada por comas de pares nombre:valor.

filter

str

La expresión $filter OData que se va a aplicar a la consulta de búsqueda.

highlight_fields

str

Lista separada por comas de nombres de campo que se usarán para los resaltados de aciertos. Solo se pueden usar campos que se pueden buscar para el resaltado de aciertos.

highlight_post_tag

str

Etiqueta de cadena que se anexa para alcanzar los resaltados. Debe establecerse con highlightPreTag. El valor predeterminado es .

highlight_pre_tag

str

Etiqueta de cadena que se antepone a los resaltados. Debe establecerse con highlightPostTag. El valor predeterminado es .

minimum_coverage

float

Número comprendido entre 0 y 100 que indica el porcentaje del índice que debe estar cubierto por una consulta de búsqueda para que la consulta se notifique como correcta. Este parámetro puede ser útil para garantizar la disponibilidad de búsqueda incluso para los servicios con una sola réplica. El valor predeterminado es 100.

order_by

list[str]

Lista de expresiones de $orderby de OData por las que se ordenan los resultados. Cada expresión puede ser un nombre de campo o una llamada a las funciones geo.distance() o search.score(). Cada expresión puede ir seguida de asc para indicar ascendente y desc para indicar descendente. El valor predeterminado es ascendente. Los empates se resolverán por la puntuación de coincidencia de los documentos. Si no se especifica ningún OrderBy, el criterio de ordenación predeterminado es descendente por puntuación de coincidencia de documento. Puede haber como máximo 32 cláusulas de $orderby.

query_type

str o QueryType

Valor que especifica la sintaxis de la consulta de búsqueda. El valor predeterminado es "simple". Use "full" si la consulta usa la sintaxis de consulta de Lucene. Entre los valores posibles se incluyen: "simple", "full", "semantic".

scoring_parameters

list[str]

Lista de valores de parámetro que se van a usar en las funciones de puntuación (por ejemplo, referencePointParameter) mediante el formato name-values. Por ejemplo, si el perfil de puntuación define una función con un parámetro denominado "mylocation", la cadena de parámetro sería "mylocation–122.2,44.8" (sin las comillas).

scoring_profile

str

El nombre de un perfil de puntuación para evaluar puntuaciones de coincidencia para documentos coincidentes a fin de ordenar los resultados.

search_fields

list[str]

Lista de nombres de campo a los que se va a definir el ámbito de la búsqueda de texto completo. Cuando se usa la búsqueda por campos (fieldName:searchExpression) en una consulta completa de Lucene, los nombres de campo de cada expresión de búsqueda con campos tienen prioridad sobre los nombres de campo enumerados en este parámetro.

search_mode

str o SearchMode

Valor que especifica si alguno o todos los términos de búsqueda deben coincidir para contar el documento como una coincidencia. Entre los valores posibles se incluyen: "any", "all".

query_answer

str o QueryAnswerType

Este parámetro solo es válido si el tipo de consulta es "semántico". Si se establece, la consulta devuelve respuestas extraídas de los pasajes clave de los documentos clasificados más altos. Entre los valores posibles se incluyen: "none", "extractive".

query_answer_count

int

Este parámetro solo es válido si el tipo de consulta es "semántico" y la respuesta de consulta es "extractiva". Configura el número de respuestas devueltas. El recuento predeterminado es 1.

query_answer_threshold

float

Este parámetro solo es válido si el tipo de consulta es "semántico" y la respuesta de consulta es "extractiva". Configura el número de umbral de confianza. El recuento predeterminado es 0,7.

query_caption

str o QueryCaptionType

Este parámetro solo es válido si el tipo de consulta es "semántico". Si se establece, la consulta devuelve los títulos extraídos de los pasajes clave de los documentos clasificados más altos. El valor predeterminado es "None". Entre los valores posibles se incluyen: "none", "extractive".

query_caption_highlight_enabled

bool

Este parámetro solo es válido si el tipo de consulta es "semántico" cuando la consulta subtítulo se establece en "extractive". Determina si el resaltado está habilitado. El valor predeterminado es "true".

semantic_configuration_name

str

Nombre de la configuración semántica que se usará al procesar documentos para consultas de tipo semántico.

select

list[str]

Lista de campos que se van a recuperar. Si no se especifica nada, se incluirán todos los campos marcados como recuperables en el esquema.

skip

int

El número de resultados de búsqueda que se van a omitir. Este valor no puede ser mayor que 100 000. Si necesita examinar documentos en secuencia, pero no puede usar $skip debido a esta limitación, considere la posibilidad de usar $orderby en una clave totalmente ordenada y $filter con una consulta de rango en su lugar.

top

int

El número de resultados de búsqueda que se van a recuperar. Esto se puede usar junto con $skip para implementar la paginación del lado cliente de los resultados de búsqueda. Si los resultados se truncan debido a la paginación del lado servidor, la respuesta incluirá un token de continuación que se puede usar para emitir otra solicitud de búsqueda para la página siguiente de resultados.

scoring_statistics

str o ScoringStatistics

Valor que especifica si queremos calcular las estadísticas de puntuación (como la frecuencia del documento) globalmente para obtener una puntuación más coherente o localmente para reducir la latencia. El valor predeterminado es "local". Use "global" para agregar estadísticas de puntuación globalmente antes de la puntuación. El uso de estadísticas de puntuación global puede aumentar la latencia de las consultas de búsqueda. Entre los valores posibles se incluyen: "local", "global".

session_id

str

Valor que se va a usar para crear una sesión permanente, lo que puede ayudar a obtener resultados más coherentes. Siempre que se use el mismo sessionId, se realizará un intento de mejor esfuerzo para tener como destino el mismo conjunto de réplicas. Tenga cuidado de que reutilizar los mismos valores de sessionID repetidamente puede interferir con el equilibrio de carga de las solicitudes entre réplicas y afectar negativamente al rendimiento del servicio de búsqueda. El valor utilizado como sessionId no puede empezar con el carácter "_".

semantic_error_mode

str o SemanticErrorMode

Permite al usuario elegir si una llamada semántica debe producir un error completamente (comportamiento predeterminado o actual) o devolver resultados parciales. Los valores conocidos son: "parcial" y "fail".

semantic_max_wait_in_milliseconds

int

Permite al usuario establecer un límite superior en la cantidad de tiempo que tarda el enriquecimiento semántico en finalizar el procesamiento antes de que se produzca un error en la solicitud.

vector_queries

list[VectorQuery]

Los parámetros de consulta para las consultas de búsqueda híbrida y vectorial.

vector_filter_mode

str o VectorFilterMode

Determina si se aplican o no filtros antes o después de realizar la búsqueda vectorial. El valor predeterminado es "preFilter". Los valores conocidos son: "postFilter" y "preFilter".

Devoluciones

Lista de documentos (dicts) que coinciden con los criterios de búsqueda especificados.

Tipo de valor devuelto

AsyncSearchItemPaged[dict]

Ejemplos

Obtiene las facetas del resultado de búsqueda.

   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

Obtenga los resultados de sugerencias de búsqueda del índice de Azure Search.

carácter y no más de 100 caracteres. :p aram str suggester_name: Obligatorio. Nombre del proveedor de sugerencias tal y como se especifica en la colección suggesters que forma parte de la definición del índice. :keyword str filter: expresión OData que filtra los documentos que se consideran para obtener sugerencias. :keyword bool use_fuzzy_matching: valor que indica si se debe usar la coincidencia aproximada para las sugerencias.

. El valor predeterminado es False. Cuando se establece en true, la consulta encontrará términos incluso si hay un carácter sustituido o que falta en el texto de búsqueda. Aunque esto proporciona una mejor experiencia en algunos escenarios, se produce un costo de rendimiento, ya que las consultas de sugerencias aproximadas son más lentas y consumen más recursos.

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]

Parámetros

highlight_post_tag

str

Etiqueta de cadena que se anexa a los resaltados de aciertos. Debe establecerse con highlightPreTag. Si se omite, el resaltado de referencias de sugerencias está deshabilitado.

highlight_pre_tag

str

Una etiqueta de cadena que se antepone para alcanzar los resaltados. Debe establecerse con highlightPostTag. Si se omite, el resaltado de referencias de sugerencias está deshabilitado.

minimum_coverage

float

Número comprendido entre 0 y 100 que indica el porcentaje del índice que debe estar cubierto por una consulta de sugerencias para que la consulta se notifique como correcta. Este parámetro puede ser útil para garantizar la disponibilidad de búsqueda incluso para los servicios con una sola réplica. El valor predeterminado es 80.

order_by

list[str]

Lista de expresiones de $orderby de OData por las que se ordenan los resultados. Cada expresión puede ser un nombre de campo o una llamada a las funciones geo.distance() o search.score(). Cada expresión puede ir seguida de asc para indicar ascendente, o desc para indicar descendente. El valor predeterminado es ascendente. Los empates se resolverán por la puntuación de coincidencia de los documentos. Si no se especifica ningún $orderby, el criterio de ordenación predeterminado es descendente por puntuación de coincidencia de documento. Puede haber como máximo 32 $orderby cláusulas.

search_fields

list[str]

Lista de nombres de campo que se van a buscar en el texto de búsqueda especificado. Los campos de destino deben incluirse en el proveedor de sugerencias especificado.

select

list[str]

Lista de campos que se van a recuperar. Si no se especifica, solo se incluirá el campo clave en los resultados.

top

int

Número de sugerencias que se van a recuperar. El valor debe ser un número comprendido entre 1 y 100. El valor predeterminado es 5.

Devoluciones

Lista de documentos.

Tipo de valor devuelto

list[dict]

Ejemplos

Obtener sugerencias de búsqueda.

   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

Cargue documentos en el índice de Azure Search.

Una acción de carga es similar a una "upsert" donde se insertará el documento si es nuevo y actualizado o reemplazado si existe. Todos los campos se reemplazan en el caso de actualización.

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

Parámetros

documents

list[dict]

Requerido

Lista de documentos que se van a cargar.

Devoluciones

Lista de IndexingResult

Tipo de valor devuelto

list[IndexingResult]

Ejemplos

Carga de nuevos documentos en un índice

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