Sintaxe de consulta simples na IA do Azure Search

Para cenários de pesquisa de texto completo, a Pesquisa de IA do Azure implementa duas linguagens de consulta baseadas em Lucene, cada uma alinhada a um analisador de consulta. O Analisador de Consulta Simples é o padrão. Ele aborda casos de uso comuns e tenta interpretar uma solicitação mesmo que ela não seja perfeitamente composta. O outro é o Analisador de Consultas Lucene e dá suporte a construções de consulta mais avançadas.

Este artigo é a referência de sintaxe de consulta para o analisador de consulta simples.

A sintaxe de consulta para ambos os analisadores aplica-se às expressões de consulta passadas no parâmetro search de uma solicitação de consulta, para não serem confundidos com a sintaxe OData, com sua própria sintaxe e regras para expressões filter e orderby na mesma solicitação.

Embora o analisador simples seja baseado na classe Analisador de consulta simples do Apache Lucene, sua implementação na IA do Azure Search exclui a pesquisa difusa. Se você precisar de pesquisa difusa, considere a alternativa sintaxe de consulta Lucene completa.

Exemplo (sintaxe simples)

Este exemplo mostra uma consulta simples, diferenciada por "queryType": "simple" e por uma sintaxe válida. Embora o tipo de consulta seja definido abaixo, é o padrão e pode ser omitido, a menos que você esteja revertendo de um tipo alternativo. O exemplo a seguir é uma pesquisa de termos independentes, com o requisito de que todos os documentos correspondentes incluam "pool".

POST https://{{service-name}}.search.windows.net/indexes/hotel-rooms-sample/docs/search?api-version=2024-07-01
{
  "queryType": "simple",
  "search": "budget hotel +pool",
  "searchMode": "all"
}

O parâmetro searchMode é relevante neste exemplo. Sempre que os operadores boolianos estiverem na consulta, geralmente você deve definir searchMode=all para garantir que todos os critérios sejam correspondidos. Caso contrário, você pode usar o padrão searchMode=any que favorece a recuperação em vez de precisão.

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

Pesquisa de palavra-chave em termos e frases

As cadeias de caracteres passadas para o search parâmetro podem incluir termos ou frases em qualquer idioma com suporte, operadores boolianos, operadores de precedência, caracteres curinga ou prefixo para consultas "começa com", caracteres de escape e caracteres de codificação de URL. O search é opcional. Não especificado, a pesquisa ( search=* ou search=" " ) retorna os 50 principais documentos em ordem arbitrária (não classificada).

• Uma pesquisa de termo é uma consulta de um ou mais termos, em que qualquer um dos termos é considerado uma correspondência.

• Uma pesquisa de frase é uma frase exata entre aspas " ". Por exemplo, embora Roach Motel (sem aspas) procure documentos que contenham Roach e/ou Motel em qualquer lugar e em qualquer ordem, "Roach Motel" (com aspas) faz a correspondência apenas com documentos que contenham essa frase inteira, junta e naquela ordem (a análise léxica ainda se aplica).

Dependendo do seu cliente de pesquisa, talvez seja necessário não usar aspas em uma pesquisa de frase. Por exemplo, em uma solicitação POST, uma pesquisa de frase em "Roach Motel" no corpo da solicitação poderia especificada como "\"Roach Motel\"". Se você estiver usando os SDKs do Azure, o cliente de pesquisa irá escapar as aspas quando serializar o texto da pesquisa. Sua frase de pesquisa poderá ser enviada como um "pega-mosca".

Por padrão, todas as cadeias de caracteres transmitidas no parâmetro search passam pela análise léxica. Certifique-se de entender o comportamento de geração de tokens do analisador que você está usando. Geralmente, quando os resultados da consulta são inesperados, o motivo pode ser rastreado para como os termos são indexados no momento da consulta. Você pode testar a tokenização em cadeias de caracteres específicas para confirmar a saída.

Qualquer entrada de texto com um ou mais termos é considerada um ponto de partida válido para a execução da consulta. A IA do Azure Search corresponderá a documentos que contenham um ou todos os termos, incluindo qualquer variação encontrada durante a análise do texto.

Por mais simples que pareça, há um aspecto da execução da consulta na IA do Azure Search que talvez produza resultados inesperados, aumentando em vez de diminuir a pesquisa de resultados conforme mais termos e operadores são adicionados à cadeia de caracteres de entrada. Se essa expansão realmente ocorre depende da inclusão de um operador NOT, combinado a uma configuração de parâmetro searchMode que determina como NOT é interpretado em termos dos comportamentos de AND ou OR. Para obter mais informações, consulte o operador NOT em Operadores boolianos.

Operadores booleanos

Você pode inserir operadores boolianos em uma cadeia de caracteres de consulta para melhorar a precisão de uma correspondência. Na sintaxe simples, os operadores boolianos são baseados em caracteres. Não há suporte para operadores de texto, como a palavra AND.

Consultas de prefixo

Para consultas "começa com", adicione um operador de sufixo ( * ) como o espaço reservado para o restante de um termo. Uma consulta de prefixo deve começar com pelo menos um caractere alfanumérico antes que você possa adicionar o operador de sufixo.

Semelhante aos filtros, uma consulta de prefixo procura uma correspondência exata. Assim, não há nenhuma pontuação de relevância (todos os resultados recebem uma pontuação de pesquisa de 1,0). Lembre-se de que as consultas de prefixo podem ser lentas, especialmente se o índice for grande e o prefixo consistir em um pequeno número de caracteres. Uma metodologia alternativa, como a geração de tokens de n-grama de borda, pode ser executada mais rapidamente. Os termos que usam a pesquisa de prefixo não podem ter mais de mil caracteres.

A sintaxe simples dá suporte apenas à correspondência de prefixo. Para a correspondência de sufixo ou infixo no final ou no meio de um termo, use a sintaxe Lucene completa para pesquisa de curinga.

Operadores de escape de pesquisa

Na sintaxe simples, os operadores de pesquisa incluem estes caracteres: + | " ( ) ' \

Se qualquer um desses caracteres fizer parte de um token no índice, faça o escape dele o prefixando com uma barra invertida única (\) na consulta. Por exemplo, suponha que você usou um analisador personalizado para geração de tokens de termo inteiro e o índice contém a cadeia de caracteres "Luxo + Hotel". Para obter uma correspondência exata desse token, insira um caractere de escape: search=luxury\+hotel.

Para simplificar o processo para os casos mais comuns, há duas exceções a essa regra em que o escape não é necessário:

• O operador NOT - só precisa ser ignorado se for o primeiro caractere após um espaço em branco. Se o - aparecer no meio (por exemplo, em 3352CDD0-EF30-4A2E-A512-3B30AF40F3FD), você poderá ignorar a saída.

• O operador de sufixo * só precisa ser ignorado se for o último caractere antes de um espaço em branco. Se o * aparecer no meio (por exemplo, em 4*4=16), não é necessário escapar.

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. Para obter mais informações, consulte RFC1738: Uniform Resource Locators (URL).

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

Caracteres especiais

Os caracteres especiais podem variar de símbolos de moeda como '$' ou '€', a emojis. Muitos analisadores, incluindo o analisador padrão, excluirão caracteres especiais durante a indexação, o que significa que eles não serão representados no índice.

Se você precisar de uma representação de caractere especial, poderá atribuir um analisador que os preserve:

• O analisador de “espaço em branco” considera qualquer sequência de caracteres separada por espaços em branco como tokens (portanto, o emoji “❤” seria considerado um token).

• Um analisador de idioma, como o analisador de inglês da Microsoft (en.microsoft), usaria a cadeia de caracteres “$” ou “€” como um token.

Para confirmação, você pode testar um analisador para ver quais tokens são gerados para uma determinada cadeia de caracteres. Como esperado, talvez você não obtenha a geração de tokens completa de um só analisador. Uma solução alternativa é criar vários campos com o mesmo conteúdo, mas com atribuições de analisador diferentes (por exemplo, description_en, description_fr etc. para analisadores de idioma).

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 Web 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) irá procurar documentos que contenham o termo "motel" e "wifi" ou "luxo" (ou ambos).

Limites de tamanho de consulta

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 GET, o comprimento da URL não pode exceder 8 KB.

• Para POST (e qualquer outra solicitação), em que o corpo da solicitação inclua search e outros parâmetros, como filter e orderby, o tamanho máximo é de 16 MB. Os limites adicionais incluem:

  • O comprimento máximo da cláusula de pesquisa é de 100 mil caracteres.
  • O número máximo de cláusulas em search (expressões separadas por AND ou OR) é de 1.024.
  • O tamanho máximo do termo de pesquisa é de mil caracteres para pesquisa de prefixo.
  • Há também um limite de aproximadamente 32 KB em relação ao tamanho de qualquer termo individual em uma consulta.

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

Próximas etapas

Se você for construir consultas programaticamente, examine a Pesquisa de texto completo na IA do Azure Search para entender os estágios do processamento de consultas e as implicações da análise de texto.

Você também pode examinar os seguintes artigos para saber mais sobre a construção da consulta:

• Exemplos de consulta para pesquisa simples
• Exemplos de consulta para a pesquisa completa Lucene
• API REST para pesquisar documentos
• Sintaxe de consulta Lucene
• Sintaxe de expressão Filter e Select (OData)