Syntaxe de requête Lucene dans Recherche Azure AI

  • Article

Lorsque vous créez des alertes dans Recherche Azure AI, vous pouvez choisir la syntaxe Analyseur de requêtes Lucene complète pour des formes de requêtes spécialisées : caractère générique, recherche approximative, recherche de proximité et expressions régulières. La plus grande partie de la syntaxe de l’analyseur de requêtes Lucene est implémentée telle quelle dans Recherche Azure AI, à l’exception des *recherches de plage, qui sont construites via des expressions $filter

Pour utiliser la syntaxe Lucene complète, définissez queryType sur full et passez une expression de requête modélisée pour les caractères génériques, la recherche approximative ou une des autres formes de requête prises en charge par la syntaxe complète. Dans REST, des expressions de requête sont fournies dans le paramètre search d’une requête Rechercher des documents (API REST).

Exemple (syntaxe complète)

L’exemple suivant est une demande de recherche construite à l’aide de la syntaxe complète. Cet exemple illustre une recherche dans le champ et une promotion de terme. Il recherche des hôtels où le champ de catégorie contient le terme budget. Tout document contenant l’expression "recently renovated" est classé plus haut en raison de la valeur de promotion de terme (3).

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

Bien qu’il ne soit spécifique d’aucun type de requête, le paramètre searchMode est pertinent dans cet exemple. Quand des opérateurs se trouvent sur la requête, vous devez généralement définir searchMode=all pour garantir que tous les critères sont satisfaits.

Pour plus d’exemples, consultez Exemples de syntaxe de requête Lucene. Pour plus d’informations sur la demande et les paramètres de requête, dont searchMode, consultez Rechercher des documents (API REST).

Bases de la syntaxe

Les principes de base suivants de la syntaxe s’appliquent à toutes les requêtes qui utilisent la syntaxe Lucene.

Évaluation des opérateurs en contexte

L’emplacement détermine si un symbole est interprété comme un opérateur ou simplement comme un autre caractère dans une chaîne.

Par exemple, dans la syntaxe complète Lucene, le tilde (~) est utilisé pour la recherche approximative et la recherche de proximité. Quand il est placé après une expression entre guillemets, ~ appelle la recherche de proximité. Quand il est placé à la fin d’un terme, ~ appelle la recherche approximative.

Au sein d’un terme, comme business~analyst, le caractère n’est pas évalué comme opérateur. Dans ce cas, en supposant que la requête est une requête de terme ou d’expression, la recherche en texte intégral avec analyse lexicale supprime le ~ et décompose le terme business~analyst en deux : business OR analyst.

L’exemple ci-dessus concerne le tilde (~), mais le même principe s’applique à chaque opérateur.

Échappement des caractères spéciaux

Pour utiliser l’un des opérateurs de recherche dans le cadre du texte de recherche, échappez le caractère en le préfixant avec une seule barre oblique inverse (\). Par exemple, pour une recherche avec caractères génériques sur https://, sachant que :// fait partie de la chaîne de requête, vous devez spécifier search=https\:\/\/*. De même, un modèle de numéro de téléphone placé dans une séquence d'échappement peut se présenter comme suit : \+1 \(800\) 642\-7676.

Les caractères spéciaux qui doivent être placés dans une séquence d'échappement sont les suivants :
+ - & | ! ( ) { } [ ] ^ " ~ * ? : \ /

Remarque

Bien que l'échappement maintienne les jetons ensemble, l'analyse lexicale pendant l'indexation peut les supprimer. Par exemple, l'analyseur Lucene standard coupe les mots sur les traits d'union, les espaces et autres caractères. Si vous avez besoin de caractères spéciaux dans la chaîne de requête, vous aurez peut-être également besoin d'un analyseur qui les conserve dans l'index. Parmi les choix possibles figurent les analyseurs de langage naturel de Microsoft, qui conservent les mots avec trait d'union, ou un analyseur personnalisé pour les modèles plus complexes. Pour plus d'informations, consultez Termes partiels, modèles et caractères spéciaux.

Encodage de caractères dangereux et réservés dans les URL

Vérifiez que tous les caractères non sécurisés et réservés sont encodés dans une URL. Par exemple, # est un caractère non sécurisé, car il s’agit d’un identificateur de fragment/d’ancrage au sein d’une URL. Le caractère doit être encodé en %23 s’il est utilisé dans une URL. & et = sont des exemples de caractères réservés, car ils délimitent les paramètres et spécifient des valeurs dans Recherche Azure AI. Consultez RFC1738 : Uniform Resource Locators (URL).

Les caractères dangereux sont " ` < > # % { } | \ ^ ~ [ ]. Les caractères réservés sont ; / ? : @ = + &.

Opérateurs booléens

Vous pouvez incorporer des opérateurs booléens dans une chaîne de requête pour améliorer la précision d’une correspondance. La syntaxe complète prend en charge des opérateurs de texte en plus des opérateurs de caractères. Spécifiez toujours les opérateurs booléens de texte (AND, OR, NOT) tout en majuscules.

Opérateur de texte Caractère Exemple Utilisation
AND + wifi AND luxury Spécifie les termes qu’une correspondance doit contenir. Dans l’exemple, le moteur de requête recherche les documents contenant à la fois wifi et luxury. Le caractère plus (+) peut également être utilisé directement devant un terme pour le rendre obligatoire. Par exemple, +wifi +luxury stipule que les deux termes doivent apparaître quelque part dans le champ d’un même document.
OR (none) 1 wifi OR luxury Trouve une correspondance quand un terme est trouvé. Dans l’exemple, le moteur de requête retourne des correspondances sur les documents contenant wifi ou luxury ou les deux. Comme OR est l’opérateur de conjonction par défaut, vous pouvez aussi l’omettre : ainsi, wifi luxury est l’équivalent de wifi OR luxury.
NOT !, - wifi –luxury Retourne une correspondance sur des documents qui excluent le terme. Par exemple, wifi –luxury recherche les documents qui contiennent le terme wifi, mais pas le terme luxury.

1 Le caractère | n’est pas pris en charge pour les opérations OR.

NOT opérateur booléen

Important

L’opérateur NOT (NOT, ! ou -) se comporte différemment dans la syntaxe complète par rapport à la syntaxe simple.

  • Dans une syntaxe simple, les requêtes avec négation ont toujours un caractère générique automatiquement ajouté. Par exemple, la requête -luxury est automatiquement développée pour -luxury *.
  • Dans la syntaxe complète, les requêtes avec négation ne peuvent pas être combinées à un caractère générique. Par exemple, les requêtes -luxury * ne sont pas autorisées.
  • Dans la syntaxe complète, les requêtes avec une seule négation ne sont pas autorisées. Par exemple, la requête -luxury n’est pas autorisée.
  • En syntaxe complète, les négations se comportent comme si elles sont toujours reliées par l’opérateur logique AND sur la requête, quel que soit le mode de recherche.
    • Par exemple, la requête de syntaxe complète wifi -luxury dans la syntaxe complète extrait uniquement les documents qui contiennent le terme wifi, puis applique la négation -luxury à ces documents.
  • Si vous voulez utiliser des négations pour effectuer une recherche dans tous les documents de l’index, une syntaxe simple avec le mode de recherche any est recommandée.
  • Si vous souhaitez utiliser des négations pour effectuer une recherche sur un sous-ensemble de documents dans l’index, une syntaxe complète ou la syntaxe simple avec le mode de recherche complet sont recommandées.
Query Type Mode de recherche Exemple de requête Comportement
Simplicité tous wifi -luxury Retourne tous les documents dans l’index. Les documents avec le terme « wifi » ou les documents ne contenant pas le terme « luxe » sont classés plus haut que d’autres documents. La requête est développée pour wifi OR -luxury OR *.
Simple all wifi -luxury Retourne uniquement les documents de l’index qui contiennent le terme « wifi » et ne contiennent pas le terme « luxe ». La requête est développée pour wifi AND -luxury AND *.
Complète tous wifi -luxury Retourne uniquement les documents de l’index qui contiennent le terme « wifi » et les documents qui contiennent le terme « luxe » sont supprimés des résultats.
Complète all wifi -luxury Retourne uniquement les documents de l’index qui contiennent le terme « wifi » et les documents qui contiennent le terme « luxe » sont supprimés des résultats.

Recherche par champ

Vous pouvez définir une opération de recherche par champ avec la syntaxe fieldName:searchExpression, où l’expression de recherche peut être un mot ou une phrase, ou une expression plus complexe entre parenthèses, éventuellement avec des opérateurs booléens. Voici quelques exemples :

  • genre:jazz NOT history

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

Veillez à placer les chaînes multiples entre guillemets si vous voulez que les deux chaînes soient évaluées comme une seule entité, comme ici où deux artistes distincts sont recherchés dans le champ artists.

Le champ spécifié dans fieldName:searchExpression doit être un champ searchable. Pour plus d’informations sur l’utilisation des attributs d’index dans les définitions de champs, consultez Créer un index .

Remarque

Lorsque vous utilisez des expressions de recherche par champ, il est inutile d’utiliser le paramètre searchFields, car chaque expression de recherche par champ a un nom de champ spécifié explicitement. Cependant, vous pouvez toujours utiliser le paramètre searchFields si vous voulez exécuter une requête où certaines parties sont limitées à un champ spécifique, et le reste peut s’appliquer à plusieurs champs. Par exemple, la requête search=genre:jazz NOT history&searchFields=description ne correspondrait à jazz qu’au niveau du champ genre, alors qu’elle correspondrait au champ NOT history avec le champ description. Le nom du champ fourni dans fieldName:searchExpression a toujours priorité sur le paramètre searchFields, c’est pourquoi dans cet exemple, nous n’avons pas besoin d’inclure genre dans le paramètre searchFields.

Recherche approximative

Une recherche approximative recherche des correspondances dans des termes à la construction similaire, en développant un terme jusqu’au maximum de 50 termes qui répondent aux critères de distance de deux ou moins. Pour plus d’informations, consultez Recherche approximative.

Pour effectuer une recherche approximative, utilisez le symbole ~ à la fin d’un mot avec un paramètre facultatif, un nombre compris entre 0 et 2 (la valeur par défaut), qui spécifie la distance de modification. Par exemple, blue~ ou blue~1 retournerait blue, blues et glue.

La recherche partielle est applicable uniquement pour les termes, et non les expressions délimitées par des guillemets, mais vous pouvez ajouter le tilde à chaque terme individuel dans un nom en plusieurs parties ou une expression. Par exemple, Unviersty~ of~ Wshington~ correspondrait uniquement à University of Washington.

Recherche par proximité

Les recherches de proximité servent à rechercher des termes qui sont proches les uns des autres dans un document. Insérez un signe tilde ~ à la fin d’une expression, suivi du nombre de mots qui créent la limite de proximité. Par exemple, "hotel airport"~5 recherche les termes hotel et airport distants de cinq mots ou moins dans un document.

Mise en avant des termes

La promotion de termes signifie que vous pouvez accorder à un document un rang plus élevé s’il contient le terme promu, par rapport aux documents qui ne contiennent pas ce terme. À ne pas confondre avec les profils de score qui promeuvent certains champs, plutôt que des termes spécifiques.

L’exemple suivant permet d’illustrer les différences entre les deux. Supposons qu’un profil de score promeuve les correspondances dans un certain champ, disons genre dans l’exemple musicstoreindex. En utilisant la promotion de termes, vous pouvez promouvoir encore plus certains termes de recherche. Par exemple, rock^2 electronic promeut les documents qui contiennent les termes de recherche dans le champ genre en les classant mieux que d’autres champs de recherche de l’index. Par ailleurs, les documents qui contiennent le terme de recherche rock bénéficient d’un meilleur classement que ceux qui contiennent le terme de recherche electronic en raison de la valeur de promotion du terme (2).

Pour promouvoir un terme, utilisez le signe ^ avec un facteur de promotion (un nombre) à la fin du terme recherché. Vous pouvez également promouvoir des expressions. Plus le facteur de promotion est élevé, plus le terme est pertinent par rapport aux autres termes de recherche. Par défaut, le facteur de mise en avant est 1. Ce facteur doit être positif, mais il peut être inférieur à 1 (par exemple 0,20).

Recherche d’expression régulière

Une recherche d’expression régulière trouve une correspondance en fonction de modèles qui sont valides sous Apache Lucene, comme le décrit la classe RegExp. Dans Recherche Azure AI, une expression régulière est placée entre des barres obliques /.

Par exemple, pour rechercher des documents contenant motel ou hotel, spécifiez /[mh]otel/. Les recherches d’expression régulière se font par comparaison avec des mots individuels.

Certains outils et langages imposent des exigences de caractère d’échappement supplémentaires en plus des règles d’échappement imposées par la Recherche Azure AI. Pour JSON, les chaînes qui incluent une barre oblique sont placées dans une séquence d’échappement avec une barre oblique inverse : microsoft.com/azure/ devient search=/.*microsoft.com\/azure\/.*/ où search=/.* <string-placeholder>.*/ configure l’expression régulière et microsoft.com\/azure\/ est la chaîne avec une barre oblique d’échappement.

Deux symboles courants dans les requêtes regex sont . et *. . correspond à n’importe quel caractère et * correspond au caractère précédent zéro ou plusieurs fois. Par exemple, /be./ correspond aux termes bee et bet tandis que /be*/ correspondrait à be, beeet beee, mais pas bet. Ensemble, .* vous permettent de rechercher n’importe quelle série de caractères de manière à ce que /be.*/ corresponde à tous les termes commençant par be, par exemple better.

Si vous obtenez des erreurs de syntaxe dans votre expression régulière, vérifiez les règles d’échappement pour voir si elles contiennent des caractères spéciaux. Vous pouvez également essayer un autre client pour vérifier si le problème est propre à l’outil.

Recherche avec caractère générique

Vous pouvez utiliser la syntaxe généralement reconnue pour effectuer des recherches avec plusieurs caractères génériques (*) ou un caractère générique unique (?). La syntaxe Lucene complète prend en charge la correspondance de préfixe, d’infixe et de suffixe.

Notez que l’Analyseur de requêtes Lucene prend en charge l’utilisation de ces symboles avec un terme unique, et non une expression.

Type d’affixe Description et exemples
prefix Le fragment de terme vient devant * ou ? . Par exemple, une expression de requête search=alpha* retourne alphanumeric ou alphabetical. La mise en correspondance de préfixe est prise en charge tant dans la syntaxe simple que dans la syntaxe complète.
suffix Le terme fragment vient derrière * ou ?, avec une barre oblique pour délimiter la construction. Par exemple, search=/.*numeric/ retourne alphanumeric.
Infixe Les fragments de terme encadrent * ou ?. Par exemple, search=non*al retourne non-numerical et nonsensical.

Vous pouvez combiner plusieurs opérateurs dans une seule expression. Par exemple, 980?2* correspond à 98072-1222 et 98052-1234, où ? correspond à un caractère unique (obligatoire) et * aux caractères d’une longueur arbitraire qui suivent.

La correspondance de suffixe nécessite les barres obliques / d’expression régulière comme délimiteurs. En règle générale, vous ne pouvez pas utiliser un symbole * ou ? comme premier caractère d’un terme, sans /. Notez également que * se comporte différemment quand il est utilisé en dehors des requêtes regex. En dehors des délimiteurs de barre oblique / de regex, * est un caractère générique qui correspond à toutes les séries de caractères, un peu comme .* dans les regex. Par exemple, search=/non.*al/ produit le même jeu de résultats que search=non*al.

Remarque

En règle générale, les critères spéciaux sont lents ; vous préférerez donc peut-être explorer d’autres méthodes, telles que la tokenisation Edge n-Gram qui crée des jetons pour les séquences de caractères d’un terme. Avec une segmentation du texte en unités lexicales n-gram, l’index est plus grand, mais les requêtes peuvent s’exécuter plus rapidement, en fonction de la construction du modèle et de la longueur des chaînes que vous indexez. Pour plus d’informations, consultez Recherche de termes partiels et modèles avec des caractères spéciaux.

Effet d’un analyseur sur les requêtes génériques

Pendant l’analyse des requêtes, les requêtes qui sont formulées sous forme de préfixe, de suffixe, de caractère générique ou d’expression régulière sont transmises telles quelles à l’arborescence de requête, en ignorant l’analyse lexicale. Les correspondances ne seront trouvées que si l’index contient les chaînes au format spécifié par votre requête. Dans la plupart des cas, vous avez besoin d’un analyseur pendant l’indexation qui préserve l’intégrité de la chaîne pour que le terme partiel et les critères spéciaux soient respectés. Pour plus d’informations, consultez Recherche de termes partiels dans les requêtes Recherche Azure AI.

Supposons que vous souhaitez que la requête de recherche terminal* retourne des résultats qui contiennent des termes tels que terminate, termination et terminates.

Si vous deviez utiliser l’analyseur en.lucene (Lucene anglais), il appliquerait une recherche de radical agressive pour chaque terme. Par exemple, terminate, termination, terminates seront tous sous forme de jeton jusqu’au jeton termi dans votre index. D’un côté, comme les termes dans les requêtes utilisant des caractères génériques ou une recherche approximative ne sont pas analysés du tout, la requête terminat* ne donnerait aucun résultat.

D’un autre côté, les analyseurs Microsoft (dans ce cas, l’analyseur en.microsoft) sont un peu plus avancés et utilisent la lemmatisation et non la recherche de radical. Cela signifie que tous les jetons générés doivent être des mots anglais valides. Par exemple, terminate, terminates, et termination seront généralement conservés dans leur forme entière dans l’index, ce qui constitue un choix préférable pour les scénarios qui dépendent beaucoup des caractères génériques et de la recherche approximative.

Scoring des requêtes avec des caractères génériques et des expressions régulières

La Recherche Azure AI utilise un scoring basé sur la fréquence (BM25) pour les requêtes de texte. Cependant, pour les requêtes avec des caractères génériques et des expressions régulières où l’étendue des termes est potentiellement vaste, le facteur de fréquence est ignoré pour empêcher que le classement soit faussé par les correspondances avec des termes plus rares. Toutes les correspondances sont traitées de façon égale pour les recherches avec des caractères génériques et avec des expressions régulières.

Caractères spéciaux

Dans certains cas, vous rechercherez un caractère spécial, tel que l’émoji « ❤ » ou le signe « € ». Le cas échéant, assurez-vous que l’analyseur que vous utilisez n’ignore pas ces caractères. L’analyseur standard ignore de nombreux caractères spéciaux, en les excluant de votre index.

Les analyseurs qui marquent les caractères spéciaux incluent l’analyseur d’« espace blanc », qui considère toute séquence de caractères séparée par des espaces blancs comme un jeton (la chaîne ❤ serait donc considérée comme un jeton). En outre, un analyseur de langage comme l’analyseur Microsoft English (« en.microsoft ») considère la chaîne « € » comme un jeton. Vous pouvez tester un analyseur pour voir quels jetons il génère pour une requête donnée.

Lorsque vous utilisez des caractères Unicode, assurez-vous que les symboles sont correctement placés dans une séquence d’échappement dans l’URL de la requête (par exemple, pour ❤, utilisez la séquence d’échappement %E2%9D%A4+). Certains clients REST effectuent cette traduction automatiquement.

Précédence (regroupement)

Vous pouvez utiliser des parenthèses pour créer des sous-requêtes, en incluant des opérateurs au sein de l’instruction entre parenthèses. Par exemple, motel+(wifi|luxury) recherche les documents contenant le terme motel, et wifi ou luxury (ou les deux).

Le regroupement de champs est similaire, mais il délimite le regroupement à un seul champ. Par exemple, hotelAmenities:(gym+(wifi|pool)) recherche le champ hotelAmenities pour gym et wifi, ou gym et pool.

Limites de taille des requêtes

La Recherche Azure AI impose des limites sur la taille et la composition de la requête, car les requêtes illimitées peuvent déstabiliser votre service de recherche. Il existe des limites sur la taille et la composition de la requête (le nombre de clauses). Il existe également des limites sur la longueur de la recherche de préfixe, et sur la complexité de la recherche avec des regex et des caractères génériques. Si votre application génère des requêtes de recherche par programmation, nous vous recommandons de la concevoir de façon à ce qu’elle ne génère pas des requêtes d’une taille illimitée.

Pour plus d’informations sur les limites de requête, consultez Limites des demandes d’API.

Voir aussi