Sintaxe simples de consulta no Pesquisa de IA do Azure

Para cenários de pesquisa por texto completo, o Pesquisa de IA do Azure implementa duas linguagens de consulta baseadas em Lucene, cada uma alinhada a um analisador de consultas. O Simple Query Parser é o padrão. Cobre casos de uso comuns e tenta interpretar um pedido mesmo que não esteja perfeitamente composto. O outro parser é o Lucene Query Parser e suporta construções de consultas mais avançadas.

Este artigo é a referência da sintaxe de consulta para o parser de consultas simples.

A sintaxe de consulta para ambos os analisadores aplica-se a expressões de consulta passadas no search parâmetro de um pedido de consulta, não deve ser confundida com a sintaxe OData, que tem a sua própria sintaxe e regras para filter e orderby expressões no mesmo pedido.

Embora o parser simples se baseie na classe Apache Lucene Simple Query Parser, a sua implementação em Pesquisa de IA do Azure exclui a pesquisa fuzzy. Se precisares de pesquisa fuzzy, considera em vez disso a sintaxe completa de consulta Lucene.

Exemplo (sintaxe simples)

Este exemplo mostra uma consulta simples, distinguida por "queryType": "simple" uma sintaxe válida. Embora o tipo de consulta esteja definido abaixo, é o padrão e pode ser omitido, a menos que esteja a reverter de um tipo alternativo. O exemplo seguinte é uma pesquisa sobre 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=2025-09-01
{
  "queryType": "simple",
  "search": "budget hotel +pool",
  "searchMode": "all"
}

O searchMode parâmetro é relevante neste exemplo. Sempre que há operadores booleanos na consulta, deve geralmente definir searchMode=all para garantir que todos os critérios são cumpridos. Caso contrário, pode usar o padrão searchMode=any que favorece a recordação em vez da precisão.

Para mais exemplos, veja Exemplos simples de sintaxe de consultas. Para detalhes sobre o pedido de consulta e os parâmetros, consulte Documentos de Pesquisa (API REST).

Pesquisa por palavras-chave em termos e expressões

As strings passadas ao search parâmetro podem incluir termos ou frases em qualquer língua suportada, operadores booleanos, operadores de precedência, caracteres coringa ou prefixos para consultas "começa com", caracteres escape e caracteres de codificação URL. O search parâmetro é opcional. Não especificado, a pesquisa (search=* ou search=" ") devolve os 50 primeiros documentos por ordem arbitrária (não classificada).

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

  • Uma pesquisa por frases é uma expressão exata incluída entre aspas " ". Por exemplo, enquanto Roach Motel (sem aspas) procuraria documentos contendo Roach e/ou Motel em qualquer lugar em qualquer ordem, "Roach Motel" (com aspas) só compararia documentos que contenham toda essa frase juntos e nessa ordem (a análise lexical ainda se aplica).

Dependendo do seu cliente de pesquisa, pode ser necessário evitar as aspas numa pesquisa por frase. Por exemplo, num pedido POST, uma pesquisa de frases no "Roach Motel" corpo do pedido pode ser especificada como "\"Roach Motel\"". Se estiveres a usar os SDKs do Azure, o cliente de pesquisa escapa das aspas quando serializa o texto da pesquisa. A sua frase de pesquisa pode ser enviada como "Roach Motel".

Por padrão, todas as cadeias passadas no parâmetro search passam por análise lexical. Certifica-te de que compreendes o comportamento de tokenização do analisador que estás a usar. Muitas vezes, quando os resultados das consultas são inesperados, a razão pode ser atribuída à forma como os termos são tokenizados no momento da consulta. Podes testar tokenização em strings 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. O Pesquisa de IA do Azure irá corresponder documentos que contenham qualquer ou todos os termos, incluindo quaisquer variações encontradas durante a análise do texto.

Por mais simples que isto pareça, há um aspeto da execução de consultas em Pesquisa de IA do Azure que poderá produzir resultados inesperados, aumentando em vez de diminuir os resultados de pesquisa à medida que mais termos e operadores são adicionados à cadeia de entrada. Se esta expansão realmente ocorrer depende da inclusão de um operador NOT, combinado com uma searchMode definição do parâmetro que determina como o NOT é interpretado em termos dos comportamentos AND ou OR. Para mais informações, veja o operador NOT em operadores booleanos.

Operadores booleanos

Pode incorporar operadores booleanos numa string de consulta para melhorar a precisão de um resultado. Na sintaxe simples, operadores booleanos são baseados em caracteres. Operadores de texto, como a palavra AND, não são suportados.

Carácter Exemplo Utilização
+ pool + ocean Uma AND operação. Por exemplo, pool + ocean estipula que um documento deve conter ambos os termos.
| pool | ocean Uma OR operação encontra uma correspondência quando qualquer um dos termos é encontrado. No exemplo, o motor de consulta devolverá uma correspondência em documentos que contenham pool ou ocean ou ambos. Como OR é o operador de conjunção padrão, também pode ser omitido, assim pool ocean é o equivalente a pool | ocean.
- pool – ocean Uma NOT operação retorna resultados em documentos que excluem o termo.

O searchMode parâmetro num pedido de consulta controla se um termo com o NOT operador é ANDed ou ORed com outros termos na consulta (assumindo que não existem operadores booleanos nos outros termos). Valores válidos incluem any ou all.

searchMode=any aumenta a recordação de consultas ao incluir mais resultados e, por defeito - , será interpretado como "OU NÃO". Por exemplo, pool - ocean irá corresponder documentos que contenham o termo pool ou aqueles que não contêm o termo ocean.

searchMode=all aumenta a precisão das consultas porque inclui menos resultados e, por defeito, - será interpretado como "E NÃO". Por exemplo, com searchMode=any, a consulta pool - ocean irá corresponder a documentos que contenham o termo "piscina" e os documentos que não contenham o termo "oceano". Este é, provavelmente, um comportamento mais intuitivo para o - operador. Por isso, deve considerar usar searchMode=all em vez de searchMode=any se quiser otimizar as pesquisas para precisão em vez de recordação, e os seus utilizadores usam frequentemente o - operador nas pesquisas.

Ao decidir uma searchMode definição, considere os padrões de interação do utilizador para consultas em várias aplicações. Os utilizadores que procuram informação têm maior probabilidade de incluir um operador numa consulta, ao contrário dos sites de comércio eletrónico que têm mais estruturas de navegação integradas.

Consultas de prefixo

Para consultas "começa com", adicione um operador sufixo (*) como marcador de posição para o restante do termo. Numa consulta de prefixo, deve começar com pelo menos um carácter de texto simples antes de poder adicionar o operador de sufixo.

Carácter Exemplo Utilização
* lingui* corresponderá a "linguistic" ou "linguini" O asterisco (*) representa um ou mais caracteres de comprimento arbitrário, ignorando o caso.

Semelhante aos filtros, uma consulta prefixa procura uma correspondência exata. Assim, não existe pontuação de relevância (todos os resultados recebem uma pontuação de pesquisa de 1,0). Tenha em atenção que as consultas de prefixo podem ser lentas, especialmente se o índice for grande e o prefixo for composto por um número reduzido de caracteres. Uma metodologia alternativa, como a tokenização edge n-gram, poderá ter um desempenho mais rápido. Os termos que usam pesquisa por prefixo não podem ter mais de 1000 caracteres.

A sintaxe simples suporta apenas correspondência de prefixos. Para correspondência de sufixos ou infixos no final ou no meio de um termo, use a sintaxe completa do Lucene para pesquisa por curinga.

Escape de operadores de pesquisa

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

Se algum destes caracteres fizer parte de um token no índice, escape dele prefixando-o com uma única barra inversa (\) na consulta. Por exemplo, suponha que usou um analisador personalizado para tokenização de termos inteiros, e o seu índice contém a cadeia "Luxury+Hotel". Para obter uma correspondência exata neste token, insira um caractere de escape: search=luxury\+hotel.

Para simplificar os casos mais típicos, existem duas exceções a esta regra onde não é necessário fugir:

  • O operador NOT - só precisa ser escapado 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), podes saltar a fuga.

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

Nota

Por defeito, o analisador padrão apaga e quebra palavras em hífens, espaços em branco, ampersands e outros caracteres durante a análise lexical. Se precisar que caracteres especiais permaneçam na cadeia de consulta, poderá precisar de um analisador que os preserve no índice. Algumas opções incluem analisadores de linguagem natural da Microsoft, que preservam palavras com hífens, ou um analisador personalizado para padrões mais complexos. Para mais informações, veja Termos parciais, padrões e caracteres especiais.

Codificação de caracteres inseguros e reservados em URLs

Garanta que todos os caracteres inseguros e reservados estão codificados numa URL. Por exemplo, '#' é um carácter inseguro porque é um identificador de fragmento/âncora numa URL. O carácter deve ser codificado %23 se usado numa URL. '& ' e '=' são exemplos de caracteres reservados, pois delimitam parâmetros e especificam valores no Pesquisa de IA do Azure. Para mais informações, veja RFC1738: Localizadores Uniformes de Recursos (URL).

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

Personagens especiais

Caracteres especiais podem variar desde símbolos de moeda como '$' ou '€', até emojis. Muitos analisadores, incluindo o analisador padrão padrão, excluem caracteres especiais durante a indexação, o que significa que não serão representados no seu índice.

Se precisar representar caracteres especiais, pode configurar um analisador que os preserve:

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

  • Um analisador de linguagem, como o analisador Microsoft English (en.microsoft), consideraria a sequência '$' ou '€' como token.

Para confirmação, pode testar um analisador para ver que tokens são gerados para uma determinada cadeia. Como é de esperar, pode não obter tokenização completa de um único analisador. Uma solução alternativa é criar múltiplos campos que contenham o mesmo conteúdo, mas com atribuições de analisadores diferentes (por exemplo, description_en, description_fr, , e assim por diante para analisadores de linguagem).

Ao usar caracteres Unicode, certifique-se de que os símbolos estão devidamente escapados na URL da consulta (por exemplo, para '❤' usaria a sequência de escape %E2%9D%A4+). Alguns clientes web fazem esta tradução automaticamente.

Precedência (agrupamento)

Pode usar parênteses para criar subconsultas, incluindo operadores dentro da instrução entre parênteses. Por exemplo, motel+(wifi|luxury) vai procurar documentos que contenham o termo "motel" e "wifi" ou "luxúria" (ou ambos).

Limites de tamanho da consulta

Se a sua aplicação gerar consultas de pesquisa programaticamente, recomendamos que a desenhe de forma a não gerar consultas de tamanho ilimitado.

  • Para o GET, o comprimento da URL não pode exceder 8 KB.

  • Para POST (e qualquer outro pedido), onde o corpo do pedido inclui search e outros parâmetros como filter e orderby, o tamanho máximo é de 16 MB. Limites adicionais incluem:

    • O comprimento máximo da cláusula de pesquisa é de 100.000 caracteres.
    • O número máximo de orações em search (expressões separadas por AND ou OR) é 1024.
    • O tamanho máximo do termo de pesquisa é de 1000 caracteres para pesquisa com prefixo.
    • Existe também um limite de aproximadamente 32 KB para o tamanho de qualquer termo individual numa consulta.

Para mais informações sobre limites de consultas, consulte limites de pedidos de API.

Próximos passos

Se estiver a construir consultas programaticamente, revista a Pesquisa de Texto Completo no Pesquisa de IA do Azure para compreender as fases do processamento de consultas e as implicações da análise de texto.

Pode também consultar os seguintes artigos para saber mais sobre a construção de consultas.

  • Last updated on