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, pois essas são construídas por meio das 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 a pesquisa em campo e o aumento de termos. Isso procura por hotéis em que o campo categoria contém o termo budget. Todo documento com a frase "recently renovated" apresentam uma classificação superior como um resultado do valor de aumento de termo (3).

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-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 ao delimitarem parâmetros e especificarem valores na IA do Azure Search. Consulte RFC1738: URL (Uniform Resource Locator) 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 para 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 em campo

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

O aumento de termos refere-se ao aumento da classificação de um documento caso contenha o termo aumentado, em relação aos documentos que não contêm o termo. Isso é diferente dos perfis de pontuação, já que os perfis de pontuação aumentam determinados campos, em vez de termos específicos.

O exemplo a seguir ajuda a ilustrar as diferenças. Considere um perfil de pontuação que aumente as correspondências em um determinado campo, como gênero no exemplo de índice de loja de música. O aumento de termos pode ser usado para melhorar a posição de determinados termos de pesquisa. Por exemplo, rock^2 electronic aumenta os documentos que contêm os termos de pesquisa no campo gênero, à frente de outros campos pesquisáveis no índice. Além disso, os documentos com o termo de pesquisa rock são melhor classificados do que o outro termo de pesquisa eletrônico como resultado do valor de aumento do termo (2).

Para aumentar um termo, use o circunflexo, ^, com um fator de aumento (um número) no final do termo que você está pesquisando. Você também pode aumentar as frases. Quanto maior o fator de aumento, mais relevante é o termo em relação a outros termos de pesquisa. Por padrão, o valor de aumento é 1. Embora o fator de aumento deva ser positivo, ele pode ser menor do que 1 (por exemplo, 0,20).

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 IA do Azure Search, uma expressão regular é colocada entre barras invertidas /.

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 do Lucene completa oferece suporte à correspondência de prefixo, infixo e sufixo. Use a sintaxe de expressão regular para 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 na qual você deseja que a consulta de pesquisa terminal* retorne resultados que contenham termos como terminate, termination e terminates.

Se você fosse usar o analisador en.Lucene (Inglês Lucene), ele aplicaria uma stemizaçã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 lematização (leva em consideração a análise morfológica) em vez de stemização. 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 algumas circunstâncias, talvez você queira 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)

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

O agrupamento de campo é semelhante, mas tem como escopo o agrupamento para um único campo. Por exemplo, hotelAmenities:(gym+(wifi|pool)) pesquisa o campo hotelAmenities para gym e wifi ou gym e pool.

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.

Confira também

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