Sintaxe de consulta simples na Pesquisa Cognitiva Azure

A Azure Cognitive Search implementa duas línguas de consulta baseadas em Lucene: Simple Query Parser e o Lucene Query Parser. O simples parser é mais flexível e tentará interpretar um pedido mesmo que não seja perfeitamente composto. Porque é flexível, é o padrão para consultas na Pesquisa Cognitiva Azure.

A sintaxe simples é utilizada para expressões de consulta passadas no parâmetro de "pesquisa" de um pedido de Documentos de Busca (REST API), não devendo ser confundida com a sintaxe OData utilizada para as expressões "$filter" e "$orderby" no mesmo pedido. Os parâmetros OData têm diferentes sintaxes e regras para a construção de consultas, cordas de fuga, e assim por diante.

Embora o simples parser seja baseado na classe Apache Lucene Simple Query Parser , a sua implementação na Cognitive Search exclui a pesquisa difusa. Se precisar de uma pesquisa confusa, considere a sintaxe de consulta completa de Lucene alternativa.

Exemplo (sintaxe simples)

Este exemplo mostra uma simples consulta, distinguida por "queryType": "simple" sintaxe válida e válida. Embora o tipo de consulta esteja 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 sobre termos independentes, com a exigência de que todos os documentos correspondentes incluam "pool".

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

O parâmetro "searchMode" é relevante neste exemplo. Sempre que os operadores booleanos estiverem em consulta, deve geralmente definir "searchMode=all" para garantir que todos os critérios são compatíveis. Caso contrário, pode utilizar o padrão "searchMode=any" que favorece a recuperação em vez de precisão.

Para exemplos adicionais, consulte exemplos de sintaxe de consulta simples. Para mais informações sobre o pedido de consulta e parâmetros, consulte Documentos de Pesquisa (REST API).

Pesquisa de palavras-chave em termos e frases

As cordas passadas para o parâmetro de "pesquisa" podem incluir termos ou frases em qualquer idioma suportado, operadores booleanos, operadores de precedência, caracteres wildcard ou prefixo para consultas "começa com" personagens de fuga e caracteres codificadores de URL. O parâmetro de "pesquisa" é opcional. Não especificado, pesquisar (search=* ou search=" ") devolve os 50 melhores documentos em ordem arbitrária (não classificada).

  • Uma pesquisa de termo é uma consulta de um ou mais termos, onde qualquer um dos termos são considerados compatíveis.

  • Uma pesquisa de frases é uma frase exata incluída em aspas " ". Por exemplo, enquanto Roach Motel (sem cotações) procuraria documentos que contenham Roach e/ou Motel em qualquer lugar em qualquer ordem, "Roach Motel" (com aspas) apenas corresponderá a documentos que contenham toda essa frase em conjunto e nessa ordem (a análise lexical ainda se aplica).

    Dependendo do seu cliente de pesquisa, poderá ter de escapar às aspas numa pesquisa de frases. Por exemplo, num pedido do Postman, uma pesquisa de frases no "Roach Motel" corpo de pedido seria especificada como "\"Roach Motel\"".

Por padrão, todas as cordas passadas no parâmetro de "pesquisa" são submetidas a análise lexical. Certifique-se de compreender o comportamento de tokenização do analisador que está a usar. Muitas vezes, quando os resultados da consulta são inesperados, a razão pode ser rastreada para como os termos são tokenizados no tempo de consulta. Pode testar a tokenização em cordas 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 de consultas. A Azure Cognitive Search corresponderá a 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, existe um aspeto de execução de consultas na Pesquisa Cognitiva Azure que pode 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 ocorre depende da inclusão de um operador NÃO, combinado com uma definição de parâmetro "searchMode" que determina como NÃO é interpretado em termos de e ou ou comportamentos. Para obter mais informações, consulte o operador NÃO sob os operadores Boolean.

Operadores booleanos

Pode incorporar os operadores Boolean numa cadeia de consulta para melhorar a precisão de uma correspondência. Na simples sintaxe, os operadores booleanos são baseados em caracteres. Os operadores de texto, como a palavra E, não são apoiados.

Caráter Exemplo Utilização
+ pool + ocean Uma operação e uma operação. Por exemplo, pool + ocean estipula que um documento deve conter ambos os termos.
| pool | ocean Uma operação DES encontra uma correspondência quando qualquer um dos termos é encontrado. No exemplo, o motor de consulta voltará a corresponder em documentos que contenham pool ou ocean ambos. Como o OR é o operador de conjunção padrão, também pode deixá-lo de fora, tal que pool ocean é o equivalente pool | oceana .
- pool – ocean Uma operação NÃO devolve correspondências em documentos que excluem o termo.

Para obter o comportamento esperado numa expressão NÃO, desconte "searchMode=all" no pedido. Caso contrário, sob o padrão de "searchMode=any", você receberá fósforos em pool, mais fósforos em todos os documentos que não contêm ocean- o que pode ser um monte de documentos. O parâmetro "searchMode" sobre um pedido de consulta controla se um termo com o operador NÃO é ANDed ou ORed com outros termos na consulta (assumindo que não existe nenhum + ou | operador nos outros termos). A utilização "searchMode=all" aumenta a precisão das consultas, incluindo menos resultados, e por defeito - será interpretada como "E NÃO".

Ao decidir sobre uma definição de "searchMode", considere os padrões de interação do utilizador para consultas em várias aplicações. Os utilizadores que procuram informações são mais propensos a incluir um operador numa consulta, em oposição aos sites de e-commerce que têm mais estruturas de navegação incorporadas.

Consultas de prefixo

Para consultas "começa com", adicione um operador de sufixo (*) como espaço reservado para o resto de um período. Uma consulta de prefixo deve começar com pelo menos um carácter alfanumérico antes de poder adicionar o operador de sufixo.

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

Semelhante aos filtros, uma consulta de prefixo procura uma correspondência exata. Como tal, não há pontuação de relevância (todos os resultados recebem uma pontuação de pesquisa de 1.0). Esteja ciente de que as consultas de prefixo podem ser lentas, especialmente se o índice é grande e o prefixo consiste em um pequeno número de caracteres. Uma metodologia alternativa, como a tokenização edge n-gram, pode funcionar mais rapidamente. Os termos que utilizam a pesquisa de prefixo não podem ser superiores a 1000 caracteres.

A sintaxe simples suporta apenas a correspondência do prefixo. Para sufixo ou infixo correspondente ao final ou a meio de um termo, utilize a sintaxe Lucene completa para pesquisa de wildcard.

Operadores de busca em fuga

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

Se algum destes caracteres fizer parte de um símbolo no índice, escape-o prefixando-o com uma única contrala detrás (\) na consulta. Por exemplo, suponha que usou um analisador personalizado para toda a tokenização do termo, e o seu índice contém a cadeia "Luxury+Hotel". Para obter uma correspondência exata neste token, insira um personagem de fuga: search=luxury\+hotel.

Para tornar as coisas simples para os casos mais típicos, existem duas exceções a esta regra onde não é necessário escapar:

  • O operador - do NOT só precisa de ser escapado se for o primeiro personagem depois de um espaço em branco. Se o aparecer - no meio (por exemplo, em 3352CDD0-EF30-4A2E-A512-3B30AF40F3FD), pode saltar para escapar.

  • O operador * de sufixo só precisa de ser escapado se for o último personagem 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 padrão, o analisador padrão irá apagar e quebrar palavras sobre hífens, espaços brancos, ampersands e outros caracteres durante a análise lexical. Se necessitar de caracteres especiais para permanecer na cadeia de consulta, pode precisar de um analisador que os preserve no índice. Algumas escolhas incluem analisadores de linguagem natural da Microsoft, que preserva palavras hifenizadas, ou um analisador personalizado para padrões mais complexos. Para mais informações, consulte termos, padrões e caracteres especiais.

Codificação de caracteres inseguros e reservados em URLs

Certifique-se de que todos os caracteres inseguros e reservados estão codificados num URL. Por exemplo, '#' é um personagem inseguro porque é um identificador de fragmento/âncora num URL. O carácter deve ser codificado se %23 for utilizado num URL. '&' e '=' são exemplos de caracteres reservados à medida que delimitam parâmetros e especificam valores na Pesquisa Cognitiva Azure. Para mais informações, consulte RFC1738: Localizadores de Recursos Uniformes (URL).

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

Carateres especiais

Em algumas circunstâncias, você pode querer procurar um personagem especial, como um emoji '❤' ou o sinal '€'. Nesses casos, certifique-se de que o analisador que utiliza não filtra esses caracteres. O analisador padrão contorna muitos caracteres especiais, excluindo-os do seu índice.

Os analisadores que irão tokenizar caracteres especiais incluem o analisador "whitespace", que leva em consideração quaisquer sequências de caracteres separadas por espaços brancos como tokens (assim a cadeia "❤" seria considerada um símbolo). Além disso, um analisador de idiomas como o analisador de inglês da Microsoft ("en.microsoft"), levaria a cadeia "€" como um símbolo. Pode testar um analisador para ver que fichas gera para uma determinada consulta.

Ao utilizar caracteres Unicode, certifique-se de que os símbolos são corretamente escapados no url de consulta (por exemplo, para "❤" utilizaria a sequência %E2%9D%A4+de fuga). O carteiro faz esta tradução automaticamente.

Precedência (agrupamento)

Você pode usar parênteses para criar subqueries, incluindo operadores dentro da declaração parêntesis. Por exemplo, motel+(wifi|luxury) procurará documentos que contenham o termo "motel" e "wifi" ou "luxo" (ou ambos).

Limites de tamanho de consulta

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

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

  • Para POST (e qualquer outro pedido), onde o corpo do pedido inclui search e outros parâmetros tais 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.000 caracteres.
    • O número máximo de cláusulas em search (expressões separadas por E ou OR) é de 1024.
    • O tamanho máximo do prazo de pesquisa é de 1000 caracteres para pesquisa de prefixos.
    • Existe também um limite de aproximadamente 32 KB sobre o tamanho de qualquer termo individual numa consulta.

Para obter mais informações sobre os limites de consulta, consulte os limites de pedido da API.

Passos seguintes

Se você estiver construindo consultas programáticas, reveja a pesquisa completa de texto na Pesquisa Cognitiva Azure para entender as fases do processamento de consultas e as implicações da análise de texto.

Também pode rever os seguintes artigos para saber mais sobre a construção de consultas: