Sintaxe de consulta do Lucene na IA do Azure Search

Ao criar consultas na IA do Azure Search, você pode optar pela sintaxe completa do Analisador de Consulta do Lucene para formulários de consulta especializados: curinga, pesquisa difusa, pesquisa por proximidade, expressões regulares. Grande parte da sintaxe do Analisador de Consultas do Lucene é implementada intacta na Pesquisa de IA do Azure, exceto para pesquisas de intervalo, que são criadas por meio de expressões $filter.

Para usar a sintaxe do Lucene completa, defina o queryType como full e passe uma expressão de consulta padronizada para curinga, pesquisa difusa ou um dos outros formulários de consulta com suporte na sintaxe completa. Em REST, as expressões de consulta são fornecidas no parâmetro search de uma solicitação de Documentos de pesquisa (API REST).

Exemplo (sintaxe completa)

O exemplo a seguir é uma solicitação de pesquisa construída usando a sintaxe completa. Este exemplo específico mostra busca por campo e priorização de frases. Isso procura por hotéis em que o campo categoria contém o termo budget. Os documentos que contêm a frase "recently renovated" recebem um peso adicional de relevância e, como resultado do valor de reforço da frase (3), podem ter uma classificação mais alta.

POST /indexes/hotels-sample/docs/search?api-version=2026-04-01
{
  "queryType": "full",
  "search": "category:budget AND \"recently renovated\"^3",
  "searchMode": "all"
}

Embora não seja específico para qualquer tipo de consulta, o parâmetro searchMode é relevante neste exemplo. Sempre que os operadores estiverem na consulta, geralmente você deve definir searchMode=all para garantir que todos os critérios sejam correspondidos.

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

Conceitos básicos da sintaxe

Os conceitos básicos de sintaxe a seguir se aplicam a todas as consultas que usam a sintaxe do Lucene.

Avaliação de operador no contexto

O posicionamento determina se um símbolo é interpretado como um operador ou apenas outro caractere em uma cadeia de caracteres.

Por exemplo, na sintaxe completa do Lucene, o til (~) é usado na pesquisa difusa e na pesquisa por proximidade. Quando colocado depois de uma frase entre aspas, ~ invoca a pesquisa por proximidade. Quando colocado no final de um termo, ~ invoca a pesquisa difusa.

Dentro de um termo, como business~analyst, o caractere não é avaliado como um operador. Nesse caso, considerando que a consulta seja uma consulta de termo ou de frase, a pesquisa de texto completo com análise léxica retira o ~ e divide o termo business~analyst em dois: business OU analyst.

O exemplo acima usa o til (~), mas o mesmo princípio se aplica a todos os operadores.

Caracteres especiais de escape

Para usar qualquer um dos operadores como parte do texto de pesquisa, escape o caractere prefixando-o com uma barra invertida única (\). Por exemplo, para uma pesquisa de curinga em https://, em que :// é parte da cadeia de caracteres de consulta, você especificaria search=https\:\/\/*. Da mesma forma, um padrão de número de telefone de escape pode ser assim \+1 \(800\) 642\-7676.

Os caracteres especiais que exigem escape incluem o seguinte:
+ - & | ! ( ) { } [ ] ^ " ~ * ? : \ /

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

Verifique se todos os caracteres reservados e não seguros estão codificados em uma URL. Por exemplo, # é um caractere desprotegido por ser um identificador de fragmento/âncora em uma URL. O caractere deverá ser codificado como %23 se for usado em uma URL. & e = são exemplos de caracteres reservados pois delimitam parâmetros e especificam valores na Pesquisa de IA do Azure. Consulte RFC1738: URL (Uniform Resource Locators) para obter mais detalhes.

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

Operadores booleanos

Você pode inserir operadores boolianos em uma cadeia de caracteres de consulta para melhorar a precisão de uma correspondência. A sintaxe completa oferece suporte a operadores de texto, além de operadores de caracteres. Sempre especifique operadores boolianos de texto (AND, OR, NOT) com tudo em maiúsculas.

¹ O caractere | não tem suporte em operações OR.

Operador booliano de expressão NOT lógica

• Na sintaxe simples, as consultas com negação sempre têm um curinga adicionado automaticamente. Por exemplo, a consulta -luxury é expandida automaticamente para -luxury *.
• Na sintaxe completa, as consultas com negação não podem ser combinadas com um curinga. Por exemplo, as consultas -luxury * não são permitidas.
• Na sintaxe completa, as consultas com uma única negação não são permitidas. Por exemplo, a consulta -luxury não é permitida.
• Na sintaxe completa, as negações se comportarão como se fossem sempre ANDed na consulta, independentemente do modo de pesquisa.
  • Por exemplo, a consulta de sintaxe completa wifi -luxury na sintaxe completa só busca documentos que contêm o termo wifi e aplica a negação -luxury a esses documentos.
• Se desejar usar negações para pesquisar todos os documentos no índice, é recomendável obter uma sintaxe simples com o modo de pesquisa any.
• Se desejar usar negações para pesquisar um subconjunto de documentos no índice, será recomendáveis obter a sintaxe completa ou a sintaxe simples com todo o modo de pesquisa.

Pesquisa com campos

Você pode definir uma operação de pesquisa em campo com a sintaxe fieldName:searchExpression, em que a expressão de pesquisa pode ser uma única palavra ou frase, ou uma expressão mais complexa entre parênteses, opcionalmente com operadores boolianos. Alguns exemplos incluem o seguinte:

• genre:jazz NOT history

• artists:("Miles Davis" "John Coltrane")

Coloque várias cadeias de caracteres entre aspas se quiser que ambas cadeias de caracteres sejam avaliadas como uma única entidade, como neste caso, pesquisar duas cidades distintas no campo artists.

O campo especificado em fieldName:searchExpression deve ser um campo searchable. Confira Criar Índice para obter detalhes sobre como os atributos de índice são usados em definições de campo.

Pesquisa difusa

Uma pesquisa difusa localiza correspondências em termos que têm uma construção semelhante, expandindo um termo até o máximo de 50 que atendem aos critérios de distância de dois ou menos. Para obter mais informações, consulte Pesquisa difusa.

Para fazer uma pesquisa difusa, use o símbolo til ~ no final de uma única palavra com um parâmetro opcional, um número entre 0 e 2 (padrão), que especifica a distância de edição. Por exemplo, blue~ ou blue~1 retornaria blue, blues e glue.

A pesquisa difusa só pode ser aplicada a termos, não a frases entre aspas, mas você pode acrescentar o til em cada termo individualmente num nome ou frase com várias partes. Por exemplo, Unviersty~ of~ Wshington~ corresponderia a University of Washington.

Pesquisa por proximidade

As pesquisas de proximidade são usadas para localizar termos que estejam próximos um do outro em um documento. Insira um símbolo til ~ no final de uma frase seguida pelo número de palavras que criam o limite de proximidade. Por exemplo, "hotel airport"~5 localiza os termos hotel e airport dentro de cinco palavras umas das outras em um documento.

Aumento de termos

Pense na pesquisa como duas etapas. Primeiro, Pesquisa de IA do Azure  localiza documentos correspondentes. Em seguida, classifica essas correspondências. O reforço de termos afeta apenas a segunda etapa: ele pode mover documentos que correspondem a uma parte da sua consulta para posições mais altas nos resultados.

O reforço de termos difere de um perfil de pontuação. Um reforço favorece uma palavra, frase ou grupo na consulta atual. Um perfil de pontuação favorece campos ou outro conteúdo de índice de acordo com as regras definidas no índice.

Ampliação de escopo

Escreva um acento circunflexo (^) e um número positivo imediatamente após a parte da consulta que você deseja favorecer. Por exemplo, tax^2 pode mover documentos que contêm tax para posições mais altas do que documentos que correspondem apenas a um termo sem reforço. O valor de aumento padrão é 1. Você também pode usar um valor entre 0 e 1, como 0.2, para atribuir menos peso a uma correspondência.

A pontuação informa quais palavras cada instrução afeta:

• Um nome de campo seguido de dois-pontos, chamado prefixo de campo, aparece antes de uma palavra, uma frase entre aspas ou um grupo entre parênteses. Por exemplo, content: instrui o Pesquisa de IA do Azure  a procurar no campo content.
• Um reforço, como ^2, aparece após uma palavra, frase entre aspas ou grupo entre parênteses. Ele diz a Pesquisa de IA do Azure  o que favorecer ao classificar as partidas.

A tabela a seguir usa o padrão searchMode=any, em que um espaço entre palavras funciona como OR.

Com searchMode=all, a consulta deferred tax^2 requer que ambas as palavras correspondam. O aumento ainda se aplica apenas a tax. Para corresponder a qualquer palavra em vez disso, escreva deferred OR tax^2.

Coloque o cursor após a aspa ou parêntese de fechamento quando quiser aumentar toda a frase ou grupo. Parênteses não criam uma frase. Use aspas quando as palavras devem estar próximas umas das outras e em uma ordem específica.

Reforço e escopo do campo

Um nome de campo seguido por dois pontos limita onde a Pesquisa de IA do Azure procura. Um reforço altera a forma como a Pesquisa de IA do Azure classifica uma correspondência. Você pode usar ambos na mesma consulta.

Por exemplo, se searchFields estiver definido como title, a primeira consulta procurará por deferred em content e por tax em title. As aspas e os parênteses nas outras consultas mantêm ambas as palavras em content.

Efeito de um analisador em consultas reforçadas

Para palavras, frases e grupos de palavras comuns, o reforço não ignora a análise de texto. Antes de corresponder, Pesquisa de IA do Azure  ainda processa o texto da consulta com o analisador de cada campo. Como resultado, o mesmo texto aumentado pode corresponder de forma diferente em campos que usam analisadores diferentes.

Uma frase ou grupo com um prefixo de campo usa o analisador desse campo. O texto sem um prefixo de campo usa o analisador para cada campo que está sendo pesquisado. Por exemplo, um analisador que altera o texto em letras minúsculas pode corresponder "DEFERRED TAX"^2 a termos indexados em letras minúsculas.

Outros formulários de consulta, como curinga, expressão regular e consultas difusas, usam regras de análise diferentes. Adicionar um impulso não altera essas regras. Para obter mais informações, consulte Estágio 2: análise lexical.

Pesquisa com expressão regular

Uma pesquisa de expressão regular localiza uma correspondência com base em padrões que são válidos no Apache Lucene, conforme documentado na classe RegExp.

Na Pesquisa de IA do Azure, uma expressão regular é:

• Entre barras /
• Apenas minúsculas

Por exemplo, para localizar documentos contendo motel ou hotel, especifique /[mh]otel/. As pesquisas com expressões regulares são comparadas com palavras individuais.

Algumas ferramentas e idiomas impõem requisitos extras de caracteres de escape além das regras de escape impostas pela Pesquisa de IA do Azure. Para o JSON, as cadeias de caracteres que incluem uma barra são repassadas com uma barra invertida: microsoft.com/azure/ torna-se search=/.*microsoft.com\/azure\/.*/ em que search=/.* <string-placeholder>.*/ configura a expressão regular e microsoft.com\/azure\/ é a cadeia de caracteres com uma barra de escape.

Dois símbolos comuns em consultas regex são . e *. Um . corresponde a qualquer caractere, e um * corresponde ao caractere anterior zero ou mais vezes. Por exemplo, /be./ corresponde aos termos bee e bet ao mesmo tempo /be*/ corresponderia a be, bee e beee, mas não bet. Juntos, .* permite que você faça a correspondência de qualquer série de caracteres, ou seja, /be.*/ corresponderá a qualquer termo que comece com be, como better.

Se você receber erros de sintaxe em sua expressão regular, examine as regras de escape para caracteres especiais. Você também pode tentar um cliente diferente para confirmar se o problema é específico da ferramenta.

Pesquisa de curinga

Você pode usar a sintaxe geralmente reconhecida para pesquisas com vários caracteres curinga (*) ou um caractere curinga (?). A sintaxe completa do Lucene dá suporte à correspondência de prefixo e infixo. Use a sintaxe de expressão regular para a correspondência de sufixo.

Observe que o analisador de consulta Lucene oferece suporte ao uso desses símbolos com um único termo e não uma frase.

Você pode combinar operadores em uma expressão. Por exemplo, 980?2* corresponde a 98072-1222 e 98052-1234, em que ? corresponde a um só caractere (obrigatório) e * corresponde a caracteres de um comprimento arbitrário que se seguem.

A correspondência de sufixo exige os delimitadores / de barra '/' de expressão regular. Em geral, não é possível usar um símbolo * ou ? como o primeiro caractere de um termo, sem o /. Também é importante observar que o * se comporta de maneira diferente quando usado fora das consultas regex. Além do delimitador / da barra regex, o * é um caractere curinga e corresponde a qualquer série de caracteres, muito semelhante ao .* em regex. Por exemplo, search=/non.*al/ produz o mesmo conjunto de resultados que search=non*al.

Efeito de um analisador em consultas curinga

Durante a análise de consulta, as consultas que são formuladas como prefixo, sufixo, curinga ou expressões regulares são passadas como estão para a árvore de consulta, ignorando a análise léxica. As correspondências só serão encontradas se o índice contiver as cadeias de caracteres no formato especificado pela sua consulta. Na maioria dos casos, durante a indexação, você precisa de um analisador que preserve a integridade da cadeia de caracteres para que o termo parcial e os padrões correspondentes obtenham êxito. Para obter mais informações, consulte Pesquisa de termo parcial nas consultas da IA do Azure Search.

Considere uma situação em que você deseje que a consulta de pesquisa terminal* retorne resultados contendo termos como terminate, termination e terminates.

Se você fosse usar o analisador en.lucene (Inglês Lucene), ele aplicaria uma lematização (corte de afixos para chegar ao radical) agressiva de cada termo. Por exemplo, todos os terminate, termination, terminates gerarão tokens até o token termi em seu índice. Por outro lado, os termos em consultas que usam curingas ou pesquisa difusa não são analisados, sendo assim, não haveria nenhum resultado correspondente à consulta terminat*.

Por outro lado, os analisadores da Microsoft (neste caso, o en.microsoft) são um pouco mais avançados e usam a lematização (leva em consideração a análise morfológica). Isso significa que todos os tokens gerados devem ser palavras válidas em inglês. Por exemplo, terminate, terminates e termination permanecerão em sua maioria, inteiros no índice e seriam a melhor opção em cenários que dependem muito de curingas e pesquisa difusa.

Classificar consultas de caractere curinga e regex

A IA do Azure Search usa a pontuação baseada em frequência (BM25) para consultas de texto. No entanto, para consultas curinga e regex em que o escopo de termos pode ser potencialmente amplo, o fator de frequência é ignorado para impedir que a classificação seja direcionada para correspondências de termos mais raros. Todas as correspondências são tratadas da mesma maneira para as pesquisas de caractere curinga e regex.

Caracteres especiais

Em determinadas circunstâncias, talvez você deseje procurar um caractere especial, como um emoji '❤' ou o sinal '€'. Nesses casos, certifique-se de que o analisador usado não filtra esses caracteres. O analisador padrão ignora muitos caracteres especiais, excluindo-os do índice.

Os analisadores que geram tokens de caracteres especiais incluem o analisador de espaço em branco, que considera todas as sequências de caracteres separadas por espaços em branco como tokens (portanto, a cadeia de caracteres ❤ seria considerada um token). Além disso, um analisador de linguagem como o Microsoft English Analyzer ("en.microsoft"), entenderia a cadeia de caracteres "€" como um token. Você pode testar um analisador para ver quais tokens ele gera para uma determinada consulta.

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

Precedência (agrupamento)

Use parênteses para controlar quais partes de uma consulta são avaliadas juntas. Por exemplo, motel AND (wifi OR luxury) requer motel e pelo menos um dos termos dentro dos parênteses: wifi ou luxury.

Coloque um prefixo de campo antes de um grupo parêntese para pesquisar todo esse grupo em um campo. Por exemplo, hotelAmenities:(wifi OR pool) procura wifi ou pool apenas no hotelAmenities campo.

Parênteses controlam como AND e OR trabalham juntos. Eles não exigem que as palavras apareçam ao lado umas das outras ou em uma ordem específica. Use aspas para esse comportamento. Para reforçar um grupo, coloque o acento circunflexo após o parêntese de fechamento, como em hotelAmenities:(wifi OR pool)^2. Para obter mais informações, consulte o escopo do Boost.

Limites de tamanho de consulta

A IA do Azure Search impõe limites no tamanho e na composição da consulta, porque as consultas desassociadas podem desestabilizar o serviço de pesquisa. Há limites no tamanho e na composição da consulta (o número de cláusulas). Também existem limites para o comprimento da pesquisa de prefixo e para a complexidade da pesquisa regex e da pesquisa de curinga. Se seu aplicativo gerar consultas de pesquisa por meio de programação, é recomendável criá-lo de forma que não gere consultas de tamanho ilimitado.

Para saber mais sobre os limites de consulta, confira Limites de solicitação de API.

Consulte também

• Exemplos de consulta para pesquisa simples
• Exemplos de consulta para pesquisa completa do Lucene
• Pesquisar Documentos
• Sintaxe de expressão OData para filtros e classificação
• Sintaxe de consulta simples na Pesquisa de IA do Azure