Compartilhar via

Sintaxe de consulta do Lucene na IA do Azure Search

  • Artigo

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:
+ - & | ! ( ) { } [ ] ^ " ~ * ? : \ /

Observação

Embora o escape mantenha os tokens juntos, a análise léxica durante a indexação pode distribuí-los. Por exemplo, o analisador do Lucene padrão quebrará palavras em hifens, espaços em branco e outros caracteres. Se você precisar de caracteres especiais na cadeia de caracteres de consulta, talvez seja necessário um analisador que os preserve no índice. Algumas opções incluem analisadores de idioma natural 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.

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.

Operador de texto Character Exemplo Uso
AND + wifi AND luxury Especifica os termos que uma correspondência deve conter. No exemplo, o mecanismo de consulta procura documentos contendo wifi e luxury. O caractere de mais (+) também pode ser usado diretamente na frente de um termo para torná-lo obrigatório. Por exemplo, +wifi +luxury estipula que os dois termos devem aparecer em algum lugar no campo de um único documento.
OR (nenhum) 1 wifi OR luxury Encontra uma correspondência quando um dos termos é encontrado. No exemplo, o mecanismo de consulta retorna a correspondência em documentos contendo wifi, luxury ou ambos. Porque OR é o operador de conjunção padrão, que também pode ser deixado de fora, de modo que wifi luxury é o equivalente de wifi OR luxury.
NOT !, - wifi –luxury Retorna uma correspondência em documentos que excluem o termo. Por exemplo, wifi –luxury pesquisa documentos que têm o termo wifi, mas não luxury.

1 O caractere | não tem suporte para operações OR.

Operador booliano de expressão NOT lógica

Importante

O operador de expressão NOT lógica (NOT, ! ou -) se comporta de maneira diferente na sintaxe completa em relação ao comportamento na sintaxe simples.

  • 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.
Tipo de Consulta Modo de Pesquisa Consulta de exemplo Comportamento
Simples qualquer wifi -luxury Retorna todos os documentos no índice. Documentos com o termo "WIFI" ou documentos que sem o termo "luxo" recebem classificações mais altas do que outros documentos. A consulta é expandida para wifi OR -luxury OR *.
Simples all wifi -luxury Retorna apenas documentos no índice que contêm o termo "WIFI" e não contêm o termo "luxo". A consulta é expandida para wifi AND -luxury AND *.
Completo qualquer wifi -luxury Retorna apenas documentos no índice que contêm o termo "WIFI" e, em seguida, os documentos que contêm o termo "luxo" são removidos dos resultados.
Completo all wifi -luxury Retorna apenas documentos no índice que contêm o termo "WIFI" e, em seguida, os documentos que contêm o termo "luxo" são removidos dos resultados.

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.

Observação

Ao usar expressões de pesquisa em campo, você não precisa usar o parâmetro searchFields porque cada expressão de pesquisa em campo tem um nome de campo especificado explicitamente. No entanto, você ainda poderá usar o parâmetro searchFields se quiser executar uma consulta em que algumas partes têm o escopo de um campo específico, e o restante pode se aplicar a vários campos. Por exemplo, a consulta search=genre:jazz NOT history&searchFields=description corresponderia a jazz apenas no que se refere ao campo genre, enquanto ela corresponderia a NOT history com o campo description. O nome do campo fornecido em fieldName:searchExpression sempre tem precedência sobre o parâmetro searchFields. Por isso, neste exemplo, não precisamos incluir genre no parâmetro searchFields.

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.

No Azure AI Search, uma expressão regular é:

  • Entre barras /
  • Somente letras 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 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.

Tipo de afixação Descrição e exemplos
prefixo O fragmento de termo vem antes * ou ?. Por exemplo, uma expressão de consulta de search=alpha* retorna alphanumeric ou alphabetical. Há suporte para correspondência de prefixo tanto na sintaxe de simples quanto na completa.
sufixo O fragmento do termo vem após * ou ?, com uma barra para delimitar o constructo. Por exemplo, search=/.*numeric/ retorna alphanumeric.
infix Os fragmentos de termo incluem * ou ?. Por exemplo, search=non*al retorna non-numerical e nonsensical.

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.

Observação

Como regra, a correspondência de padrões é lenta, portanto, talvez seja interessante explorar métodos alternativos, como a geração de tokens de n-gram de borda, que cria tokens para sequências de caracteres em um termo. Com a tokenização n-gram, o índice será maior, mas as consultas serão executadas mais rapidamente, dependendo da construção do padrão e do comprimento das cadeias de caracteres que estão sendo indexadas. Para obter mais informações, consulte Pesquisa de termo parcial e padrões com caracteres especiais.

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