Sintaxe de consulta Lucene na Pesquisa de IA do Azure

Ao criar consultas no Azure AI Search, 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 em particular mostra a pesquisa em campo e o aumento de termos. Procura hotéis onde o campo de categoria contém o termo budget. Todos os documentos que contenham a frase "recently renovated" são classificados mais alto como resultado do termo boost value (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 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, o til (~) é usado tanto para pesquisa difusa 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 é uma consulta de termo ou frase, a pesquisa de texto completo com análise lexical retira o ~ termo e divide o termo business~analyst em dois: business OU 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 curinga no https://, onde :// faz parte da cadeia de caracteres de consulta, você deve especificar search=https\:\/\/*. Da mesma forma, um padrão de número de telefone com escape pode ter esta \+1 \(800\) 642\-7676aparência.

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 Azure AI Search. 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 não são permitidas -luxury * .
• 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 sobre um subconjunto de documentos no índice, recomenda-se sintaxe completa ou a sintaxe simples com o modo de pesquisa todos.

Pesquisa em campo

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 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 a cada termo individualmente em um nome ou frase com várias partes. Por exemplo, Unviersty~ of~ Wshington~ corresponderia em University of Washington.

Pesquisa de proximidade

As pesquisas de proximidade são usadas para encontrar termos próximos uns dos outros em um documento. Insira um símbolo til no final de uma frase seguido 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 um do outro em um documento.

Reforço de termos

Aumento de termos refere-se à classificação mais alta de um documento se ele contiver o termo impulsionado, em relação aos documentos que não contêm o termo. Isso difere dos perfis de pontuação, pois os perfis de pontuação impulsionam determinados campos, em vez de termos específicos.

O exemplo a seguir ajuda a ilustrar as diferenças. Suponha que haja um perfil de pontuação que aumente as correspondências em um determinado campo, digamos gênero no exemplo musicstoreindex. O aumento de termos pode ser usado para impulsionar ainda mais certos termos de pesquisa do que outros. Por exemplo, rock^2 electronic impulsiona documentos que contêm os termos de pesquisa no campo de gênero mais alto do que outros campos pesquisáveis no índice. Além disso, os documentos que contêm o termo de pesquisa rock são classificados mais alto do que o outro termo de pesquisa eletrônico como resultado do valor de impulso do termo (2).

Para impulsionar um termo, use o acento circunflexo, ^símbolo com um fator de impulso (um número) no final do termo que você está pesquisando. Você também pode impulsionar frases. Quanto maior o fator de impulso, mais relevante o termo é em relação a outros termos de pesquisa. O fator de potência predefinido é 1. Embora o fator de impulso deva ser positivo, pode ser inferior a 1 (por exemplo, 0,20).

Pesquisa de expressões regulares

Uma pesquisa de expressão regular encontra 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 é colocada entre barras /.

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 requisitos de caracteres de escape adicionais além das regras de escape impostas pelo Azure AI Search. Para JSON, as cadeias de caracteres que incluem uma barra 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 uma barra para frente com escape.

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 que você corresponda a qualquer série de caracteres para corresponder a /be.*/ qualquer termo que comece com be .better

Se você receber erros de sintaxe em sua expressão regular, revise 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 carateres universais

Você pode usar a sintaxe geralmente reconhecida para pesquisas curinga de vários caracteres (*) ou únicos (?). A sintaxe Lucene completa suporta correspondência de prefixo e infix. 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* correspondências em 98072-1222 e 98052-1234, onde ? corresponde a um único caractere (obrigatório) e * corresponde a caracteres de comprimento arbitrário que se seguem.

A correspondência de sufixos requer os delimitadores de barra / para a frente da 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 barras / para frente regex, o é um caractere curinga e corresponde a qualquer série de caracteres muito parecido .* com o * 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, curinga ou expressões regulares são passadas 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 Azure AI Search.

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 você usasse o analisador en.lucene (inglês Lucene), ele aplicaria derivaçã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 em consultas que usam curingas ou pesquisa difusa não são analisados, portanto, não haveria resultados que correspondessem à terminat* consulta.

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

Pontuação de consultas curinga e regex

O Azure AI Search 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 curinga e regex.

Carateres 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 escapados corretamente na url de consulta (por exemplo, para ❤ usar a sequência %E2%9D%A4+de escape ). 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 motel termo e um wifi ou ( luxury ou ambos).

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

Limites de tamanho da consulta

O Azure AI Search 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 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
• Pesquisar Documentos
• Sintaxe da expressão OData para filtros e classificação
• Sintaxe de consulta simples no Azure AI Search