Criar uma consulta de texto completo no Azure AI Search

Artigo
11/16/2023

Se você estiver criando uma consulta para pesquisa de texto completo, este artigo fornece etapas para configurar a solicitação. Ele também apresenta uma estrutura de consulta e explica como os atributos de campo e os analisadores linguísticos podem afetar os resultados da consulta.

Pré-requisitos

Um índice de pesquisa com campos de cadeia de caracteres atribuídos como searchable.
Permissões de leitura no índice de pesquisa. Para acesso de leitura, inclua uma chave de API de consulta na solicitação ou conceda ao chamador permissões de Leitor de Dados de Índice de Pesquisa.

Exemplo de uma solicitação de consulta de texto completo

No Azure AI Search, uma consulta é uma solicitação somente leitura na coleção de documentos de um único índice de pesquisa, com parâmetros que informam a execução da consulta e moldam a resposta que retorna.

Uma consulta de texto completo é especificada em um search parâmetro e consiste em termos, frases entre aspas e operadores. Outros parâmetros adicionam mais definição à solicitação.

A seguinte chamada Search POST REST API ilustra uma solicitação de consulta usando os parâmetros acima mencionados.

POST https://[service name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2023-11-01
{
    "search": "NY +view",
    "queryType": "simple",
    "searchMode": "all",
    "searchFields": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "select": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "top": "10",
    "count": "true"
}

Pontos principais:

search fornece os critérios de correspondência, geralmente termos ou frases inteiros, com ou sem operadores. Qualquer campo atribuído como "pesquisável" no esquema de índice é um candidato para este parâmetro.
queryType define o analisador: simple, full. O analisador de consulta simples padrão é ideal para pesquisa de texto completo. O analisador de consulta Lucene completo destina-se a construções de consulta avançadas, como expressões regulares, pesquisa de proximidade, pesquisa difusa e curinga. Esse parâmetro também pode ser definido como semantic para classificação semântica para modelagem semântica avançada na resposta da consulta.
searchMode Especifica se as correspondências são baseadas em "todos" os critérios (favorece a precisão) ou "qualquer" critério (favorece a recordação) na expressão. O padrão é "qualquer". Se você prevê o uso intenso de operadores booleanos, o que é mais provável em índices que contêm blocos de texto grandes (um campo de conteúdo ou descrições longas), certifique-se de testar consultas com o searchMode=Any|All parâmetro para avaliar o impacto dessa configuração na pesquisa booleana.
searchFields Restringe a execução da consulta a campos pesquisáveis específicos. Durante o desenvolvimento, é útil usar a mesma lista de campos para selecionar e pesquisar. Caso contrário, uma correspondência pode ser baseada em valores de campo que você não pode ver nos resultados, criando incerteza sobre o motivo pelo qual o documento foi retornado.

Parâmetros usados para moldar a resposta:

select Especifica quais campos devem ser retornados na resposta. Somente os campos marcados como "recuperáveis" no índice podem ser usados em uma instrução select.
top Devolve o número especificado de documentos com melhor correspondência. Neste exemplo, apenas 10 acertos são retornados. Você pode usar top e pular (não mostrado) para paginar os resultados.
count informa quantos documentos em todo o índice correspondem no geral, o que pode ser mais do que o que é retornado.
orderby é usado se você quiser classificar os resultados por um valor, como uma classificação ou local. Caso contrário, o padrão é usar a pontuação de relevância para classificar os resultados. Um campo deve ser atribuído como "classificável" para ser um candidato para este parâmetro.

Escolha um cliente

Para desenvolvimento inicial e testes de prova de conceito, comece com o portal do Azure ou um cliente REST. Ambas as abordagens são interativas, úteis para testes direcionados e ajudam a avaliar os efeitos de diferentes propriedades sem precisar escrever nenhum código.

Para chamar a pesquisa de dentro de um aplicativo, use as bibliotecas de cliente Azure.Document.Search nos SDKs do Azure para .NET, Java, JavaScript e Python.

No portal, ao abrir um índice, você pode trabalhar com o Search Explorer ao lado da definição JSON do índice em guias lado a lado para facilitar o acesso aos atributos de campo. Verifique a tabela Campos para ver quais são pesquisáveis, classificáveis, filtráveis e faceiros durante o teste de consultas.

Entre no portal do Azure e encontre seu serviço de pesquisa.
Abra Índices e selecione um índice.
Um índice é aberto na guia Gerenciador de pesquisa para que você possa consultar imediatamente. Alterne para o modo de exibição JSON para especificar a sintaxe da consulta.

Aqui está uma expressão de consulta de pesquisa de texto completo que funciona para o índice de exemplo Hotéis:
```
   {
       "search": "pool spa +airport",
       "queryType": "simple",
       "searchMode": "any",
       "searchFields": "Description, Tags",
       "select": "HotelName, Description, Tags",
       "top": 10,
       "count": true
   }
```
A captura de tela a seguir ilustra a consulta e a resposta:

Use um cliente REST para configurar uma solicitação. Guia de início rápido: a pesquisa de texto usando REST tem instruções se você precisar de ajuda para começar.

O exemplo a seguir chama a API REST para pesquisa de texto completo:

POST https://[service name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2023-11-01
{
    "search": "NY +view",
    "queryType": "simple",
    "searchMode": "all",
    "searchFields": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "select": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "count": true
}

Os seguintes SDKs do Azure fornecem um SearchClient que tem métodos para formular solicitações de consulta.

SDK do Azure	Cliente	Exemplos
.NET	SearchClient	DotNetHowTo
Java	SearchClient	SearchForDynamicDocumentsExample.java
JavaScript	SearchClient	Exemplos de SDK
Python	SearchClient	sample_simple_query.py

Escolha um tipo de consulta: simples | cheio

Se a sua consulta for pesquisa de texto completo, um analisador de consulta é usado para processar qualquer texto que seja passado como termos e frases de pesquisa. O Azure AI Search oferece dois analisadores de consulta.

O analisador simples compreende a sintaxe de consulta simples. Este analisador foi selecionado como padrão por sua velocidade e eficácia em consultas de texto de forma livre. A sintaxe suporta operadores de pesquisa comuns (AND, OR, NOT) para pesquisas de termos e frases, e pesquisa de prefixo (*) (como em "sea*" para Seattle e Seaside). Uma recomendação geral é experimentar o analisador simples primeiro e, em seguida, passar para o analisador completo se os requisitos do aplicativo exigirem consultas mais poderosas.
A sintaxe de consulta Lucene completa, ativada quando você adiciona queryType=full à solicitação, é baseada no Apache Lucene Parser.

A sintaxe completa e a sintaxe simples se sobrepõem na medida em que ambas suportam o mesmo prefixo e operações booleanas, mas a sintaxe completa fornece mais operadores. Na íntegra, há mais operadores para expressões booleanas e mais operadores para consultas avançadas, como pesquisa difusa, pesquisa curinga, pesquisa de proximidade e expressões regulares.

Escolher métodos de consulta

A pesquisa é fundamentalmente um exercício orientado para o utilizador, em que os termos ou frases são recolhidos a partir de uma caixa de pesquisa ou de eventos de clique numa página. A tabela a seguir resume os mecanismos pelos quais você pode coletar a entrada do usuário, juntamente com a experiência de pesquisa esperada.

Entrada	Experiência
Método de pesquisa	Um usuário digita os termos ou frases em uma caixa de pesquisa, com ou sem operadores, e clica em Pesquisar para enviar a solicitação. A pesquisa pode ser usada com filtros na mesma solicitação, mas não com preenchimento automático ou sugestões.
Método de preenchimento automático	Um usuário digita alguns caracteres e as consultas são iniciadas depois que cada novo caractere é digitado. A resposta é uma cadeia de caracteres concluída do índice. Se a cadeia de caracteres fornecida for válida, o usuário clicará em Pesquisar para enviar essa consulta ao serviço.
Método de sugestões	Assim como no preenchimento automático, um usuário digita alguns caracteres e consultas incrementais são geradas. A resposta é uma lista suspensa de documentos correspondentes, normalmente representados por alguns campos exclusivos ou descritivos. Se qualquer uma das seleções for válida, o usuário clicará em uma e o documento correspondente será retornado.
Navegação por facetas	Uma página mostra links de navegação clicáveis ou trilhas que restringem o escopo da pesquisa. Uma estrutura de navegação facetada é composta dinamicamente com base em uma consulta inicial. Por exemplo, `search=*` para preencher uma árvore de navegação facetada composta por todas as categorias possíveis. Uma estrutura de navegação facetada é criada a partir de uma resposta de consulta, mas também é um mecanismo para expressar a próxima consulta. n A referência `facets` da API REST é documentada como um parâmetro de consulta de uma operação de Pesquisa de Documentos, mas pode ser usada sem o `search` parâmetro.
Método de filtragem	Os filtros são usados com facetas para estreitar os resultados. Você também pode implementar um filtro atrás da página, por exemplo, para inicializar a página com campos específicos do idioma. Na referência da API REST, `$filter` é documentado como um parâmetro de consulta de uma operação de Pesquisa de Documentos, mas pode ser usado sem o `search` parâmetro.

Efeito dos atributos de campo nas consultas

Se você estiver familiarizado com tipos de consulta e composição, talvez se lembre de que os parâmetros em uma solicitação de consulta dependem de atributos de campo em um índice. Por exemplo, apenas os campos marcados como searchable e retrievable podem ser usados em consultas e resultados de pesquisa. Ao definir o search, filtere orderby parâmetros em sua solicitação, você deve verificar os atributos para evitar resultados inesperados.

Na captura de tela do portal abaixo do índice de amostra de hotéis, apenas os dois últimos campos "LastRenovationDate" e "Rating" são sortable, um requisito para uso em uma "$orderby" cláusula única.

Para definições de atributos de campo, consulte Criar índice (API REST).

Efeito dos tokens nas consultas

Durante a indexação, o mecanismo de pesquisa usa um analisador de texto em cadeias de caracteres para maximizar o potencial de encontrar uma correspondência no momento da consulta. No mínimo, as cadeias de caracteres são minúsculas, mas dependendo do analisador, também podem sofrer lemmatização e remoção de palavras paradas. Cadeias de caracteres maiores ou palavras compostas são normalmente divididas por espaços em branco, hífenes ou traços e indexadas como tokens separados.

O ponto a ser tirado aqui é que o que você acha que seu índice contém, e o que realmente está nele, pode ser diferente. Se as consultas não retornarem os resultados esperados, você poderá inspecionar os tokens criados pelo analisador por meio da API REST (Analisar texto). Para obter mais informações sobre tokenização e o impacto nas consultas, consulte Pesquisa parcial de termos e padrões com caracteres especiais.

Próximos passos

Agora que você já entendeu melhor como as solicitações de consulta funcionam, tente os seguintes guias de início rápido para obter uma experiência prática.