Sintaxe de consulta simples no Azure AI Search

  • Artigo

Para cenários de pesquisa de texto completo, o Azure AI Search implementa duas linguagens de consulta baseadas em Lucene, cada uma alinhada a um analisador de consulta. O Simple Query Parser é o padrão. Abrange casos de uso comuns e tentativas de interpretar um pedido, mesmo que não esteja perfeitamente composto. O outro analisador é o Lucene Query Parser e suporta construções de consulta mais avançadas.

Este artigo é a referência de sintaxe de consulta para o analisador de consulta simples.

A sintaxe de consulta para ambos os analisadores aplica-se a expressões de consulta passadas search no parâmetro de uma solicitação de consulta, não confundir com a sintaxe OData, com sua própria sintaxe e regras para filter e orderby expressões na mesma solicitação.

Embora o analisador simples seja baseado na classe Apache Lucene Simple Query Parser, sua implementação no Azure AI Search exclui a pesquisa difusa. Se você precisar de uma pesquisa difusa, considere a sintaxe de consulta Lucene completa alternativa.

Exemplo (sintaxe simples)

Este exemplo mostra uma consulta simples, diferenciada por "queryType": "simple" sintaxe válida. Embora o tipo de consulta esteja definido abaixo, ele é o padrão e pode ser omitido, a menos que você esteja revertendo de um tipo alternativo. O exemplo a seguir é uma pesquisa sobre termos independentes, com um requisito de que todos os documentos correspondentes incluam "pool".

POST https://{{service-name}}.search.windows.net/indexes/hotel-rooms-sample/docs/search?api-version=2024-07-01
{
  "queryType": "simple",
  "search": "budget hotel +pool",
  "searchMode": "all"
}

O searchMode parâmetro é relevante neste exemplo. Sempre que os operadores booleanos estiverem na consulta, você geralmente deve definir searchMode=all para garantir que todos os critérios sejam correspondidos. Caso contrário, você pode usar o padrão searchMode=any que favorece a recuperação em vez da precisão.

Para obter mais exemplos, consulte Exemplos de sintaxe de consulta simples. Para obter detalhes sobre a solicitação de consulta e os parâmetros, consulte Pesquisar documentos (API REST).

Pesquisa de palavras-chave em termos e frases

As cadeias de caracteres passadas para o parâmetro podem incluir termos ou frases em qualquer idioma suportado, operadores booleanos, operadores de precedência, caracteres curinga ou prefixo search para consultas "começa com", caracteres de escape e caracteres de codificação de URL. O search parâmetro é opcional. Não especificado, a pesquisa (search=* ou search=" ") retorna os 50 principais documentos em ordem arbitrária (não classificada).

  • Uma pesquisa de termos é uma consulta de um ou mais termos, onde qualquer um dos termos é considerado uma correspondência.

  • Uma pesquisa de frases é uma frase exata entre aspas " ". Por exemplo, enquanto Roach Motel (sem aspas) procuraria documentos contendo Roach e/ou Motel em qualquer lugar em qualquer ordem, "Roach Motel" (com aspas) só corresponderá a documentos que contenham toda essa frase juntos e nessa ordem (a análise lexical ainda se aplica).

Dependendo do seu cliente de pesquisa, talvez seja necessário escapar das aspas em uma pesquisa de frases. Por exemplo, em uma solicitação POST, uma pesquisa de frase no "Roach Motel" corpo da solicitação pode ser especificada como "\"Roach Motel\"". Se você estiver usando os SDKs do Azure, o cliente de pesquisa escapará das aspas quando serializar o texto de pesquisa. Sua frase de pesquisa pode ser enviada como "Roach Motel".

Por padrão, todas as cadeias de caracteres passadas no parâmetro passam por search análise lexical. Certifique-se de entender o comportamento de tokenização do analisador que você está usando. Muitas vezes, quando os resultados da consulta são inesperados, o motivo pode ser rastreado para como os termos são tokenizados no momento da consulta. Você pode testar a tokenização em cadeias de caracteres específicas para confirmar a saída.

Qualquer entrada de texto com um ou mais termos é considerada um ponto de partida válido para a execução da consulta. A Pesquisa de IA do Azure corresponderá a documentos que contenham qualquer um ou todos os termos, incluindo quaisquer variações encontradas durante a análise do texto.

Por mais simples que isso pareça, há um aspeto da execução de consultas no Azure AI Search que pode produzir resultados inesperados, aumentando em vez de diminuir os resultados da pesquisa à medida que mais termos e operadores são adicionados à cadeia de caracteres de entrada. Se essa expansão realmente ocorre depende da inclusão de um operador NOT, combinado com uma searchMode configuração de parâmetro que determina como NOT é interpretado em termos de AND ou OR comportamentos. Para obter mais informações, consulte o NOT operador em Operadores booleanos.

Operadores booleanas

Você pode incorporar operadores booleanos em uma cadeia de caracteres de consulta para melhorar a precisão de uma correspondência. Na sintaxe simples, os operadores booleanos são baseados em caracteres. Operadores de texto, como a palavra E, não são suportados.

Caráter Exemplo Utilização
+ pool + ocean Uma AND operação. Por exemplo, pool + ocean estipula que um documento deve conter ambos os termos.
| pool | ocean Uma OR operação encontra uma correspondência quando um dos termos é encontrado. No exemplo, o mecanismo de consulta retornará uma correspondência em documentos que contenham um pool ou ocean ambos. Como OR é o operador de conjunção padrão, você também pode deixá-lo de fora, de modo que pool ocean é o equivalente pool | oceana .
- pool – ocean Uma NOT operação retorna correspondências em documentos que excluem o termo.

O searchMode parâmetro em uma solicitação de consulta controla se um termo com o NOT operador é ANDed ou ORed com outros termos na consulta (supondo que não haja operadores booleanos nos outros termos). Os valores válidos incluem any ou all.

searchMode=any aumenta a recuperação de consultas ao incluir mais resultados e, por padrão - , será interpretado como "OU NÃO". Por exemplo, pool - ocean corresponderá a documentos que contêm o termo pool ou aqueles que não contêm o termo ocean.

searchMode=all aumenta a precisão das consultas ao incluir menos resultados e, por padrão - , será interpretado como "E NÃO". Por exemplo, com searchMode=anyo , a consulta pool - ocean corresponderá aos documentos que contêm o termo "pool" e a todos os documentos que não contêm o termo "ocean". Este é, sem dúvida, um comportamento mais intuitivo para o - operador. Portanto, você deve considerar usar searchMode=all em vez de searchMode=any otimizar pesquisas para precisão em vez de recordação, e seus usuários usam frequentemente o - operador em pesquisas.

Ao decidir sobre uma searchMode configuração, considere os padrões de interação do usuário para consultas em vários aplicativos. Os usuários que estão procurando informações são mais propensos a incluir um operador em uma consulta, em oposição aos sites de comércio eletrônico que têm mais estruturas de navegação integradas.

Consultas de prefixo

Para consultas "começa com", adicione um operador de sufixo (*) como o espaço reservado para o restante de um termo. Uma consulta de prefixo deve começar com pelo menos um caractere alfanumérico antes que você possa adicionar o operador de sufixo.

Caráter Exemplo Utilização
* lingui* corresponderá em "linguístico" ou "linguini" O asterisco (*) representa um ou mais caracteres de comprimento arbitrário, ignorando maiúsculas e minúsculas.

Semelhante aos filtros, uma consulta de prefixo procura uma correspondência exata. Como tal, não há pontuação de relevância (todos os resultados recebem uma pontuação de pesquisa de 1,0). Lembre-se de que as consultas de prefixo podem ser lentas, especialmente se o índice for grande e o prefixo consistir em um pequeno número de caracteres. Uma metodologia alternativa, como a tokenização de n-gramas de borda, pode ter um desempenho mais rápido. Os termos que utilizam a pesquisa por prefixo não podem ter mais de 1000 carateres.

A sintaxe simples suporta apenas a correspondência de prefixos. Para correspondência de sufixo ou infix em relação ao final ou meio de um termo, use a sintaxe Lucene completa para pesquisa de curinga.

Escapar aos operadores de pesquisa

Na sintaxe simples, os operadores de pesquisa incluem estes caracteres: + | " ( ) ' \

Se algum desses caracteres fizer parte de um token no índice, escape-o prefixando-o com uma única barra invertida (\) na consulta. Por exemplo, suponha que você usou um analisador personalizado para tokenização de termo inteiro e seu índice contém a cadeia de caracteres "Luxo+Hotel". Para obter uma correspondência exata neste token, insira um caractere de escape: search=luxury\+hotel.

Para simplificar as coisas para os casos mais típicos, há duas exceções a esta regra onde a fuga não é necessária:

  • O operador - NOT só precisa ser escapado se for o primeiro caractere após um espaço em branco. Se o aparece - no meio (por exemplo, em 3352CDD0-EF30-4A2E-A512-3B30AF40F3FD), você pode pular a fuga.

  • O operador * de sufixo só precisa ser escapado se for o último caractere antes de um espaço em branco. Se o * aparece no meio (por exemplo, em 4*4=16), não é necessário escapar.

Nota

Por padrão, o analisador padrão excluirá e quebrará palavras em hífenes, espaço em branco, E comercial e outros caracteres durante a análise lexical. Se você precisar de caracteres especiais para permanecer na cadeia de caracteres de consulta, talvez precise de um analisador que os preserve no índice. Algumas opções incluem analisadores de linguagem natural da Microsoft, que preserva palavras hifenizadas, ou um analisador personalizado para padrões mais complexos. Para obter mais informações, consulte Termos parciais, padrões e caracteres especiais.

Codificação de caracteres não seguros e reservados em URLs

Verifique se todos os caracteres não seguros e reservados estão codificados em uma URL. Por exemplo, '#' é um caractere inseguro porque é um identificador de fragmento/âncora em uma URL. O caractere deve ser codificado para %23 se usado em uma URL. '&' e '=' são exemplos de caracteres reservados, pois delimitam parâmetros e especificam valores no Azure AI Search. Para obter mais informações, consulte RFC1738: URL (Uniform Resource Locators).

Caracteres inseguros são " ` < > # % { } | \ ^ ~ [ ]. Os caracteres reservados são ; / ? : @ = + &.

Carateres especiais

Os caracteres especiais podem variar de símbolos de moeda como '$' ou '€', a emojis. Muitos analisadores, incluindo o analisador padrão padrão, excluirão caracteres especiais durante a indexação, o que significa que eles não serão representados no índice.

Se precisar de representação de caracteres especiais, você pode atribuir um analisador que os preserve:

  • O analisador de espaço em branco considera qualquer sequência de caracteres separada por espaços em branco como tokens (portanto, o emoji '❤' seria considerado um token).

  • Um analisador de idioma, como o Microsoft English Analyzer (en.microsoft), tomaria a string '$' ou '€' como um token.

Para confirmação, você pode testar um analisador para ver quais tokens são gerados para uma determinada cadeia de caracteres. Como seria de esperar, poderá não obter a tokenização completa a partir de um único analisador. Uma solução alternativa é criar vários campos que contêm o mesmo conteúdo, mas com atribuições de analisador diferentes (por exemplo, description_en, description_fr, e assim por diante para analisadores de linguagem).

Ao usar caracteres Unicode, certifique-se de que os símbolos são escapados corretamente na url de consulta (por exemplo, para '❤' usaria a sequência %E2%9D%A4+de escape ). Alguns clientes da Web fazem essa tradução automaticamente.

Precedência (agrupamento)

Você pode usar parênteses para criar subconsultas, incluindo operadores dentro da instrução entre parênteses. Por exemplo, motel+(wifi|luxury) irá procurar documentos que contenham o termo "motel" e "wifi" ou "luxo" (ou ambos).

Limites de tamanho da consulta

Se seu aplicativo gera consultas de pesquisa programaticamente, recomendamos projetá-lo de tal forma que não gere consultas de tamanho ilimitado.

  • Para GET, o comprimento da URL não pode exceder 8 KB.

  • Para POST (e qualquer outra solicitação), onde o corpo da solicitação inclui search e outros parâmetros, como filter e orderby, o tamanho máximo é de 16 MB. Os limites adicionais incluem:

    • O comprimento máximo da cláusula de pesquisa é de 100.000 caracteres.
    • O número máximo de cláusulas em search (expressões separadas por AND ou OR) é 1024.
    • O tamanho máximo do termo de pesquisa é de 1000 caracteres para pesquisa de prefixo.
    • Há também um limite de aproximadamente 32 KB no tamanho de qualquer termo individual em uma consulta.

Para obter mais informações sobre limites de consulta, consulte Limites de solicitação de API.

Próximos passos

Se você estiver construindo consultas programaticamente, revise a pesquisa de texto completo no Azure AI Search para entender os estágios do processamento de consultas e as implicações da análise de texto.

Você também pode revisar os seguintes artigos para saber mais sobre a construção de consultas: