Syntaxe des requêtes Lucene au sein de la recherche Azure AI

Lors de la création de requêtes dans la recherche Azure AI, vous pouvez choisir d’utiliser la syntaxe complète du parseur de requêtes Lucene afin de formuler des requêtes spécialisées, notamment les caractères génériques, la recherche approximative, la recherche de proximité et les expressions régulières. La majorité de la syntaxe du Lucene Query Parser est reprise telle quelle dans la recherche Azure AI, à l’exception des recherches par plage, qui sont définies au moyen d’expressions $filter.

Afin d’utiliser la syntaxe Lucene complète, vous devez définir queryType sur full et fournir une expression de requête conçue pour les caractères génériques, la recherche approximative ou toute autre forme de requête prise en charge par cette syntaxe étendue. Dans REST, les expressions de requête sont transmises via le paramètre search d’une requête Search 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. Cette requête identifie les hôtels dont le champ de catégorie contient le terme budget. Tous les documents contenant l’expression "recently renovated" bénéficient d’un meilleur classement en raison de la valeur de boost appliquée au terme (3).

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

Bien qu’il ne soit rattaché à aucun type de requête particulier, le paramètre searchMode joue un rôle pertinent dans cet exemple. Lorsque des opérateurs sont employés dans une requête, il est généralement conseillé de définir searchMode=all afin de garantir que l’ensemble des critères soit respecté.

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

Notions de base 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 Lucene complète, le tilde (~) est utilisé à la fois pour la recherche floue et pour la recherche de proximité. Lorsqu’il est positionné après une expression entre guillemets, ~ active une recherche de proximité. Lorsqu’il est placé à la fin d’un terme, ~ déclenche une recherche floue.

À l’intérieur d’un terme, comme business~analyst, ce caractère n’est pas interprété comme un opérateur. Dans cette situation, en supposant qu’il s’agisse d’une requête par mot ou par expression, la recherche en texte intégral avec analyse lexicale élimine le ~ et scinde le terme business~analyst en deux éléments distincts : business OU analyst.

L’exemple précédent porte sur le tilde (~), toutefois le même principe s’applique à l’ensemble des opérateurs.

É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 :
+ - & | ! ( ) { } [ ] ^ " ~ * ? : \ /

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 considéré comme un caractère non sécurisé, car il correspond à un identifiant de fragment ou d’ancrage dans 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 les valeurs dans la 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.

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

Opérateur booléen NOT

• Dans la syntaxe simple, les requêtes comportant une négation se voient systématiquement adjoindre automatiquement un caractère générique. Par exemple, la requête -luxury est automatiquement développée en -luxury *.
• Dans la syntaxe complète, les requêtes intégrant une négation ne peuvent pas être associées à un caractère générique. Par exemple, la requête -luxury * n’est pas autorisée.
• Dans la syntaxe complète, les requêtes composées d’une seule négation ne sont pas admises. Par exemple, la requête -luxury n’est pas autorisée.
• Dans la syntaxe complète, les négations fonctionnent comme si elles étaient toujours liées à la requête par un opérateur ET, indépendamment du mode de recherche utilisé.
  • Par exemple, la requête wifi -luxury en syntaxe complète récupère uniquement les documents contenant le terme wifi, puis applique la négation -luxury à cet ensemble de documents.
• Si vous souhaitez exploiter des négations afin d’effectuer une recherche sur l’ensemble des documents de l’index, il est recommandé d’utiliser la syntaxe simple avec le mode de recherche any.
• Si vous souhaitez utiliser des négations pour rechercher au sein d’un sous-ensemble de documents de l’index, il est conseillé d’employer la syntaxe complète ou la syntaxe simple avec le mode de recherche all.

Recherche par champ spécifié

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 .

Recherche floue

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 réaliser une recherche approximative, utilisez le symbole tilde ~ à la fin d’un mot unique, avec un paramètre facultatif correspondant à un nombre compris entre 0 et 2 (valeur par défaut), lequel définit la distance d’édition. Par exemple, blue~ ou blue~1 renverrait blue, blues et glue.

La recherche approximative s’applique uniquement aux termes et non aux expressions placées entre guillemets ; toutefois, il est possible d’ajouter le tilde à chaque terme individuellement dans un nom ou une expression composée de plusieurs mots. Par exemple, Unviersty~ of~ Wshington~ correspondrait à 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 le symbole tilde ~ à la fin d’une expression, suivi du nombre de mots définissant la limite de proximité. Par exemple, "hotel airport"~5 localise les termes hotel et airport lorsqu’ils se trouvent à moins de cinq mots l’un de l’autre 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 accorde une priorité plus élevée aux documents contenant les termes de recherche dans le champ genre plutôt que dans les autres champs consultables de l’index. En outre, les documents qui contiennent le terme de recherche rock sont classés plus haut que ceux contenant le terme de recherche electronic, en raison de la valeur de priorité du terme (2).

Pour augmenter la priorité d’un terme, utilisez le symbole ^ accompagné d’un facteur de priorité (un nombre) placé à la fin du terme recherché. Vous pouvez également promouvoir des expressions. Plus le facteur de priorité est élevé, plus le terme est considéré comme pertinent par rapport aux autres termes de la requête. Par défaut, le facteur de mise en avant est 1. Bien que le facteur de mise en avant doive être positif, 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 la recherche Azure AI, une expression régulière est définie comme suit :

• Placée entre deux barres obliques /
• Minuscules uniquement

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

Certains outils et langages imposent des contraintes supplémentaires concernant l’échappement des caractères, en complément des règles d’échappement appliquées par la recherche Azure AI. Dans le cas de JSON, les chaînes contenant une barre oblique doivent être échappées à l’aide d’une barre oblique inversée : microsoft.com/azure/ devient search=/.*microsoft.com\/azure\/.*/, où search=/.* <string-placeholder>.*/ représente l’expression régulière et microsoft.com\/azure\/ correspond à la chaîne avec la barre oblique échappée.

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. À titre d’illustration, /be./ fait correspondre les termes bee et bet, alors que /be*/ correspondrait à be, bee et beee, à l’exclusion de bet. Pris ensemble, .* permettent d’associer n’importe quelle suite de caractères ; ainsi, /be.*/ correspondrait à tout terme débutant par be, comme better.

Si des erreurs de syntaxe apparaissent dans votre expression régulière, il convient de vérifier les règles d’échappement applicables aux caractères spéciaux. Il est également possible de tester un autre client afin de déterminer si le problème est propre à l’outil utilisé.

Recherche par caractères génériques

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 sur les préfixes et sur les infixes. Pour la correspondance des suffixes, utilisez la syntaxe des expressions régulières.

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

Vous pouvez combiner plusieurs opérateurs dans une seule expression. Par exemple, 980?2* correspond à 98072-1222 et 98052-1234, où ? représente un caractère unique obligatoire et * représente une suite de caractères de 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 /. Il convient également de noter que * adopte un comportement différent lorsqu’il est utilisé en dehors des requêtes regex. En dehors du délimiteur regex /, * agit comme un caractère générique et correspond à toute suite de caractères, de la même manière que .* en regex. À titre d’exemple, search=/non.*al/ génère le même ensemble de résultats que search=non*al.

Effet d’un analyseur sur les requêtes comportant des caractères 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 majorité des cas, un analyseur est nécessaire lors de l’indexation afin de préserver l’intégrité des chaînes et de permettre la réussite de la correspondance partielle des termes et des motifs. Pour plus de détails, consultez Recherche de termes partiels dans les requêtes de recherche Azure AI.

Considérons une situation dans laquelle vous souhaitez que la requête de recherche terminal* renvoie des résultats contenant 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 et terminates seront tous tokenisés en un seul token termi dans votre index. En revanche, les termes de requête utilisant des caractères génériques ou la recherche floue ne sont pas analysés ; par conséquent, aucun résultat ne correspondrait à la requête terminat*.

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 resteraient en grande partie intacts dans l’index et constitueraient une option plus adaptée aux scénarios reposant fortement sur les caractères génériques et la recherche floue

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

La recherche Azure AI s’appuie sur un score basé sur la fréquence (BM25) pour les requêtes textuelles 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 certaines circonstances, vous pourriez souhaiter rechercher un caractère spécial, tel qu’un emoji « ❤ » ou le symbole « € ». 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 segmentent les caractères spéciaux incluent l’analyseur d’espaces blancs, lequel considère toute séquence de caractères séparée par des espaces blancs comme un token ; la chaîne ❤ serait donc traitée comme un token unique. 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.

Lors de l’utilisation de caractères Unicode, assurez-vous que les symboles sont correctement échappés dans l’URL de la requête ; par exemple, pour ❤, la séquence d’échappement à utiliser est %E2%9D%A4+. Certains clients REST réalisent cette conversion automatiquement.

Priorité (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 ainsi que soit wifi, soit 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 dans le champ hotelAmenities les termes gym et wifi, ou bien gym et pool.

Limites de taille des requêtes

La recherche Azure AI applique des limites à la taille et à la composition des requêtes, car des requêtes sans restriction peuvent compromettre la stabilité de 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

• Exemples de requêtes pour une recherche simple
• Exemples de requêtes pour une recherche Lucene complète
• Rechercher des documents
• Syntaxe des expressions OData pour les filtres et le tri
• Syntaxe de requête simple dans la recherche Azure AI