Sintaxe de consulta lucene em Pesquisa Cognitiva Azure

Ao criar consultas, pode optar pela sintaxe Lucene Query Parser para formas de consulta especializadas: wildcard, pesquisa fuzzy, pesquisa de proximidade, expressões regulares. Grande parte da sintaxe Lucene Query Parser é implementada intacta na Pesquisa Cognitiva do Azure, com exceção das pesquisas de alcance que são construídas através de $filter expressões.

Para utilizar a sintaxe Lucene completa, irá definir a consultaType para "full" e passar numa expressão de consulta padronizada para wildcard, pesquisa difusa ou uma das outras formas de consulta suportadas pela sintaxe completa. Em REST, as expressões de consulta são fornecidas no search parâmetro de um pedido de Documentos de Busca (REST API).

Exemplo (sintaxe completa)

O exemplo a seguir é um pedido de pesquisa construído utilizando a sintaxe completa. Este exemplo em particular mostra a procura no terreno e o aumento do prazo. Procura hotéis onde o campo de categoria contém o termo "orçamento". Quaisquer documentos que contenham a frase "recentemente renovado" são classificados mais elevados como resultado do valor de aumento do termo (3).

POST /indexes/hotels-sample-index/docs/search?api-version=2020-06-30
{
  "queryType": "full",
  "search": "category:budget AND \"recently renovated\"^3",
  "searchMode": "all"
}

Embora não seja específico de qualquer tipo de consulta, o searchMode parâmetro é relevante neste exemplo. Sempre que os operadores estiverem em consulta, deve geralmente definir searchMode=all para garantir que todos os critérios são compatíveis.

Para outros exemplos, consulte os exemplos de sintaxe de consulta de Lucene. Para mais detalhes sobre o pedido de consulta e parâmetros, incluindo searchMode, consulte Documentos de Pesquisa (REST API).

Fundamentos da sintaxe

Os seguintes fundamentos da sintaxe aplicam-se a todas as consultas que utilizam a sintaxe lucene.

Avaliação do operador em contexto

A colocação determina se um símbolo é interpretado como um operador ou apenas como outro personagem numa corda.

Por exemplo, na sintaxe completa de Lucene, o azulejo (~) é usado tanto para pesquisa de fuzzy como para pesquisa de proximidade. Quando colocado após uma frase citada, ~ invoca a procura de proximidade. Quando colocado no final de um termo, ~ invoca a procura confusa.

Dentro de um prazo, como "business~analyst", o personagem não é avaliado como operador. Neste caso, assumindo que a consulta é um termo ou consulta de frase, a pesquisa completa de texto com análise lexical tira o ~ e quebra o termo "business~analyst" em dois: analista de negócios OR.

O exemplo acima é o azulejo (~), mas o mesmo princípio aplica-se a todos os operadores.

Escapando de personagens especiais

Para utilizar qualquer um dos operadores de pesquisa como parte do texto de pesquisa, escape o personagem prefixando-o com uma única faixa traseira (\). Por exemplo, para uma pesquisa de wildcard em https://, onde :// faz parte da cadeia de consulta, você especificaria search=https\:\/\/*. Da mesma forma, um padrão de número de telefone escapado pode ser assim \+1 \(800\) 642\-7676.

Os caracteres especiais que requerem fuga incluem o seguinte:
+ - & | ! ( ) { } [ ] ^ " ~ * ? : \ /

Nota

Embora escapar mantenha os tokens juntos, a análise lexical durante a indexação pode despojá-los. Por exemplo, o analisador padrão lucene quebrará palavras sobre hífens, espaço branco e outros personagens. Se necessitar de caracteres especiais na cadeia de consulta, poderá 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. Consulte RFC1738: Localizadores de recursos uniformes (URL) para mais detalhes.

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

Operadores booleanos

Pode incorporar os operadores Boolean numa cadeia de consulta para melhorar a precisão de uma correspondência. A sintaxe completa suporta os operadores de texto, para além dos operadores de caracteres. Especifique sempre os operadores de boolean de texto (E, OU NÃO) em todas as tampas.

Operador de texto Caráter Exemplo Utilização
AND + wifi AND luxury Especifica os termos que uma correspondência deve conter. No exemplo, o motor de consulta procurará documentos que contenham ambos wifi e luxury. O caráter mais (+) também pode ser usado diretamente na frente de um termo para torná-lo necessário. Por exemplo, +wifi +luxury estipula que ambos os termos devem aparecer em algum lugar no campo de um único documento.
OU (nenhum) 1 wifi OR luxury Encontra uma correspondência quando qualquer um dos termos é encontrado. No exemplo, o motor de consulta voltará a corresponder em documentos que contenham wifi ou luxury ambos. Como o OR é o operador de conjunção padrão, também pode deixá-lo de fora, tal que wifi luxury é o equivalente wifi OR luxurya .
NOT !, - wifi –luxury Devolução de correspondências em documentos que excluam o termo. Por exemplo, wifi –luxury procurará documentos que tenham o wifi termo, mas não luxury.

O searchMode parâmetro de 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 há operadores booleanos nos outros termos). Valores válidos incluem any ou all.

searchMode=any aumenta a recolha de consultas através da inclusão de mais resultados, e por padrão - será interpretado como "OU NÃO". Por exemplo, wifi -luxury corresponderá a documentos que contenham o termo wifi ou aqueles que não contenham o termo luxury.

searchMode=all aumenta a precisão das consultas, incluindo menos resultados, e por defeito - será interpretado como "E NÃO". Por exemplo, wifi -luxury irá combinar documentos que contenham o termo wifi e não contenham o termo "luxo". Este é, sem dúvida, um comportamento mais intuitivo para o - operador. Por isso, deve considerar a utilização searchMode=all em vez de searchMode=any se pretender otimizar as pesquisas de precisão em vez de se lembrar, e os seus utilizadores usam frequentemente o - operador em pesquisas.

Ao decidir sobre 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çõ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.

1 O | carácter não é suportado para operações de OR.

Pesquisa de campo

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 uma frase, ou uma expressão mais complexa em parênteses, opcionalmente com operadores Boolean. Alguns exemplos incluem:

  • género:jazz NÃO história

  • artistas:("Miles Davis" "John Coltrane")

Certifique-se de colocar várias cordas dentro das aspas se quiser que ambas as cordas sejam avaliadas como uma única entidade, neste caso procurando dois artistas distintos no artists campo.

O campo especificado deve fieldName:searchExpression ser um searchable campo. Consulte o Índice de Criação para obter detalhes sobre como os atributos do índice são utilizados nas definições de campo.

Nota

Ao utilizar expressões de pesquisa em campo, não precisa de utilizar o searchFields parâmetro porque cada expressão de pesquisa em campo tem um nome de campo explicitamente especificado. No entanto, ainda pode utilizar o searchFields parâmetro se quiser executar uma consulta onde algumas partes são telescópios para um campo específico, e o resto pode aplicar-se a vários campos. Por exemplo, a consulta search=genre:jazz NOT history&searchFields=description corresponderia jazz apenas ao genre campo, enquanto combinava NOT history com o description campo. O nome de campo fornecido tem fieldName:searchExpression sempre precedência sobre o searchFields parâmetro, razão pela qual, neste exemplo, não precisamos de incluir genre no searchFields parâmetro.

Pesquisa difusa

Uma pesquisa difusa encontra fósforos em termos que têm uma construção semelhante, expandindo um termo até ao máximo de 50 termos que cumprem os critérios de distância de dois ou menos. Para mais informações, consulte a pesquisa fuzzy.

Para fazer uma pesquisa difusa, utilize o símbolo de azulejo "~" no final de uma única palavra com um parâmetro opcional, um número entre 0 e 2 (predefinido), que especifica a distância de edição. Por exemplo, "blue~" ou "blue~1" devolveria "azul", "blues" e "cola".

A pesquisa fuzzy só pode ser aplicada em termos, não em frases, mas pode anexar o azulejo a cada termo individualmente num nome ou frase em várias partes. Por exemplo, "Unviersty~ de~ "Wshington~" combinaria com "Universidade de Washington".

Pesquisa de proximidade

As pesquisas de proximidade são usadas para encontrar termos que estão próximos uns dos outros em um documento. Insira um símbolo de azulejos "~" no final de uma frase seguida do número de palavras que criam o limite de proximidade. Por exemplo, "hotel airport"~5 encontrará os termos "hotel" e "aeroporto" dentro de 5 palavras um do outro num documento.

Reforço de prazos

O aumento de prazo refere-se à classificação de um documento mais elevado se contiver o termo aumentado, em relação a documentos que não contêm o termo. Isto difere de perfis de pontuação em que os perfis de pontuação impulsionam certos campos, em vez de termos específicos.

O exemplo a seguir ajuda a ilustrar as diferenças. Suponha que há um perfil de pontuação que impulsiona os fósforos num determinado campo, digamos género no exemplo da musicstoreindex. O aumento do termo poderia ser usado para aumentar ainda mais certos termos de pesquisa superiores aos outros. Por exemplo, rock^2 electronic irá impulsionar documentos que contenham os termos de pesquisa no campo de género mais elevados do que outros campos pes pesjáveis no índice. Além disso, os documentos que contenham o termo de pesquisa rock serão classificados mais alto do que o outro termo de pesquisa eletrónico como resultado do valor de aumento do termo (2).

Para impulsionar um termo, use o caret, símbolo "^", com um fator de aumento (um número) no final do termo que está a procurar. Também pode aumentar as frases. Quanto maior for o fator de impulso, mais relevante será o termo relativo a outros termos de pesquisa. Por padrão, o fator de impulso é 1. Embora o fator de impulso tenha de ser positivo, pode ser inferior a 1 (por exemplo, 0,20).

Pesquisa regular de expressão

Uma pesquisa regular de expressão encontra uma correspondência baseada em padrões que são válidos sob Apache Lucene, como documentado na classe RegExp. Na Pesquisa Cognitiva Azure, uma expressão regular é fechada entre cortes para /a frente .

Por exemplo, para encontrar documentos que contenham "motel" ou "hotel", especifique /[mh]otel/. As pesquisas regulares de expressão são compatívels com palavras únicas.

Algumas ferramentas e idiomas impõem requisitos adicionais de carácter de fuga. Para JSON, as cordas que incluem um corte para a frente escapam com um corte para trás: "microsoft.com/azure/" torna-se search=/.*microsoft.com\/azure\/.*/ onde search=/.* <string-placeholder>.*/ define a expressão regular, e microsoft.com\/azure\/ é a corda com um corte para a frente escapado.

Dois símbolos comuns em consultas de regex são . e *. Um . corresponde a qualquer personagem e um * corresponde ao personagem anterior zero ou mais vezes. Por exemplo, /be./ irá combinar os termos "abelha" e "aposta" enquanto /be*/ combinaria "ser", "abelha" e "beee" mas não "aposta". Juntos, .* permita-lhe combinar qualquer série de caracteres /be.*/ para que corresponda a qualquer termo que comece com "ser" como "melhor".

Pesquisa wildcard

Pode utilizar sintaxe geralmente reconhecida para pesquisas de wildcard de caracteres múltiplos (*) ou individuais (?) de caracteres. A sintaxe Lucene completa suporta prefixo, infixo e sufixo correspondente.

Note que o parser de consulta Lucene suporta o uso destes símbolos com um único termo, e não uma frase.

Tipo de afixo Descrição e exemplos
prefixo O fragmento do termo vem antes * ou ?. Por exemplo, uma expressão de consulta de search=alpha* devoluções "alfanumérica" ou "alfabética". A correspondência prefixo é suportada em sintaxe simples e completa.
sufixo O fragmento do termo vem depois * ou ?, com um corte para a frente para delimitar a construção. Por exemplo, search=/.*numeric/ devolve "alfanumérico".
infixo Fragmentos de prazos fechados * ou ?. Por exemplo, search=non*al devolve "nãonumérico" e "sem sentido".

Pode combinar operadores numa só expressão. Por exemplo, 980?2* combina com "98072-1222" e "98052-1234", onde ? corresponde a um único (obrigatório) carácter, e * corresponde a caracteres de comprimento arbitrário que se seguem.

A correspondência de sufixos requer a expressão regular para a frente delimiters / . Geralmente, não se pode usar um * ou ? símbolo como o primeiro personagem de um termo, sem o /. Também é importante notar que o * vai comportar-se de forma diferente quando usado fora das consultas de regex. Fora ou os delimitadores de corte / dianteiros regex, o * é um personagem wildcard e irá combinar qualquer série de personagens como .* no Regex. Como exemplo, search=/non.*al/ produzirá o mesmo resultado definido como search=non*al.

Nota

Regra geral, a correspondência de padrões é lenta, por isso pode querer explorar métodos alternativos, como a tokenização edge n-gram que cria fichas para sequências de caracteres num termo. Com a tokenização n-gram, o índice será maior, mas as consultas podem executar mais rapidamente, dependendo da construção de padrões e do comprimento das cordas que está a indexar. Para obter mais informações, consulte a pesquisa parcial e padrões com caracteres especiais.

Impacto de um analisador em consultas wildcard

Durante a análise de consultas, as consultas formuladas como prefixo, sufixo, wildcard ou expressões regulares são passadas como-é para a árvore de consulta, contornando a análise lexical. As correspondências só serão encontradas se o índice contiver as cordas no formato que a sua consulta especifica. Na maioria dos casos, você precisará de um analisador durante a indexação que preserva a integridade das cordas para que o termo parcial e a correspondência de padrões sejam bem sucedidos. Para obter mais informações, consulte a pesquisa parcial do termo nas consultas de Pesquisa Cognitiva Azure.

Considere uma situação em que pode querer que a consulta de pesquisa 'terminat*' devolva resultados que contenham termos como 'terminate', 'termination' e 'terminates'.

Se usasse o analisador en.lucene (Inglês Lucene), aplicaria uma decisão agressiva de cada termo. Por exemplo, 'terminar', 'rescisão', 'terminates' será tudo tokenizado até ao símbolo 'termi' no seu índice. Por outro lado, os termos em consultas que usam wildcards ou pesquisa duvidosa não são analisados de todo., por isso não haveria resultados que correspondessem à consulta 'terminat*'.

Por outro lado, os analisadores da Microsoft (neste caso, o analisador en.microsoft) são um pouco mais avançados e usam a lematização em vez de se conter. Isto significa que todos os tokens gerados devem ser palavras em inglês válidas. Por exemplo, 'terminate', 'terminates' e 'termination' permanecerão na sua maioria inteiros no índice, e seria uma escolha preferível para cenários que dependem muito de wildcards e pesquisa duvidosa.

Consultas de wildcard e regex

A Azure Cognitive Search utiliza pontuação baseada em frequência (BM25) para consultas de texto. No entanto, para consultas de wildcard e regex onde o âmbito de termos pode potencialmente ser amplo, o fator de frequência é ignorado para evitar que o ranking seja tendencioso para jogos de termos mais raros. Todos os jogos são tratados igualmente para pesquisas wildcard e regex.

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).

O agrupamento de campo é semelhante, mas o agrupamento é um único campo. Por exemplo, hotelAmenities:(gym+(wifi|pool)) procura no campo "hotelAmenities" para "ginásio" e "wifi", ou "ginásio" e "piscina".

Limites de tamanho de consulta

A Azure Cognitive Search impõe limites ao tamanho e composição da consulta porque consultas ilimitadas podem desestabilizar o seu serviço de pesquisa. Existem limites no tamanho e composição da consulta (número de cláusulas). Existem também limites para o comprimento da pesquisa de prefixos e para a complexidade da pesquisa regex e pesquisa de wildcard. 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 obter mais informações sobre os limites de consulta, consulte os limites de pedido da API.

Ver também