SearchClient Classe
Um cliente para interagir com um índice existente do Azure Search.
- Herança
-
azure.search.documents._headers_mixin.HeadersMixinSearchClient
Construtor
SearchClient(endpoint: str, index_name: str, credential: AzureKeyCredential | TokenCredential, **kwargs: Any)Parâmetros
- credential
- AzureKeyCredential ou TokenCredential
Uma credencial para autorizar solicitações de cliente de pesquisa
- api_version
- str
A versão da API de Pesquisa a ser usada para solicitações.
- audience
- str
define o Público-alvo a ser usado para autenticação com o AAD (Azure Active Directory). O público-alvo não é considerado ao usar uma chave compartilhada. Se o público-alvo não for fornecido, o público-alvo da nuvem será assumido.
Exemplos
Criando 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 os resultados da conclusão automática da pesquisa do índice do Azure Search. coleção que faz parte da definição de índice. :palavra-chave modo: especifica o modo de preenchimento automático. O padrão é 'oneTerm'. Uso 'twoTerms' para obter telhas e 'oneTermWithContext' para usar o contexto atual ao produzir termos preenchidos automaticamente. Os valores possíveis incluem: 'oneTerm', 'twoTerms', 'oneTermWithContext'. |
| close |
Feche a SearchClient sessão. |
| delete_documents |
Excluir documentos do índice do Azure Search Excluir remove o documento especificado do índice. Qualquer campo especificado em uma operação de exclusão, diferente do campo de chave, será ignorado. Se você quiser remover um campo individual de um documento, use merge_documents e defina o campo explicitamente como Nenhum. As operações de exclusão são idempotentes. Ou seja, mesmo se não existir uma chave de documento no índice, a tentativa de uma operação de exclusão com essa chave resultará em um código de status 200. |
| get_document |
Recupere um documento do índice do Azure Search por sua chave. |
| get_document_count |
Retornar o número de documentos no índice do Azure Search. |
| index_documents |
Especifique operações de documento a serem executadas como um lote. |
| merge_documents |
Mescle documentos em documentos existentes no índice do Azure Search. A mesclagem atualiza um documento existente com os campos especificados. Se o documento não existir, a mesclagem falhará. Qualquer campo que você especificar em uma mesclagem substituirá o campo existente no documento. Isso também se aplica a coleções de tipos primitivos e complexos. |
| merge_or_upload_documents |
Mescle documentos em documentos existentes no índice do Azure Search ou carregue-os se eles ainda não existirem. Essa ação se comporta como merge_documents se um documento com a chave fornecida já existir no índice. Se o documento não existir, ele se comportará como upload_documents com um novo documento. |
| search |
Pesquise documentos no índice de pesquisa do Azure. |
| suggest |
Obtenha os resultados da sugestão de pesquisa do índice de pesquisa do Azure. caractere e não mais de 100 caracteres. :p aram str suggester_name: obrigatório. O nome do sugestor conforme especificado na coleção de sugestores que faz parte da definição de índice. :palavra-chave filtro str: uma expressão OData que filtra os documentos considerados para sugestões. :palavra-chave bool use_fuzzy_matching: um valor que indica se deve usar correspondência difusa para as sugestões do Banco de Dados Elástico. O padrão é false. Quando definida como true, a consulta encontrará termos mesmo se houver um caractere substituído ou ausente no texto da pesquisa. Embora isso forneça uma experiência melhor em alguns cenários, ele tem um custo de desempenho, pois as consultas de sugestões difusas são mais lentas e consomem mais recursos. |
| upload_documents |
Carregue documentos no índice de pesquisa do Azure. Uma ação de upload é 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 os resultados da conclusão automática da pesquisa do índice do Azure Search.
coleção que faz parte da definição de índice. :palavra-chave modo: especifica o modo de preenchimento automático. O padrão é 'oneTerm'. Uso
'twoTerms' para obter telhas e 'oneTermWithContext' para usar o contexto atual ao produzir termos preenchidos 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 usados para produzir termos concluídos para o resultado do preenchimento automático.
- use_fuzzy_matching
- bool
Um valor que indica se a correspondência difusa deve ser usada para a consulta de preenchimento automático. O padrão é false. Quando definida como true, a consulta encontrará termos mesmo se houver um caractere substituído ou ausente no texto de pesquisa. Embora isso forneça uma experiência melhor em alguns cenários, ele tem um custo de desempenho, pois as consultas de preenchimento automático difuso são mais lentas e consomem mais recursos.
- highlight_post_tag
- str
Uma marca de cadeia de caracteres que é acrescentada aos realces de clique. Deve ser definido com highlightPreTag. Se omitido, o realce de ocorrências será desabilitado.
- highlight_pre_tag
- str
Uma marca de cadeia de caracteres que é acrescentada a realces de clique. Deve ser definido com highlightPostTag. Se omitido, o realce de ocorrências será desabilitado.
- minimum_coverage
- float
Um número entre 0 e 100 que indica o percentual do índice que deve ser coberto por uma consulta de preenchimento automático para que a consulta seja relatada como um sucesso. Esse parâmetro pode ser útil para garantir a disponibilidade de pesquisa mesmo para serviços com apenas um réplica. O padrão é 80.
A lista de nomes de campo a serem considerados ao consultar termos preenchidos automaticamente. Os campos de destino devem ser incluídos no sugestor especificado.
- top
- int
O número de termos preenchidos automaticamente a serem recuperados. Deve ser um valor entre 1 e 100. O padrão é 5.
Tipo de retorno
Exemplos
Obtenha uma conclusão automática.
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() -> Nonedelete_documents
Excluir documentos do índice do Azure Search
Excluir remove o documento especificado do índice. Qualquer campo especificado em uma operação de exclusão, diferente do campo de chave, será ignorado. Se você quiser remover um campo individual de um documento, use merge_documents e defina o campo explicitamente como Nenhum.
As operações de exclusão são idempotentes. Ou seja, mesmo se não existir uma chave de documento no índice, a tentativa de uma operação de exclusão com essa chave resultará em um código de status 200.
delete_documents(documents: List[Dict], **kwargs: Any) -> List[IndexingResult]Parâmetros
Retornos
Lista de IndexingResult
Tipo de retorno
Exemplos
Excluir documentos existentes em um índice
result = search_client.delete_documents(documents=[{"hotelId": "1000"}])
print("Delete new document succeeded: {}".format(result[0].succeeded))
get_document
Recupere um documento do índice do Azure Search por sua chave.
get_document(key: str, selected_fields: List[str] | None = None, **kwargs: Any) -> DictParâmetros
uma lista de permissões de campos a serem incluídos nos resultados
Retornos
O documento como armazenado no índice do Azure Search
Tipo de retorno
Exemplos
Obtenha um documento específico 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
Retornar o número de documentos no índice do Azure Search.
get_document_count(**kwargs: Any) -> intRetornos
A contagem de documentos no índice
Tipo de retorno
index_documents
Especifique operações de documento a serem executadas como um lote.
:Gera RequestEntityTooLargeError
index_documents(batch: IndexDocumentsBatch, **kwargs: Any) -> List[IndexingResult]Parâmetros
Retornos
Lista de IndexingResult
Tipo de retorno
merge_documents
Mescle documentos em documentos existentes no índice do Azure Search.
A mesclagem atualiza um documento existente com os campos especificados. Se o documento não existir, a mesclagem falhará. Qualquer campo que você especificar em uma mesclagem substituirá o campo existente no documento. Isso também se aplica a coleções de tipos primitivos e complexos.
merge_documents(documents: List[Dict], **kwargs: Any) -> List[IndexingResult]Parâmetros
Retornos
Lista de IndexingResult
Tipo de retorno
Exemplos
Mesclar campos em documentos existentes em um í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
Mescle documentos em documentos existentes no índice do Azure Search ou carregue-os se eles ainda não existirem.
Essa ação se comporta como merge_documents se um documento com a chave fornecida já existir no índice. Se o documento não existir, ele se comportará como upload_documents com um novo documento.
merge_or_upload_documents(documents: List[Dict], **kwargs: Any) -> List[IndexingResult]Parâmetros
Retornos
Lista de IndexingResult
Tipo de retorno
search
Pesquise 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
Uma expressão de consulta de pesquisa de texto completo; Use "*" ou omita esse parâmetro para corresponder a todos os documentos.
- include_total_count
- bool
Um valor que especifica se a contagem total de resultados deve ser buscada. O padrão é false. Definir esse valor como true pode ter um impacto no desempenho. Observe que a contagem retornada é uma aproximação.
A lista de expressões de faceta a serem aplicadas à consulta de pesquisa. Cada expressão de faceta contém um nome de campo, opcionalmente seguido por uma lista separada por vírgulas de pares nome:valor.
- filter
- str
A expressão de $filter OData a ser aplicada à consulta de pesquisa.
- highlight_fields
- str
A lista separada por vírgulas de nomes de campo a serem usados para realces de ocorrência. Somente campos pesquisáveis podem ser usados para realce de ocorrências.
- highlight_post_tag
- str
Uma marca de cadeia de caracteres que é acrescentada aos realces de clique. Deve ser definido com highlightPreTag. O padrão é .
- highlight_pre_tag
- str
Uma marca de cadeia de caracteres que é acrescentada a realces de clique. Deve ser definido com highlightPostTag. O padrão é .
- minimum_coverage
- float
Um número entre 0 e 100 indicando o percentual do índice que deve ser coberto por uma consulta de pesquisa para que a consulta seja relatada como um sucesso. Esse parâmetro pode ser útil para garantir a disponibilidade de pesquisa mesmo para serviços com apenas um réplica. O padrão é 100.
A lista de expressões de $orderby OData pelas quais classificar 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 crescente e desc para indicar decrescente. O padrão é a ordem crescente. Os empates serão resolvidos pelas pontuações de correspondência de documentos. Se nenhum OrderBy for especificado, a ordem de classificação padrão será decrescente por pontuação de correspondência do documento. Pode haver no máximo 32 cláusulas $orderby.
Um valor que especifica a sintaxe da consulta de pesquisa. O padrão é "simples". Use 'full' se a consulta usar a sintaxe de consulta Lucene. Os valores possíveis incluem: 'simple', 'full', "semântico".
A lista de valores de parâmetro a serem usados em funções de pontuação (por exemplo, referencePointParameter) usando o formato name-values. Por exemplo, se o perfil de pontuação definir uma função com um parâmetro chamado 'mylocation', a cadeia de caracteres de parâmetro será "mylocation-122.2,44.8" (sem as aspas).
- scoring_profile
- str
O nome de um perfil de pontuação para avaliar as pontuações correspondentes para corresponder documentos para classificar os resultados.
A lista de nomes de campo para os quais definir o escopo da pesquisa de texto completo. Ao usar a pesquisa em campo (fieldName:searchExpression) em uma 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 nesse parâmetro.
- search_mode
- str ou SearchMode
Um valor que especifica se qualquer ou todos os termos de pesquisa devem ser correspondidos para contar o documento como uma correspondência. Os valores possíveis incluem: 'any', 'all'.
- query_answer
- str ou QueryAnswerType
Esse parâmetro só será válido se o tipo de consulta for 'semântico'. Se definida, a consulta retornará respostas extraídas das principais passagens nos documentos mais bem classificados. Os valores possíveis incluem: "none", "extractive".
- query_answer_count
- int
Esse parâmetro só será válido se o tipo de consulta for 'semântico' e a resposta de consulta for 'extrativa'. Configura o número de respostas retornadas. A contagem padrão é 1.
- query_answer_threshold
- float
Esse parâmetro só será válido se o tipo de consulta for 'semântico' e a resposta de consulta for 'extrativa'. Configura o número de limite de confiança. A contagem padrão é 0,7.
- query_caption
- str ou QueryCaptionType
Esse parâmetro só será válido se o tipo de consulta for 'semântico'. Se definida, a consulta retornará legendas extraídas das principais passagens nos documentos mais bem classificados. O padrão é 'None'. Os valores possíveis incluem: "none", "extractive".
- query_caption_highlight_enabled
- bool
Esse parâmetro só será válido se o tipo de consulta for 'semântico' quando a consulta legenda for definida como 'extractive'. Determina se o realce está habilitado. O padrão é 'true'.
- semantic_configuration_name
- str
O nome da configuração semântica que será usada ao processar documentos para consultas do tipo semântica.
A lista de campos a serem recuperados. Se não for especificado, todos os campos marcados como recuperáveis no esquema serão incluídos.
- skip
- int
O número de resultados de pesquisa a ser ignorado. Esse valor não deve ser maior que 100.000. Se você precisar examinar documentos em sequência, mas não puder usar $skip devido a essa limitação, considere usar $orderby em uma chave totalmente ordenada e $filter com uma consulta de intervalo.
- top
- int
O número de resultados de pesquisa a ser recuperado. Isso pode ser usado 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 usado para emitir outra solicitação de pesquisa para a próxima página de resultados.
- scoring_statistics
- str ou ScoringStatistics
Um valor que especifica se desejamos calcular estatísticas de pontuação (como frequência de documento) globalmente para pontuação mais consistente ou localmente, para menor latência. O padrão é 'local'. Use 'global' para agregar estatísticas de pontuação globalmente antes da pontuação. O uso de estatísticas de pontuação global pode aumentar a latência das consultas de pesquisa. Os valores possíveis incluem: "local", "global".
- session_id
- str
Um valor a ser usado para criar uma sessão autoadesiva, o que pode ajudar a obter resultados mais consistentes. Desde que a mesma sessionId seja usada, será feita uma tentativa de melhor esforço para atingir o mesmo conjunto de réplica. Tenha cuidado para que a reutilização dos mesmos valores sessionID repetidamente possa interferir no balanceamento de carga das solicitações entre réplicas e afetar negativamente o desempenho do serviço de pesquisa. O valor usado como sessionId não pode começar com um caractere “_”.
- semantic_error_mode
- str ou SemanticErrorMode
Permite que o usuário escolha se uma chamada semântica deve falhar completamente (comportamento padrão/atual) ou retornar resultados parciais. Os valores conhecidos são: "parcial" e "fail".
- semantic_max_wait_in_milliseconds
- int
Permite que o usuário defina um limite superior na quantidade de tempo que leva para que o enriquecimento semântico conclua o processamento antes que a solicitação falhe.
- vector_queries
- list[VectorQuery]
Os parâmetros de consulta para consultas de pesquisa híbrida e vetor.
- vector_filter_mode
- str ou VectorFilterMode
Determina se os filtros são aplicados ou não antes ou depois que a pesquisa de vetor é executada. O padrão é 'preFilter'. Os valores conhecidos são: "postFilter" e "preFilter".
Tipo de retorno
Exemplos
Obter facetas de resultado 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 os resultados da sugestão de pesquisa do índice de pesquisa do Azure.
caractere e não mais de 100 caracteres. :p aram str suggester_name: obrigatório. O nome do sugestor conforme especificado na coleção de sugestores que faz parte da definição de índice. :palavra-chave filtro str: uma expressão OData que filtra os documentos considerados para sugestões. :palavra-chave bool use_fuzzy_matching: um valor que indica se deve usar correspondência difusa para as sugestões
do Banco de Dados Elástico. O padrão é false. Quando definida como true, a consulta encontrará termos mesmo se houver um caractere substituído ou ausente no texto da pesquisa. Embora isso forneça uma experiência melhor em alguns cenários, ele tem um custo de desempenho, pois 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 marca de cadeia de caracteres que é acrescentada para atingir realces. Deve ser definido com highlightPreTag. Se omitido, o realce de ocorrência de sugestões será desabilitado.
- highlight_pre_tag
- str
Uma marca de cadeia de caracteres que é prefixada para atingir realces. Deve ser definido com highlightPostTag. Se omitido, o realce de ocorrência de sugestões será desabilitado.
- minimum_coverage
- float
Um número entre 0 e 100 indicando o percentual do índice que deve ser coberto por uma consulta de sugestões para que a consulta seja relatada como um sucesso. Esse parâmetro pode ser útil para garantir a disponibilidade de pesquisa mesmo para serviços com apenas um réplica. O padrão é 80.
A lista de expressões $orderby OData pelas quais classificar 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 crescente ou desc para indicar decrescente. O padrão é a ordem crescente. Os empates serão resolvidos pelas pontuações de correspondência de documentos. Se nenhuma $orderby for especificada, a ordem de classificação padrão será decrescente por pontuação de correspondência do documento. Pode haver no máximo 32 cláusulas $orderby.
A lista de nomes de campo para pesquisar o texto de pesquisa especificado. Os campos de destino devem ser incluídos no sugestor especificado.
A lista de campos a serem recuperados. Se não for especificado, somente o campo de chave será incluído nos resultados.
- top
- int
O número de sugestões a serem recuperadas. O valor deve ser um número entre 1 e 100. O padrão é 5.
Retornos
Lista de documentos.
Tipo de retorno
Exemplos
Obtenha 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 no índice de pesquisa do Azure.
Uma ação de upload é 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
Retornos
Lista de IndexingResult
Tipo de retorno
Exemplos
Carregar novos documentos em 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))
Azure SDK for Python