SearchClient Classe

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

Herança

azure.search.documents._headers_mixin.HeadersMixin

SearchClient

Construtor

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

Parâmetros

endpoint

str

Obrigatório

O ponto de extremidade de URL de um serviço do Azure Search

index_name

str

Obrigatório

O nome do índice ao qual se conectar

credential

AzureKeyCredential ou AsyncTokenCredential

Obrigatório

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.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	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. :Gera RequestEntityTooLargeError
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 do Azure Search.
suggest	Obtenha os resultados da sugestão de pesquisa do índice do Azure Search. caractere e não mais de 100 caracteres. :p aram str suggester_name: obrigatório. O nome do sugestor conforme especificado na coleção suggesters 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 use_fuzzy_matching bool: um valor que indica se é necessário 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 de 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 do Azure Search. 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'.

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

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.

search_fields

list[str]

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

list[Dict]

Exemplos

Obtenha uma conclusão automática.

   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

Feche a SearchClient sessão.

async close() -> None

Retornos

Nenhum

Tipo de retorno

None

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.

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

Parâmetros

documents

list[dict]

Obrigatório

Uma lista de documentos a serem excluídos.

Retornos

Lista de IndexingResult

Tipo de retorno

list[IndexingResult]

Exemplos

Excluir documentos existentes em um índice

   result = await search_client.upload_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.

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

Parâmetros

key

str

Obrigatório

O valor da chave primária para o documento recuperar

selected_fields

list[str]

Obrigatório

uma lista de permissões de campos a serem incluídos nos resultados

Retornos

O documento que corresponde à chave especificada

Tipo de retorno

dict

Exemplos

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

   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

Retornar o número de documentos no índice do Azure Search.

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

Retornos

A contagem de documentos no índice

Tipo de retorno

int

index_documents

Especifique operações de documento a serem executadas como um lote.

:Gera RequestEntityTooLargeError

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

Parâmetros

batch

IndexDocumentsBatch

Obrigatório

Um lote de operações de documento a serem executadas.

Retornos

Lista de IndexingResult

Tipo de retorno

list[IndexingResult]

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.

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

Parâmetros

documents

list[dict]

Obrigatório

Uma lista de documentos a serem mesclados.

Retornos

Lista de IndexingResult

Tipo de retorno

list[IndexingResult]

Exemplos

Mesclar campos em documentos existentes em um í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

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.

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

Parâmetros

documents

list[dict]

Obrigatório

Uma lista de documentos a serem mesclados ou carregados.

Retornos

Lista de IndexingResult

Tipo de retorno

list[IndexingResult]

search

Pesquise documentos no índice do 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

Obrigatório

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.

facets

list[str]

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.

order_by

list[str]

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.

query_type

str ou QueryType

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".

scoring_parameters

list[str]

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.

search_fields

list[str]

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 de passagens-chave 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 de passagens-chave 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 estiver definida como 'extrativa'. 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 de tipo semântico.

select

list[str]

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 queremos calcular estatísticas de pontuação (como a frequência do documento) globalmente para uma 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. Usar estatísticas de pontuação global pode aumentar a latência de 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".

Retornos

Uma lista de documentos (dicts) que correspondem aos critérios de pesquisa especificados.

Tipo de retorno

AsyncSearchItemPaged[dict]

Exemplos

Obter facetas de resultado da pesquisa.

   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

Obtenha os resultados da sugestão de pesquisa do índice do Azure Search.

caractere e não mais de 100 caracteres. :p aram str suggester_name: obrigatório. O nome do sugestor conforme especificado na coleção suggesters 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 use_fuzzy_matching bool: um valor que indica se é necessário 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 de 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.

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

Uma marca de cadeia de caracteres que é acrescentada aos realces de clique. Deve ser definido com highlightPreTag. Se omitido, o realce de ocorrências de sugestões 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 de sugestões 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 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.

order_by

list[str]

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 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 de documento. Pode haver no máximo 32 cláusulas $orderby.

search_fields

list[str]

A lista de nomes de campo para pesquisar o texto de pesquisa especificado. Os campos de destino devem ser incluídos no sugestor especificado.

select

list[str]

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

list[dict]

Exemplos

Obtenha sugestões de pesquisa.

   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

Carregue documentos no índice do Azure Search.

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.

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

Parâmetros

documents

list[dict]

Obrigatório

Uma lista de documentos a serem carregados.

Retornos

Lista de IndexingResult

Tipo de retorno

list[IndexingResult]

Exemplos

Carregar novos documentos em um í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))