Syntaxe de requête simple dans Recherche Azure AI

Pour les scénarios de recherche en texte intégral, Recherche Azure AI implémente deux langages de requête Lucene, chacun associé à un analyseur de requêtes. L’analyseur de requête simple est la valeur par défaut. Il couvre les cas d’usage courants et tente d’interpréter une requête même si elle n’est pas parfaitement composée. L’autre analyseur est Lucene Query Parser et prend en charge les constructions de requêtes plus avancées.

Cet article est la référence de syntaxe de requête pour l’analyseur de requête simple.

La syntaxe de requête pour les deux analyseurs s’applique aux expressions de requête passées dans le search paramètre d’une requête, à ne pas confondre avec la syntaxe OData, avec sa propre syntaxe et ses propres règles pour filter et orderby expressions dans la même requête.

Bien que l’analyseur simple soit basé sur la classe Apache Lucene Simple Query Parser, son implémentation dans Recherche Azure AI exclut la recherche approximative. Si vous avez besoin d’une recherche approximative, considérez plutôt l'option de la syntaxe de requête Lucene complète.

Exemple (syntaxe simple)

Cet exemple montre une requête simple, distinguée par "queryType": "simple" une syntaxe valide. Bien que le type de requête soit défini ci-dessous, il s’agit de la valeur par défaut et peut être omis, sauf si vous revenez à partir d’un type alternatif. L’exemple suivant est une recherche sur des termes indépendants, avec une exigence que tous les documents correspondants incluent « 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"
}

Le searchMode paramètre est pertinent dans cet exemple. Chaque fois que les opérateurs booléens se trouvent sur la requête, vous devez généralement définir searchMode=all pour vous assurer que tous les critères sont mis en correspondance. Sinon, vous pouvez utiliser la valeur par défaut searchMode=any qui favorise le rappel par rapport à la précision.

Pour plus d’exemples, consultez des exemples de syntaxe de requête simple. Pour plus d’informations sur la demande de requête et les paramètres, consultez l’API REST (Search Documents).

Recherche de mots clés sur les termes et les expressions

Les chaînes transmises au search paramètre peuvent inclure des termes ou des expressions dans n’importe quelle langue prise en charge, les opérateurs booléens, les opérateurs de précédence, les caractères génériques ou les caractères de préfixe pour les requêtes « commence par », les caractères d’échappement et les caractères d’encodage d’URL. Le search paramètre est facultatif. Unspecified, search (search=* ou search=" ") retourne les 50 premiers documents dans l’ordre arbitraire (non classé).

  • Une recherche de terme est une requête d’un ou plusieurs termes, où l’un des termes est considéré comme une correspondance.

  • Une recherche d’expressions est une expression exacte placée entre guillemets " ". Par exemple, alors que Roach Motel (sans guillemets) recherche des documents contenant Roach et/ou Motel n’importe où dans n’importe quel ordre, "Roach Motel" (avec des guillemets) correspond uniquement aux documents qui contiennent cette expression entière et dans cet ordre (l’analyse lexicale s’applique toujours).

Selon votre client de recherche, vous devrez peut-être échapper les guillemets dans une recherche par expressions. Par exemple, dans une requête POST, une recherche d’expressions dans "Roach Motel" le corps de la requête peut être spécifiée en tant que "\"Roach Motel\"". Si vous utilisez les SDK Azure, le client de recherche échappe les guillemets lorsqu'il serialize le texte de recherche. Votre expression de recherche peut être envoyée en tant que « Roach Motel ».

Par défaut, toutes les chaînes passées dans le search paramètre subissent une analyse lexicale. Vérifiez que vous comprenez le comportement de tokenisation de l’analyseur que vous utilisez. Souvent, lorsque les résultats de la requête sont inattendus, la raison peut être tracée sur la façon dont les termes sont tokenisés au moment de la requête. Vous pouvez tester la jetonisation sur des chaînes spécifiques pour confirmer la sortie.

Toute entrée de texte avec un ou plusieurs termes est considérée comme un point de départ valide pour l’exécution des requêtes. Recherche Azure AI correspondra aux documents contenant tout ou partie des termes, y compris les variantes trouvées lors de l’analyse du texte.

Aussi simple que cela puisse paraître, il existe un aspect de l'exécution des requêtes au sein d'Recherche Azure AI qui pourrait produire des résultats inattendus, augmentant plutôt que de les diminuer à mesure que plus de termes et d'opérateurs sont ajoutés à la chaîne d'entrée. Si cette extension se produit réellement dépend de l’inclusion d’un opérateur NOT, combinée à un paramètre searchMode qui détermine comment NOT est interprété en termes de comportements AND ou OR. Pour plus d’informations, consultez l’opérateur NOT sous opérateurs booléens.

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. Dans la syntaxe simple, les opérateurs booléens sont basés sur des caractères. Les opérateurs de texte, tels que le mot AND, ne sont pas pris en charge.

Caractère Exemple Utilisation
+ pool + ocean Une opération AND . Par exemple, pool + ocean stipule qu’un document doit contenir les deux termes.
| pool | ocean Une OR opération recherche une correspondance lorsque l’un ou l’autre terme est trouvé. Dans l’exemple, le moteur de requête retournera une correspondance sur les documents contenant soit pool, soit ocean, ou les deux. Comme OR il s’agit de l’opérateur de conjonction par défaut, vous pouvez également l’abandonner, de sorte que pool ocean c’est l’équivalent de pool | ocean.
- pool – ocean Une opération NOT retourne les correspondances des documents dans lesquels le terme est exclu.

Le paramètre searchMode d'une requête contrôle si un terme avec l'opérateur NOT est ANDé ou ORé avec d'autres termes dans la requête (en supposant qu'il n'y a pas d'opérateurs booléens sur les autres termes). Les valeurs valides incluent any ou all.

searchMode=any augmente le rappel des requêtes en incluant plus de résultats, et par défaut - sera interprété comme « OR NOT ». Par exemple, pool - ocean correspond aux documents qui contiennent le terme pool ou ceux qui ne contiennent pas le terme ocean.

searchMode=all augmente la précision des requêtes en incluant moins de résultats, et par défaut - sera interprétée comme « AND NOT ». Par exemple, avec searchMode=any, la requête pool - ocean correspond aux documents qui contiennent le terme « pool » et tous les documents qui ne contiennent pas le terme « océan ». Il s’agit sans doute d’un comportement plus intuitif pour l’opérateur - . Par conséquent, vous devez envisager d'utiliser searchMode=all plutôt que searchMode=any si vous souhaitez optimiser les recherches pour la précision au lieu du rappel, et que vos utilisateurs utilisent fréquemment l'opérateur - dans les recherches.

Lorsque vous décidez d’un searchMode paramètre, tenez compte des modèles d’interaction utilisateur pour les requêtes dans différentes applications. Les utilisateurs qui recherchent des informations sont plus susceptibles d’inclure un opérateur dans une requête, par opposition aux sites de commerce électronique qui ont des structures de navigation plus intégrées.

Requêtes de préfixe

Pour les requêtes « commence par », ajoutez un opérateur de suffixe (*) comme espace réservé pour le reste d’un terme. Une requête de préfixe doit commencer par au moins un caractère de texte brut avant de pouvoir ajouter l’opérateur de suffixe.

Caractère Exemple Utilisation
* lingui* correspond à « linguistique » ou « linguini » L’astérisque (*) représente un ou plusieurs caractères de longueur arbitraire, ignorant la casse.

Comme pour les filtres, une requête de préfixe recherche une correspondance exacte. Par conséquent, il n’existe aucun score de pertinence (tous les résultats reçoivent un score de recherche de 1,0). N’oubliez pas que les requêtes de préfixe peuvent être lentes, en particulier si l’index est volumineux et que le préfixe se compose d’un petit nombre de caractères. Une autre méthodologie, telle que la tokenisation par n-grammes de bord, peut être plus rapide. Les termes utilisant la recherche de préfixes ne peuvent pas dépasser 1 000 caractères.

La syntaxe simple prend en charge la correspondance de préfixe uniquement. Pour la correspondance de suffixe ou d'infixe par rapport à la fin ou au milieu d'un terme, utilisez la syntaxe complète Lucene pour la recherche par joker.

Échapper les opérateurs de recherche

Dans la syntaxe simple, les opérateurs de recherche incluent les caractères suivants : + | " ( ) ' \

Si l’un de ces caractères fait partie d’un jeton dans l’index, échappez-le en le préfixant avec une barre oblique inverse (\) unique dans la requête. Par exemple, supposons que vous utilisiez un analyseur personnalisé pour la tokenisation de terme entier et que votre index contient la chaîne « Luxury+Hotel ». Pour obtenir une correspondance exacte sur ce jeton, insérez un caractère d’échappement : search=luxury\+hotel.

Pour rendre les choses simples pour les cas plus classiques, il existe deux exceptions à cette règle où l’échappement n’est pas nécessaire :

  • L’opérateur - NOT doit uniquement être échappé s’il s’agit du premier caractère après un espace blanc. Si l’élément - apparaît au milieu (par exemple, dans 3352CDD0-EF30-4A2E-A512-3B30AF40F3FD), vous pouvez ignorer l’échappement.

  • L’opérateur de suffixe * doit uniquement être échappé s’il s’agit du dernier caractère avant un espace. Si l’élément * apparaît au centre (par exemple, dans 4*4=16), aucun échappement n’est nécessaire.

Note

Par défaut, l’analyseur standard supprime et interrompt les mots sur les traits d’union, les espaces blancs, les ampersands et d’autres caractères pendant l’analyse lexicale. Si vous avez besoin de caractères spéciaux pour rester dans la chaîne de requête, vous aurez peut-être besoin d’un analyseur qui les conserve dans l’index. Certains choix incluent les analyseurs de langage naturel Microsoft, qui préservent les mots avec traits d'union, ou un analyseur personnalisé pour des modèles plus complexes. Pour plus d’informations, consultez Les termes partiels, les modèles et les caractères spéciaux.

Encodage de caractères non sécurisés 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’ancre dans une URL. Le caractère doit être encodé %23 si 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. Pour plus d’informations, consultez RFC1738 : Uniform Resource Locators (URL).

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

Caractères spéciaux

Les caractères spéciaux peuvent aller des symboles monétaires tels que « $ » ou « € », aux emojis. De nombreux analyseurs, y compris l’analyseur standard par défaut, excluront les caractères spéciaux pendant l’indexation, ce qui signifie qu’ils ne seront pas représentés dans votre index.

Si vous avez besoin d’une représentation de caractères spéciaux, vous pouvez assigner un analyseur qui les conserve :

  • L’analyseur d’espace blanc considère toute séquence de caractères séparée par des espaces blancs comme des jetons (de sorte que l’emoji « ❤ » serait considéré comme un jeton).

  • Un analyseur linguistique, tel que l'analyseur linguistique anglais de Microsoft (en.microsoft), prend la chaîne '$' ou '€' comme symbole.

Pour confirmation, vous pouvez tester un analyseur pour voir quels jetons sont générés pour une chaîne donnée. Comme on peut s'y attendre, vous risquez de ne pas obtenir une tokenisation complète à partir d’un seul analyseur. Une solution de contournement consiste à créer plusieurs champs qui contiennent le même contenu, mais avec des affectations d’analyseur différentes (par exemple, description_en, description_fret ainsi de suite pour les analyseurs de langage).

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

Priorité (regroupement)

Vous pouvez utiliser des parenthèses pour créer des sous-requêtes, en intégrant des opérateurs dans la déclaration entre parenthèses. Par exemple, motel+(wifi|luxury) recherche des documents contenant le terme « motel » et « wifi » ou « luxe » (ou les deux).

Limites de taille des requêtes

Si votre application génère des requêtes de recherche par programmation, nous vous recommandons de la concevoir de telle manière qu’elle ne génère pas de requêtes de taille non limitée.

  • Pour GET, la longueur de l’URL ne peut pas dépasser 8 Ko.

  • Pour POST (et toute autre requête), où le corps de la requête inclut search et d’autres paramètres tels que filter et orderby, la taille maximale est de 16 Mo. Les limites supplémentaires sont les suivantes :

    • La longueur maximale de la clause de recherche est de 100 000 caractères.
    • Le nombre maximal de clauses dans search (expressions séparées par AND ou OR) est de 1024.
    • La taille maximale du terme de recherche est de 1 000 caractères pour la recherche de préfixes.
    • Il existe également une limite d’environ 32 Ko sur la taille d’un terme individuel dans une requête.

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

Étapes suivantes

Si vous allez construire des requêtes de manière programmatique, passez en revue Recherche en texte intégral dans Recherche Azure AI pour comprendre les étapes du traitement des requêtes et les implications de l'analyse du texte.

Vous pouvez également consulter les articles suivants pour en savoir plus sur la construction des requêtes :

  • Last updated on