Sintaxe de consulta Lucene na Pesquisa de IA do Azure

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

Para usar a sintaxe Lucene completa, defina queryType como full e passe uma expressão de consulta padronizada para curinga, pesquisa difusa ou um dos outros formulários de consulta suportados pela sintaxe completa. Em REST, as search expressões de consulta são fornecidas no parâmetro 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 a pesquisa por campos e o reforço de relevância de expressões. Procura hotéis onde o campo de categoria contém o termo budget. Os documentos que contêm a expressão "recently renovated" recebem uma ponderação adicional e podem ficar melhor classificados em resultado do valor de reforço da expressão (3).

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 nenhum tipo de consulta, o searchMode parâmetro é relevante neste exemplo. Sempre que os operadores estiverem na consulta, você geralmente 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, incluindo searchMode, consulte Pesquisar documentos (API REST).

Fundamentos da sintaxe

Os fundamentos de sintaxe a seguir se aplicam a todas as consultas que usam a sintaxe Lucene.

Avaliação do 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 de Lucene, a tilde (~) é usada tanto para pesquisa fuzzy quanto para pesquisa de proximidade. Quando colocado após uma frase citada, ~ invoca a pesquisa de proximidade. Quando colocado no final de um termo, ~ invoca a pesquisa difusa.

Dentro de um termo, como business~analyst, o personagem não é avaliado como um operador. Neste caso, assumindo que a consulta é de termo ou de frase, a pesquisa de texto completo com análise lexical elimina o e divide o termo em dois: ~ ou business~analyst.

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

Escapando de caracteres especiais

Para usar qualquer um dos operadores de pesquisa como parte do texto de pesquisa, escape do caractere prefixando-o com uma única barra invertida (\). Por exemplo, para uma pesquisa com caracteres curinga no https://, onde :// faz parte da cadeia de caracteres de consulta, deverá especificar search=https\:\/\/*. Da mesma forma, um padrão de número de telefone escapado pode ter esta aparência \+1 \(800\) 642\-7676.

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

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 à medida que delimitam parâmetros e especificam valores no Pesquisa de IA do Azure. Consulte RFC1738: Uniform Resource Locators (URL) para obter mais detalhes.

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

Operadores booleanas

Você pode incorporar operadores booleanos em uma cadeia de caracteres de consulta para melhorar a precisão de uma correspondência. A sintaxe completa suporta operadores de texto, além de operadores de caracteres. Sempre especifique operadores booleanos de texto (AND, OR, NOT) em todas as maiúsculas.

1 O | caractere não é suportado para operações OR.

NÃO operador booleano

• Em 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, 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, 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 estivessem sempre ANDed na consulta, independentemente do modo de pesquisa.
  • Por exemplo, a consulta wifi -luxury de sintaxe completa em sintaxe completa busca apenas documentos que contenham o termo wifie, em seguida, aplica a negação -luxury a esses documentos.
• Se você quiser usar negações para pesquisar todos os documentos no índice, recomenda-se uma sintaxe simples com o any modo de pesquisa.
• Se você quiser usar negações para pesquisar num subconjunto de documentos no índice, recomenda-se a sintaxe completa ou a sintaxe simples com o modo de pesquisa "todos".

Pesquisa por campos

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

• genre:jazz NOT history

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

Certifique-se de colocar várias cadeias entre aspas se quiser que ambas as cadeias sejam avaliadas como uma única entidade, neste caso procurando por dois artistas distintos no artists campo.

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

Pesquisa aproximada

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

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

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

Pesquisa por proximidade

As pesquisas de proximidade são usadas para encontrar termos próximos uns dos outros em um documento. Insira um símbolo de til ~ no final de uma frase, seguido pelo número de palavras que definem o limite de proximidade. Por exemplo, "hotel airport"~5 localiza os termos hotel e airport dentro de cinco palavras um do outro em um documento.

Aumento da relevância de termos

Pensa na pesquisa como dois passos. Primeiro, o Pesquisa de IA do Azure encontra documentos correspondentes. Em seguida, classifica essas correspondências. O aumento de termos afeta apenas o segundo passo: pode mover documentos que correspondam a uma parte da sua consulta para mais alto nos resultados.

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

Âmbito de impulso

Escreva um acento circunflexo (^) e um número positivo imediatamente após a parte da consulta que pretende favorecer. Por exemplo, tax^2 pode mover documentos que contenham tax mais do que documentos que correspondam apenas a um termo não reforçado. O valor padrão do boost é 1. Também pode usar um valor entre 0 e 1, como 0.2, para atribuir menos peso a uma correspondência.

A pontuação indica a que palavras cada instrução se aplica:

• Um nome de campo mais dois pontos, chamado prefixo de campo, aparece antes de uma palavra, frase entre aspas ou grupo entre parênteses. Por exemplo, content: indica ao Pesquisa de IA do Azure para procurar no campo content.
• Um aumento, como ^2, aparece após uma palavra, frase citada ou grupo entre parênteses. Indica ao Pesquisa de IA do Azure o que deve privilegiar na classificação das correspondências.

A tabela seguinte usa o padrão searchMode=any, onde um espaço entre palavras funciona como OR.

Com searchMode=all, a consulta deferred tax^2 requer que ambas as palavras coincidam. O aumento continua a aplicar-se apenas a tax. Para corresponder a qualquer uma das palavras, escreva deferred OR tax^2.

Coloque o cursor após as aspas ou o parêntese de fecho quando quiser dar ênfase à frase ou ao grupo na totalidade. Parênteses não criam uma frase. Use aspas quando as palavras têm de estar lado a lado e numa ordem específica.

Amplificação e alcance de campo

Um nome de campo seguido de dois pontos limita o local onde o Pesquisa de IA do Azure procura. Um impulso altera a forma como o Pesquisa de IA do Azure classifica uma correspondência. Podes usar ambos na mesma consulta.

Por exemplo, se searchFields for definido como title, a primeira consulta procura deferred em content e tax em title. As aspas e os parênteses nas outras consultas mantêm as duas palavras em content.

Efeito de um analisador nas consultas aumentadas

Para palavras, frases e grupos de palavras normais, o boost não ignora a análise de texto. Antes de combinar, o Pesquisa de IA do Azure continua a processar o texto da consulta com o analisador de cada campo. Como resultado, o mesmo texto aumentado pode corresponder de forma diferente em campos que utilizam analisadores diferentes.

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

Outras formas de consulta, como curinga, expressão regular e consultas fuzzy, utilizam regras de análise diferentes. Adicionar um reforço não altera essas regras. Para mais informações, veja Fase 2: Análise lexical.

Pesquisa de expressões regulares

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

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

• Fechado entre barras inclinadas /
• Apenas minúsculas

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

Algumas ferramentas e linguagens impõem necessidades de caracteres de escape adicionais além das regras de escape impostas pelo Pesquisa de IA do Azure. Para JSON, as cadeias de caracteres que incluem uma barra para frente são escapadas com uma barra invertida: microsoft.com/azure/ torna-se search=/.*microsoft.com\/azure\/.*/ onde search=/.* <string-placeholder>.*/ configura a expressão regular e microsoft.com\/azure\/ é a cadeia de caracteres com a barra para frente escapada com uma barra invertida.

Dois símbolos comuns em consultas regex são . e *. A . corresponde a qualquer caractere e a * corresponde ao caractere anterior zero ou mais vezes. Por exemplo, /be./ corresponde aos termos bee e bet while /be*/ corresponderia a be, beee beee mas não bet. Juntos, .* permitem-lhe corresponder a qualquer série de caracteres, de modo que /be.*/ corresponda a qualquer termo que comece com be, tal como better.

Se receber erros de sintaxe na sua expressão regular, rever 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 com caracteres universais

Você pode usar a sintaxe amplamente reconhecida para pesquisas curinga de um único carácter ou de vários caracteres (* ou ?). Sintaxe Lucene completa suporta correspondência de prefixo e infixo. Use a sintaxe de expressão regular para correspondência de sufixos.

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

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

A correspondência de sufixos requer delimitadores de barra inclinada / na expressão regular. Geralmente, não é possível usar um * símbolo ou ? como o primeiro caractere de um termo, sem o /. Também é importante notar que o * se comporta de forma diferente quando usado fora das consultas regex. Fora do delimitador de barra inclinada direta do regex /, o * é um caractere curinga e corresponde a qualquer série de caracteres, muito parecido com o .* no regex. Como 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 da consulta, as consultas formuladas como prefixo, sufixo, caracter curinga ou expressões regulares são passadas tal como estão para a árvore de consulta, ignorando a análise lexical. As correspondências só serão encontradas se o índice contiver as cadeias de caracteres no formato especificado pela consulta. Na maioria dos casos, você precisa de um analisador durante a indexação que preserve a integridade da cadeia de caracteres para que a correspondência parcial de termos e padrões seja bem-sucedida. Para obter mais informações, consulte Pesquisa parcial de termos em consultas do Pesquisa de IA do Azure.

Considere uma situação em que você pode desejar que a consulta terminal* de pesquisa retorne resultados que contenham termos como terminate, terminatione terminates.

Se usares o analisador en.lucene (inglês Lucene), ele aplicaria uma redução agressiva de cada termo. Por exemplo, terminate, termination, terminates todos serão tokenizados até o token termi em seu índice. Por outro lado, os termos nas consultas que usam curingas ou pesquisa por similaridade não são analisados, portanto, não haveria resultados que correspondessem à consulta terminat*.

Por outro lado, os analisadores da Microsoft (neste caso, o analisador en.microsoft) são um pouco mais avançados e usam lematização em vez de stemming. Isso significa que todos os tokens gerados devem ser palavras válidas em inglês. Por exemplo, terminate, terminates e termination permanecerão praticamente inteiros no índice, e seriam uma escolha preferível para cenários que dependem muito de caracteres universais e pesquisa difusa.

Pontuação de consultas curinga e regex

O Pesquisa de IA do Azure usa pontuação baseada em frequência (BM25) para consultas de texto. No entanto, para consultas curinga e regex em que o escopo dos termos pode ser potencialmente amplo, o fator de frequência é ignorado para evitar que a classificação tenda para correspondências de termos mais raros. Todas as correspondências são tratadas igualmente para pesquisas de caracteres curinga e regex.

Caracteres especiais

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

Os analisadores que tokenizam caracteres especiais incluem o analisador de espaço em branco, que leva em consideração quaisquer 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"), tomaria a string "€" 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 são codificados corretamente na URL de consulta (por exemplo, para ❤, usar a sequência de escape %E2%9D%A4+). Alguns clientes REST fazem essa tradução automaticamente.

Precedência (agrupamento)

Use parênteses para controlar que partes de uma consulta são avaliadas em conjunto. 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 entre parênteses para pesquisar todo esse grupo num campo. Por exemplo, hotelAmenities:(wifi OR pool) procura wifi ou pool apenas no hotelAmenities campo.

Parênteses controlam como AND e OR trabalham em conjunto. Não exigem que as palavras apareçam lado a lado ou numa ordem específica. Use aspas para esse comportamento. Para reforçar um grupo, coloque o caret após a parêntese final, como em hotelAmenities:(wifi OR pool)^2. Para mais informações, consulte Amplificação do telescópio.

Limites de tamanho da consulta

O Pesquisa de IA do Azure impõe limites ao tamanho e à composição da consulta porque consultas não limitadas podem desestabilizar o seu serviço de pesquisa. Há limites para o tamanho e a 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 com curinga. Se seu aplicativo gera consultas de pesquisa programaticamente, recomendamos projetá-lo de tal forma que não gere consultas de tamanho ilimitado.

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

Consulte também

• Exemplos de consulta para pesquisa simples
• Exemplos de consulta para pesquisa completa de Lucene
• Pesquisa de documentos
• Sintaxe da expressão OData para filtros e classificação
• Sintaxe de consulta simples no Pesquisa de IA do Azure