Sintaxe de consulta simples no Pesquisa de IA do Azure 

Para cenários de pesquisa de texto completo, Pesquisa de IA do Azure  implementa duas linguagens de consulta baseadas em Lucene, cada uma alinhada a um analisador de consulta. O Analisador de Consulta Simples é o padrão. Ele aborda casos de uso comuns e tenta interpretar uma solicitação mesmo que ela não seja perfeitamente composta. O outro analisador é o Analisador de Consultas Lucene e dá suporte a construções de consulta mais avançadas.

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

A sintaxe de consulta para ambos os analisadores aplica-se às expressões de consulta passadas no search parâmetro de uma solicitação de consulta, para não serem confundidas 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 Pesquisa de IA do Azure  exclui a pesquisa difusa. Se você precisar de uma busca aproximada, considere a sintaxe de consulta completa do Lucene como alternativa.

Exemplo (sintaxe simples)

Este exemplo mostra uma consulta simples, distinguida por "queryType": "simple" e uma 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=2025-09-01
{
  "queryType": "simple",
  "search": "budget hotel +pool",
  "searchMode": "all"
}

O searchMode parâmetro é relevante neste exemplo. Sempre que os operadores boolianos 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 o recall sobre a 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 palavra-chave em termos e frases

As cadeias de caracteres passadas para o search parâmetro podem incluir termos ou frases em qualquer idioma compatível, operadores booleanos, operadores de precedência, caracteres curinga ou de prefixo 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, em que 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) corresponderá apenas a documentos que contêm essa frase inteira em conjunto e nessa ordem (a análise léxica ainda se aplica).

Dependendo do 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 o SDKs do Azure, o cliente de pesquisa escapará das aspas quando serializar o texto de pesquisa. Sua frase de pesquisa pode ser enviada como "Motel Roach".

Por padrão, todas as cadeias de caracteres passadas no search parâmetro passam por análise lexical. Certifique-se de entender o comportamento de tokenização do analisador que você está usando. Geralmente, quando os resultados da consulta são inesperados, o motivo pode ser rastreado até 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. 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 aspecto da execução da consulta no Pesquisa de IA do Azure  que pode produzir resultados inesperados, aumentando em vez de diminuir os resultados da pesquisa à medida que mais termos e operadores são adicionados ao texto 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 mais informações, consulte o operador NOT em operadores boolianos.

Operadores boolianos

Você pode embutir operadores boolianos em uma string de consulta para melhorar a precisão de uma correspondência. Na sintaxe simples, os operadores boolianos são baseados em caracteres. Não há suporte para operadores de texto, como a palavra AND.

Caractere Exemplo Uso
+ 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 localiza uma correspondência quando um dos termos é encontrado. No exemplo, o mecanismo de consulta retornará uma correspondência em documentos que contêm pool, ocean ou ambos. Como OR é o operador de conjunção padrão, você também pode deixá-lo de fora, de modo que pool ocean seja o equivalente a pool | ocean.
- pool – ocean Uma operação NOT retorna resultados em documentos que excluem o termo.

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

searchMode=any aumenta o recall de consultas incluindo 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 incluindo menos resultados e, por padrão - , será interpretado como "E NÃO". Por exemplo, com searchMode=any, a consulta pool - ocean corresponderá a documentos que contêm o termo "pool" e todos os documentos que não contêm o termo "oceano". Esse é, sem dúvida, um comportamento mais intuitivo para o - operador. Portanto, você deve considerar usar searchMode=all em vez de searchMode=any para otimizar pesquisas para precisão em vez de recall, e os seus usuários frequentemente usam 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 vez de sites de comércio eletrônico que têm estruturas de navegação mais internas.

Consultas de prefixo

Para consultas "que começam 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 de texto sem formatação antes de adicionar o operador de sufixo.

Caractere Exemplo Uso
* 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. Dessa forma, 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 por n-grama de borda, pode desempenhar mais rapidamente. Os termos que usam a pesquisa de prefixo não podem ter mais de 1000 caracteres.

A sintaxe simples dá suporte apenas à correspondência de prefixo. Para correspondência de sufixo ou infixo no final ou no meio de um termo, use a Sintaxe Lucene completa para pesquisa com curinga.

Escape de 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ê tenha usado um analisador personalizado para tokenização de termo inteiro e seu índice contenha a cadeia de caracteres "Luxury+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 essa regra em que o escape não é necessário:

  • O operador "NOT" - só precisará ser escapado se for o primeiro caractere após um espaço em branco. Se - aparecer no meio (por exemplo, em 3352CDD0-EF30-4A2E-A512-3B30AF40F3FD), você pode ignorar o escape.

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

Nota

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

Codificar 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 não seguro porque é um identificador de fragmento/âncora em uma URL. O caractere deve ser codificado para %23 se usado em URL. '& ' e '=' são exemplos de caracteres reservados, pois delimitam parâmetros e especificam valores em Pesquisa de IA do Azure . Para obter mais informações, consulte RFC1738: URL (Uniform Resource Locators).

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

Caracteres especiais

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.

Caso você precise de uma representação de caracteres especiais, pode atribuir um analisador que os preserve.

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

  • Um analisador de linguagem , como o analisador de inglês da Microsoft (), trataria 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 era de se esperar, talvez você não obtenha a tokenização completa de um único analisador. Uma solução alternativa é criar vários campos que contêm o mesmo conteúdo, mas com diferentes atribuições de analisador (por exemplo, description_en, description_fre assim por diante para analisadores de idioma).

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

Precedência (agrupamento)

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

Limites de tamanho da consulta

Se o seu aplicativo gerar consultas de pesquisa programaticamente, recomendamos projetá-lo de forma que ele 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), em que o corpo da solicitação inclui search e outros parâmetros, como filter e orderby, o tamanho máximo é de 16 MB. 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 os limites de solicitação de API.

Próximas etapas

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

Você também pode examinar os seguintes artigos para saber mais sobre a construção da consulta:

  • Last updated on