SearchClient Classe

Um cliente para interagir com um índice de pesquisa do Azure existente.

Herança

azure.search.documents._headers_mixin.HeadersMixin

SearchClient

Construtor

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

Parâmetros

endpoint

str

Necessário

O ponto final do URL de um serviço de pesquisa do Azure

index_name

str

Necessário

O nome do índice ao qual ligar

credential

AzureKeyCredential ou TokenCredential

Necessário

Uma credencial para autorizar pedidos de cliente de pesquisa

api_version

str

A versão da API de Pesquisa a utilizar para pedidos.

audience

str

define a Audiência a utilizar para autenticação com o Azure Active Directory (AAD). A audiência não é considerada ao utilizar uma chave partilhada. Se a audiência não for fornecida, será assumida a audiência da cloud pública.

Exemplos

Criar o SearchClient com uma chave de 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étodos

autocomplete	Obtenha resultados de conclusão automática da pesquisa a partir do índice de pesquisa do Azure. coleção que faz parte da definição de índice. :modo de palavra-chave: especifica o modo para Conclusão Automática. A predefinição é "oneTerm". Utilização "twoTerms" para obter telhas e "oneTermWithContext" para utilizar o contexto atual enquanto produz termos concluídos automaticamente. Os valores possíveis incluem: "oneTerm", "twoTerms", "oneTermWithContext".
close	Feche a SearchClient sessão.
delete_documents	Eliminar documentos do índice de pesquisa do Azure Eliminar remove o documento especificado do índice. Qualquer campo especificado numa operação de eliminação, que não seja o campo de chave, será ignorado. Se quiser remover um campo individual de um documento, utilize merge_documents e defina o campo explicitamente como Nenhum. As operações de eliminação são idempotentes. Ou seja, mesmo que não exista uma chave de documento no índice, tentar uma operação de eliminação com essa chave resultará num código de estado 200.
get_document	Obtenha um documento a partir do índice de pesquisa do Azure pela respetiva chave.
get_document_count	Devolver o número de documentos no índice de pesquisa do Azure.
index_documents	Especifique as operações de um documento a executar como um lote. :raises RequestEntityTooLargeError
merge_documents	Intercalar documentos em documentos existentes no índice de pesquisa do Azure. Intercalar atualiza um documento existente com os campos especificados. Se o documento não existir, a intercalação falhará. Qualquer campo que especifique numa intercalação irá substituir o campo existente no documento. Isto também se aplica a coleções de tipos primitivos e complexos.
merge_or_upload_documents	Intercale documentos em documentos existentes no índice de pesquisa do Azure ou carregue-os se ainda não existirem. Esta ação comporta-se como merge_documents se já existir um documento com a chave especificada no índice. Se o documento não existir, comporta-se como upload_documents com um novo documento.
search	Procure documentos no índice de pesquisa do Azure.
suggest	Obtenha resultados de sugestões de pesquisa a partir do índice de pesquisa do Azure. e não mais de 100 carateres. :p aram str suggester_name: Necessário. O nome do sugeridor, conforme especificado na coleção de sugestores que faz parte da definição do índice. :keyword str filter: uma expressão OData que filtra os documentos considerados para sugestões. :keyword bool use_fuzzy_matching: um valor que indica se deve utilizar a correspondência difusa para as sugestões consulta. A predefinição é falso. Quando definida como verdadeira, a consulta irá encontrar termos, mesmo que exista um caráter substituído ou em falta no texto de pesquisa. Embora isto proporcione uma melhor experiência em alguns cenários, tem um custo de desempenho, uma vez que as consultas de sugestões difusas são mais lentas e consomem mais recursos.
upload_documents	Carregue documentos para o índice de pesquisa do Azure. Uma ação de carregamento é semelhante a um "upsert" em que o documento será inserido se for novo e atualizado/substituído se existir. Todos os campos são substituídos no caso de atualização.

autocomplete

Obtenha resultados de conclusão automática da pesquisa a partir do índice de pesquisa do Azure.

coleção que faz parte da definição de índice. :modo de palavra-chave: especifica o modo para Conclusão Automática. A predefinição é "oneTerm". Utilização

"twoTerms" para obter telhas e "oneTermWithContext" para utilizar o contexto atual enquanto produz termos concluídos automaticamente. Os valores possíveis incluem: "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]

Parâmetros

filter

str

Uma expressão OData que filtra os documentos utilizados para produzir termos concluídos para o resultado da Conclusão Automática.

use_fuzzy_matching

bool

Um valor que indica se deve utilizar a correspondência difusa para a consulta de conclusão automática. A predefinição é falso. Quando definida como verdadeira, a consulta irá encontrar termos, mesmo que exista um caráter substituído ou em falta no texto de pesquisa. Embora isto proporcione uma melhor experiência em alguns cenários, tem um custo de desempenho, uma vez que as consultas de conclusão automática difusas são mais lentas e consomem mais recursos.

highlight_post_tag

str

Uma etiqueta de cadeia de carateres que é anexada para obter destaques. Tem de ser definido com highlightPreTag. Se for omitido, o realce de acerto está desativado.

highlight_pre_tag

str

Uma etiqueta de cadeia de carateres que está pré-anexada para obter destaques. Tem de ser definido com highlightPostTag. Se for omitido, o realce de acerto está desativado.

minimum_coverage

float

Um número entre 0 e 100 que indica a percentagem do índice que tem de ser abrangido por uma consulta de conclusão automática para que a consulta seja comunicada com êxito. Este parâmetro pode ser útil para garantir a disponibilidade da pesquisa, mesmo para serviços com apenas uma réplica. A predefinição é 80.

search_fields

list[str]

A lista de nomes de campo a considerar ao consultar termos concluídos automaticamente. Os campos de destino têm de ser incluídos no sugeridor especificado.

top

int

O número de termos de conclusão automática a obter. Tem de ser um valor entre 1 e 100. A predefinição é 5.

Tipo de retorno

list[dict]

Exemplos

Obtenha as conclusões automáticas.

   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

Feche a SearchClient sessão.

close() -> None

delete_documents

Eliminar documentos do índice de pesquisa do Azure

Eliminar remove o documento especificado do índice. Qualquer campo especificado numa operação de eliminação, que não seja o campo de chave, será ignorado. Se quiser remover um campo individual de um documento, utilize merge_documents e defina o campo explicitamente como Nenhum.

As operações de eliminação são idempotentes. Ou seja, mesmo que não exista uma chave de documento no índice, tentar uma operação de eliminação com essa chave resultará num código de estado 200.

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

Parâmetros

documents

list[dict]

Necessário

Uma lista de documentos a eliminar.

Devoluções

Lista de IndexaçãoResult

Tipo de retorno

list[IndexingResult]

Exemplos

Eliminar documentos existentes num índice

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

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

get_document

Obtenha um documento a partir do índice de pesquisa do Azure pela respetiva chave.

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

Parâmetros

key

str

Necessário

O valor da chave primária do documento a obter

selected_fields

list[str]

Necessário

uma lista de permissões de campos a incluir nos resultados

Devoluções

O documento, conforme armazenado no índice de pesquisa do Azure

Tipo de retorno

dict

Exemplos

Obtenha um documento específico a partir do índice de pesquisa.

   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

Devolver o número de documentos no índice de pesquisa do Azure.

get_document_count(**kwargs: Any) -> int

Devoluções

A contagem de documentos no índice

Tipo de retorno

int

index_documents

Especifique as operações de um documento a executar como um lote.

:raises RequestEntityTooLargeError

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

Parâmetros

batch

IndexDocumentsBatch

Necessário

Um lote de operações de documentos a executar.

Devoluções

Lista de IndexaçãoResult

Tipo de retorno

list[IndexingResult]

merge_documents

Intercalar documentos em documentos existentes no índice de pesquisa do Azure.

Intercalar atualiza um documento existente com os campos especificados. Se o documento não existir, a intercalação falhará. Qualquer campo que especifique numa intercalação irá substituir o campo existente no documento. Isto também se aplica a coleções de tipos primitivos e complexos.

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

Parâmetros

documents

list[dict]

Necessário

Uma lista de documentos a intercalar.

Devoluções

Lista de IndexaçãoResult

Tipo de retorno

list[IndexingResult]

Exemplos

Intercalar campos em documentos existentes num índice

   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

Intercale documentos em documentos existentes no índice de pesquisa do Azure ou carregue-os se ainda não existirem.

Esta ação comporta-se como merge_documents se já existir um documento com a chave especificada no índice. Se o documento não existir, comporta-se como upload_documents com um novo documento.

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

Parâmetros

documents

list[dict]

Necessário

Uma lista de documentos para intercalar ou carregar.

Devoluções

Lista de IndexaçãoResult

Tipo de retorno

list[IndexingResult]

search

Procure documentos no índice de pesquisa do 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]

Parâmetros

search_text

str

Necessário

Uma expressão de consulta de pesquisa em texto completo; Utilize "*" ou omita este parâmetro para corresponder a todos os documentos.

include_total_count

bool

Um valor que especifica se pretende obter a contagem total de resultados. A predefinição é falso. Definir este valor como verdadeiro pode ter um impacto no desempenho. Tenha em atenção que a contagem devolvida é uma aproximação.

facets

list[str]

A lista de expressões de facetas a aplicar à consulta de pesquisa. Cada expressão de faceta contém um nome de campo, opcionalmente seguido de uma lista separada por vírgulas de pares name:value.

filter

str

O OData $filter expressão a aplicar à consulta de pesquisa.

highlight_fields

str

A lista separada por vírgulas de nomes de campo a utilizar para os destaques de acesso. Apenas os campos pesquisáveis podem ser utilizados para o realce de resultados.

highlight_post_tag

str

Uma etiqueta de cadeia de carateres que é anexada para obter destaques. Tem de ser definido com highlightPreTag. A predefinição é .

highlight_pre_tag

str

Uma etiqueta de cadeia de carateres que está pré-anexada para obter destaques. Tem de ser definido com highlightPostTag. A predefinição é .

minimum_coverage

float

Um número entre 0 e 100 que indica a percentagem do índice que tem de ser abrangido por uma consulta de pesquisa para que a consulta seja reportada como um êxito. Este parâmetro pode ser útil para garantir a disponibilidade da pesquisa, mesmo para serviços com apenas uma réplica. A predefinição é 100.

order_by

list[str]

A lista de OData $orderby expressões pelas quais ordenar os resultados. Cada expressão pode ser um nome de campo ou uma chamada para as funções geo.distance() ou search.score(). Cada expressão pode ser seguida por asc para indicar ascendente e desc para indicar descendente. A predefinição é ordem ascendente. Os empates serão quebrados pelas pontuações de correspondência de documentos. Se não for especificado orderBy, a sequência de ordenação predefinida é descendente por classificação de correspondência do documento. Pode haver, no máximo, 32 cláusulas de $orderby.

query_type

str ou QueryType

Um valor que especifica a sintaxe da consulta de pesquisa. A predefinição é "simples". Utilize "full" se a consulta utilizar a sintaxe de consulta Lucene. Os valores possíveis incluem: "simples", "completo", "semântico".

scoring_parameters

list[str]

A lista de valores de parâmetros a utilizar nas funções de classificação (por exemplo, referencePointParameter) com o formato name-values. Por exemplo, se o perfil de classificação definir uma função com um parâmetro chamado "mylocation", a cadeia de parâmetros será "mylocation–122.2,44.8" (sem as aspas).

scoring_profile

str

O nome de um perfil de classificação para avaliar pontuações de correspondência para documentos correspondentes para ordenar os resultados.

search_fields

list[str]

A lista de nomes de campos para os quais pretende definir o âmbito da pesquisa em texto completo. Ao utilizar a pesquisa em campo (fieldName:searchExpression) numa consulta Lucene completa, os nomes de campo de cada expressão de pesquisa em campo têm precedência sobre quaisquer nomes de campo listados neste parâmetro.

search_mode

str ou SearchMode

Um valor que especifica se algum ou todos os termos de pesquisa têm de ser correspondidos para contar o documento como uma correspondência. Os valores possíveis incluem: "any", "all".

query_answer

str ou QueryAnswerType

Este parâmetro só é válido se o tipo de consulta for "semântico". Se estiver definida, a consulta devolve respostas extraídas das passagens principais nos documentos mais bem classificados. Os valores possíveis incluem: "none", "extractive".

query_answer_count

int

Este parâmetro só é válido se o tipo de consulta for "semântico" e a resposta da consulta for "extrativa". Configura o número de respostas devolvidas. A contagem predefinida é 1.

query_answer_threshold

float

Este parâmetro só é válido se o tipo de consulta for "semântico" e a resposta da consulta for "extrativa". Configura o número de limiares de confiança. A contagem predefinida é 0,7.

query_caption

str ou QueryCaptionType

Este parâmetro só é válido se o tipo de consulta for "semântico". Se estiver definida, a consulta devolve legendas extraídas de passagens-chave nos documentos mais bem classificados. A predefinição é "Nenhum". Os valores possíveis incluem: "none", "extractive".

query_caption_highlight_enabled

bool

Este parâmetro só é válido se o tipo de consulta for "semântico" quando a consulta legenda estiver definida como "extrativa". Determina se o realce está ativado. A predefinição é "true".

semantic_configuration_name

str

O nome da configuração semântica que será utilizada ao processar documentos para consultas do tipo semântico.

select

list[str]

A lista de campos a obter. Se não for especificado, todos os campos marcados como recuperáveis no esquema são incluídos.

skip

int

O número de resultados da pesquisa a ignorar. Este valor não pode ser superior a 100 000. Se precisar de analisar documentos em sequência, mas não puder utilizar $skip devido a esta limitação, considere utilizar $orderby numa chave totalmente ordenada e, em vez disso, $filter com uma consulta de intervalo.

top

int

O número de resultados da pesquisa a obter. Isto pode ser utilizado em conjunto com $skip para implementar a paginação do lado do cliente dos resultados da pesquisa. Se os resultados forem truncados devido à paginação do lado do servidor, a resposta incluirá um token de continuação que pode ser utilizado para emitir outro pedido de Pesquisa para a próxima página de resultados.

scoring_statistics

str ou ScoringStatistics

Um valor que especifica se queremos calcular as estatísticas de classificação (como a frequência do documento) globalmente para uma classificação mais consistente, ou localmente, para uma menor latência. A predefinição é "local". Utilize "global" para agregar estatísticas de classificação globalmente antes de classificar. A utilização de estatísticas de classificação globais pode aumentar a latência das consultas de pesquisa. Os valores possíveis incluem: "local", "global".

session_id

str

Um valor a ser utilizado para criar uma sessão autocolante, o que pode ajudar a obter resultados mais consistentes. Desde que o mesmo sessionId seja utilizado, será efetuada uma tentativa de melhor esforço para direcionar o mesmo conjunto de réplicas. Tenha em atenção que reutilizar repetidamente os mesmos valores sessionID pode interferir com o balanceamento de carga dos pedidos entre réplicas e afetar negativamente o desempenho do serviço de pesquisa. O valor utilizado como sessionId não pode começar com um caráter "_".

semantic_error_mode

str ou SemanticErrorMode

Permite ao utilizador escolher se uma chamada semântica deve falhar completamente (comportamento predefinido/atual) ou devolver resultados parciais. Os valores conhecidos são: "parcial" e "falha".

semantic_max_wait_in_milliseconds

int

Permite que o utilizador defina um limite superior sobre a quantidade de tempo que o melhoramento semântico demora a concluir o processamento antes de o pedido falhar.

vector_queries

list[VectorQuery]

Os parâmetros de consulta para consultas de vetor e pesquisa híbrida.

vector_filter_mode

str ou VectorFilterMode

Determina se os filtros são aplicados antes ou depois de a pesquisa de vetor ser executada. A predefinição é "preFilter". Os valores conhecidos são: "postFilter" e "preFilter".

Tipo de retorno

SearchItemPaged[dict]

Exemplos

Obter facetas de resultados da pesquisa.

   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

Obtenha resultados de sugestões de pesquisa a partir do índice de pesquisa do Azure.

e não mais de 100 carateres. :p aram str suggester_name: Necessário. O nome do sugeridor, conforme especificado na coleção de sugestores que faz parte da definição do índice. :keyword str filter: uma expressão OData que filtra os documentos considerados para sugestões. :keyword bool use_fuzzy_matching: um valor que indica se deve utilizar a correspondência difusa para as sugestões

consulta. A predefinição é falso. Quando definida como verdadeira, a consulta irá encontrar termos, mesmo que exista um caráter substituído ou em falta no texto de pesquisa. Embora isto proporcione uma melhor experiência em alguns cenários, tem um custo de desempenho, uma vez que as consultas de sugestões difusas são mais lentas e consomem mais recursos.

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

Uma etiqueta de cadeia de carateres que é anexada para obter destaques. Tem de ser definido com highlightPreTag. Se for omitido, prima o realce das sugestões desativado.

highlight_pre_tag

str

Uma etiqueta de cadeia de carateres que está pré-anexada para obter destaques. Tem de ser definido com highlightPostTag. Se for omitido, prima o realce das sugestões desativado.

minimum_coverage

float

Um número entre 0 e 100 que indica a percentagem do índice que tem de ser abrangido por uma consulta de sugestões para que a consulta seja comunicada com êxito. Este parâmetro pode ser útil para garantir a disponibilidade da pesquisa, mesmo para serviços com apenas uma réplica. A predefinição é 80.

order_by

list[str]

A lista de OData $orderby expressões pelas quais ordenar os resultados. Cada expressão pode ser um nome de campo ou uma chamada para as funções geo.distance() ou search.score(). Cada expressão pode ser seguida por asc para indicar ascendente ou desc para indicar descendente. A predefinição é ordem ascendente. Os empates serão quebrados pelas pontuações de correspondência de documentos. Se não for especificada nenhuma $orderby, a sequência de ordenação predefinida é descendente por classificação de correspondência do documento. Pode haver, no máximo, 32 cláusulas de $orderby.

search_fields

list[str]

A lista de nomes de campos a procurar o texto de pesquisa especificado. Os campos de destino têm de ser incluídos no sugeridor especificado.

select

list[str]

A lista de campos a obter. Se não for especificado, apenas o campo de chave será incluído nos resultados.

top

int

O número de sugestões a obter. O valor tem de ser um número entre 1 e 100. A predefinição é 5.

Devoluções

Lista de documentos.

Tipo de retorno

list[dict]

Exemplos

Obter sugestões de pesquisa.

   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

Carregue documentos para o índice de pesquisa do Azure.

Uma ação de carregamento é semelhante a um "upsert" em que o documento será inserido se for novo e atualizado/substituído se existir. Todos os campos são substituídos no caso de atualização.

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

Parâmetros

documents

list[dict]

Necessário

Uma lista de documentos a carregar.

Devoluções

Lista de IndexaçãoResult

Tipo de retorno

list[IndexingResult]

Exemplos

Carregar novos documentos para um índice

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