Exemples de syntaxe de recherche Lucene complète (requêtes avancées)
Lors de la création de requêtes pour Azure AI Recherche, vous pouvez remplacer l’analyseur de requêtes simple par défaut par l’analyseur de requêtes Lucene, plus puissant, afin de formuler des expressions de requêtes spécialisées et avancées.
L’analyseur Lucene prend en charge des formats de requêtes complexes, telles que des requêtes portant sur des champs, la recherche approximative, la recherche par caractères génériques infixes et suffixes, la recherche de proximité, la promotion de termes et la recherche d’expression régulière. La puissance supplémentaire est fournie avec plus d’exigences de traitement. Vous devez donc vous attendre à une durée d’exécution légèrement plus longue. Dans cet article, vous pouvez parcourir des exemples qui décrivent les opérations de requête basées sur la syntaxe complète.
Remarque
Une grande partie des constructions de requêtes spécialisées activées par le biais de la syntaxe de requête Lucene complète ne sont pas soumises à une analyse du texte, ce qui peut être surprenant si vous prévoyez une recherche de radical ou une lemmatisation. L’analyse lexicale est effectuée uniquement sur des termes complets (requête sur un terme ou une expression). Les types de requête avec des termes incomplets (requête de préfixe, de caractère générique, d’expression régulière, partielle) sont ajoutés directement à l’arborescence de requête, en ignorant la phase d’analyse. La seule transformation effectuée sur les termes de requête partiels est l’utilisation de minuscules.
Index hotels-sample
Les requêtes suivantes sont basées sur l’index hotels-sample, que vous pouvez créer en suivant les instructions de ce guide de démarrage rapide.
Les exemples de requêtes sont formulés à l’aide de l’API REST et des requêtes POST. Vous pouvez les coller et les exécuter dans un client REST. Utilisez plutôt la vue JSON du Navigateur de recherche dans le Portail Azure. En vue JSON, vous pouvez coller les exemples de requête présentés dans cet article.
Les en-têtes de requête doivent comporter les valeurs suivantes :
| Clé | Valeur |
|---|---|
| Type de contenu | application/json |
| api-key | <your-search-service-api-key>, clé de requête ou d’administration |
Les paramètres URI doivent inclure le point de terminaison de votre service de recherche avec le nom de l’index, les collections de documents, la commande de recherche et la version de l’API, comme dans l’exemple suivant :
https://{{service-name}}.search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2024-07-01
Le corps de la requête doit être formé comme un JSON valide :
{
"search": "*",
"queryType": "full",
"select": "HotelId, HotelName, Category, Tags, Description",
"count": true
}
searchdéfini sur * est une requête non spécifiée, équivalente à la recherche null ou vide. Elle n’est pas particulièrement utile, mais c’est la recherche la plus simple que vous puissiez effectuer, et elle affiche tous les champs récupérables dans l’index, avec toutes les valeurs.queryTypedéfini sur complet appelle l’analyseur de requête Lucene complet et il est nécessaire pour cette syntaxe.selectdéfini sur une liste de champs séparés par des virgules est utilisé pour la composition des résultats de la recherche, y compris uniquement les champs qui sont utiles pour les résultats de la recherche.countrenvoie le nombre de documents correspondant aux critères de recherche. Une chaîne de recherche vide comptabilise tous les documents figurant dans l’index (50 dans hotels-sample-index).
Exemple 1 : Recherche par champ
La recherche par champ permet de restreindre les expressions de recherche individuelles et intégrées à un champ spécifique. Dans cet exemple, on recherche les noms d’hôtels contenant le terme hôtel, mais pas motel. Vous pouvez spécifier plusieurs champs à l’aide de l’opérateur AND.
Lorsque vous utilisez cette syntaxe de requête, vous pouvez ignorer le paramètre searchFields lorsque les champs à interroger se trouvent dans l’expression de recherche. Si vous incluez searchFields dans une recherche par champ, le fieldName:searchExpression est toujours prioritaire par rapport à searchFields.
POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
"search": "HotelName:(hotel NOT motel) AND Category:'Boutique'",
"queryType": "full",
"select": "HotelName, Category",
"count": true
}
La réponse à cette requête doit ressembler à l’exemple suivant, filtré sur Boutique, renvoyant les noms d’hôtels contenant le terme hôtel, tout en excluant les résultats qui incluent motel dans le nom.
{
"@odata.count": 5,
"value": [
{
"@search.score": 2.2289815,
"HotelName": "Stay-Kay City Hotel",
"Category": "Boutique"
},
{
"@search.score": 1.3862944,
"HotelName": "City Skyline Antiquity Hotel",
"Category": "Boutique"
},
{
"@search.score": 1.355046,
"HotelName": "Old Century Hotel",
"Category": "Boutique"
},
{
"@search.score": 1.355046,
"HotelName": "Sublime Palace Hotel",
"Category": "Boutique"
},
{
"@search.score": 1.355046,
"HotelName": "Red Tide Hotel",
"Category": "Boutique"
}
]
}
L’expression de recherche peut être un mot ou une expression unique, ou bien une expression plus complexe entre parenthèses, éventuellement avec des opérateurs booléens. Voici quelques exemples :
HotelName:(hotel NOT motel)Address/StateProvince:("WA" OR "CA")Tags:("free wifi" NOT "free parking") AND "coffee in lobby"
Veillez à placer une expression entre guillemets si vous souhaitez que les deux chaînes soient évaluées comme une seule entité, comme ici où deux emplacements distincts sont recherchés dans le champ Address/StateProvince. Selon le client, vous devrez peut-être placer les guillemets dans une séquence d’échappement (\).
Le champ spécifié dans fieldName:searchExpression doit être un champ pouvant faire l’objet d’une recherche. Pour savoir comment les définitions de champs sont attribuées, consultez Créer un index (API REST).
Exemple 2 : Recherche approximative
Les recherches approximatives permettent d’obtenir des correspondances sur des termes similaires, y compris des mots mal orthographiés. Pour effectuer une recherche partielle, ajoutez le signe tilde ~ à la fin d’un mot avec un paramètre facultatif, une valeur comprise entre 0 et 2, qui spécifie la distance de modification. Par exemple, blue~ ou blue~1 retournent blue, blues et glue.
POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
"search": "Tags:conserge~",
"queryType": "full",
"select": "HotelName, Category, Tags",
"searchFields": "HotelName, Category, Tags",
"count": true
}
La réponse à cette requête est concierge dans les documents correspondants, ajustés par souci de concision :
{
"@odata.count": 9,
"value": [
{
"@search.score": 1.4947624,
"HotelName": "Twin Vortex Hotel",
"Category": "Luxury",
"Tags": [
"bar",
"restaurant",
"concierge"
]
},
{
"@search.score": 1.1685618,
"HotelName": "Stay-Kay City Hotel",
"Category": "Boutique",
"Tags": [
"view",
"air conditioning",
"concierge"
]
},
{
"@search.score": 1.1465473,
"HotelName": "Old Century Hotel",
"Category": "Boutique",
"Tags": [
"pool",
"free wifi",
"concierge"
]
},
. . .
]
}
Les phrases ne sont pas prises en charge directement, mais vous pouvez spécifier une correspondance partielle pour chaque terme d’une phrase à plusieurs éléments, par exemple search=Tags:landy~ AND sevic~. Cette expression de requête renvoie 15 correspondances pour le terme service de blanchisserie.
Remarque
Les requêtes approximatives ne sont pas analysées. Les types de requête avec des termes incomplets (requête de préfixe, de caractère générique, d’expression régulière, partielle) sont ajoutés directement à l’arborescence de requête, en ignorant la phase d’analyse. La seule transformation effectuée sur les termes de requête partiels est l’utilisation de minuscules.
Exemple 3 : Recherche de 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é.
Cette requête recherche les termes hôtel et aéroport distants de cinq mots ou moins dans un document. Les guillemets sont placés dans une séquence d’échappement (\") pour conserver l’expression :
POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
"search": "Description: \"hotel airport\"~5",
"queryType": "full",
"select": "HotelName, Description",
"searchFields": "HotelName, Description",
"count": true
}
La réponse à cette requête doit ressembler à l’exemple suivant :
{
"@odata.count": 1,
"value": [
{
"@search.score": 0.69167054,
"HotelName": "Trails End Motel",
"Description": "Only 8 miles from Downtown. On-site bar/restaurant, Free hot breakfast buffet, Free wireless internet, All non-smoking hotel. Only 15 miles from airport."
}
]
}
Exemple 4 : Promotion de 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. Pour promouvoir un terme, utilisez le signe « ^ » (caret) avec un facteur de promotion (un nombre) à la fin du terme recherché. La valeur par défaut du facteur de promotion est 1. Si cette valeur doit être positive, elle peut néanmoins être inférieure à 1 (0,2 par exemple). Il ne faut pas confondre la promotion de termes avec les profils de score, qui promeuvent certains champs plutôt que des termes spécifiques.
Dans cette requête avant, on recherche accès à la plage et on constate que six documents correspondent à au moins un des deux termes.
POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
"search": "beach access",
"queryType": "full",
"select": "HotelName, Description, Tags",
"searchFields": "HotelName, Description, Tags",
"count": true
}
Seuls deux documents correspondent à accès. La première instance se trouve en deuxième position, même si le terme plage est manquant dans le document.
{
"@odata.count": 6,
"value": [
{
"@search.score": 1.068669,
"HotelName": "Johnson's Family Resort",
"Description": "Family oriented resort located in the heart of the northland. Operated since 1962 by the Smith family, we have grown into one of the largest family resorts in the state. The home of excellent Smallmouth Bass fishing with 10 small cabins, we're a home not only to fishermen but their families as well. Rebuilt in the early 2000's, all of our cabins have all the comforts of home. Sporting a huge **beach** with multiple water toys for those sunny summer days and a Lodge full of games for when you just can't swim anymore, there's always something for the family to do. A full marina offers watercraft rentals, boat launch, powered dock slips, canoes (free to use), & fish cleaning facility. Rent pontoons, 14' fishing boats, 16' fishing rigs or jet ski's for a fun day or week on the water. Pets are accepted in the lakeside cottages.",
"Tags": [
"24-hour front desk service",
"pool",
"coffee in lobby"
]
},
{
"@search.score": 1.0162708,
"HotelName": "Campus Commander Hotel",
"Description": "Easy **access** to campus and steps away from the best shopping corridor in the city. From meetings in town or gameday, enjoy our prime location between the union and proximity to the university stadium.",
"Tags": [
"free parking",
"coffee in lobby",
"24-hour front desk service"
]
},
{
"@search.score": 0.9050383,
"HotelName": "Lakeside B & B",
"Description": "Nature is Home on the **beach**. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.",
"Tags": [
"laundry service",
"concierge",
"free parking"
]
},
{
"@search.score": 0.8955848,
"HotelName": "Windy Ocean Motel",
"Description": "Oceanfront hotel overlooking the **beach** features rooms with a private balcony and 2 indoor and outdoor pools. Inspired by the natural beauty of the island, each room includes an original painting of local scenes by the owner. Rooms include a mini fridge, Keurig coffee maker, and flatscreen TV. Various shops and art entertainment are on the boardwalk, just steps away.",
"Tags": [
"pool",
"air conditioning",
"bar"
]
},
{
"@search.score": 0.83636594,
"HotelName": "Happy Lake Resort & Restaurant",
"Description": "The largest year-round resort in the area offering more of everything for your vacation – at the best value! What can you enjoy while at the resort, aside from the mile-long sandy **beaches** of the lake? Check out our activities sure to excite both young and young-at-heart guests. We have it all, including being named “Property of the Year” and a “Top Ten Resort” by top publications.",
"Tags": [
"pool",
"bar",
"restaurant"
]
},
{
"@search.score": 0.7808502,
"HotelName": "Swirling Currents Hotel",
"Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking **access** to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. ",
"Tags": [
"air conditioning",
"laundry service",
"24-hour front desk service"
]
}
]
}
Dans la requête après, on répète la recherche, cette fois en promouvant les résultats contenant le terme plage par rapport au terme accès. search=Description:beach^2 access est une version lisible de la requête. Selon votre client, vous devrez peut-être exprimer ^2 comme suit %5E2.
POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
"search": "Description:beach^2 access",
"queryType": "full",
"select": "HotelName, Description, Tags",
"searchFields": "HotelName, Description, Tags",
"count": true
}
Après avoir lancé le terme plage, la correspondance sur Hôtel Campus Commander se déplace vers la cinquième place.
{
"@odata.count": 6,
"value": [
{
"@search.score": 2.137338,
"HotelName": "Johnson's Family Resort",
"Description": "Family oriented resort located in the heart of the northland. Operated since 1962 by the Smith family, we have grown into one of the largest family resorts in the state. The home of excellent Smallmouth Bass fishing with 10 small cabins, we're a home not only to fishermen but their families as well. Rebuilt in the early 2000's, all of our cabins have all the comforts of home. Sporting a huge beach with multiple water toys for those sunny summer days and a Lodge full of games for when you just can't swim anymore, there's always something for the family to do. A full marina offers watercraft rentals, boat launch, powered dock slips, canoes (free to use), & fish cleaning facility. Rent pontoons, 14' fishing boats, 16' fishing rigs or jet ski's for a fun day or week on the water. Pets are accepted in the lakeside cottages.",
"Tags": [
"24-hour front desk service",
"pool",
"coffee in lobby"
]
},
{
"@search.score": 1.8100766,
"HotelName": "Lakeside B & B",
"Description": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.",
"Tags": [
"laundry service",
"concierge",
"free parking"
]
},
{
"@search.score": 1.7911696,
"HotelName": "Windy Ocean Motel",
"Description": "Oceanfront hotel overlooking the beach features rooms with a private balcony and 2 indoor and outdoor pools. Inspired by the natural beauty of the island, each room includes an original painting of local scenes by the owner. Rooms include a mini fridge, Keurig coffee maker, and flatscreen TV. Various shops and art entertainment are on the boardwalk, just steps away.",
"Tags": [
"pool",
"air conditioning",
"bar"
]
},
{
"@search.score": 1.6727319,
"HotelName": "Happy Lake Resort & Restaurant",
"Description": "The largest year-round resort in the area offering more of everything for your vacation – at the best value! What can you enjoy while at the resort, aside from the mile-long sandy beaches of the lake? Check out our activities sure to excite both young and young-at-heart guests. We have it all, including being named “Property of the Year” and a “Top Ten Resort” by top publications.",
"Tags": [
"pool",
"bar",
"restaurant"
]
},
{
"@search.score": 1.0162708,
"HotelName": "Campus Commander Hotel",
"Description": "Easy access to campus and steps away from the best shopping corridor in the city. From meetings in town or gameday, enjoy our prime location between the union and proximity to the university stadium.",
"Tags": [
"free parking",
"coffee in lobby",
"24-hour front desk service"
]
},
{
"@search.score": 0.7808502,
"HotelName": "Swirling Currents Hotel",
"Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. ",
"Tags": [
"air conditioning",
"laundry service",
"24-hour front desk service"
]
}
]
}
Exemple 5 : Regex
Une recherche d’expression régulière trouve une correspondance en fonction du contenu placé entre des barres obliques /, comme le décrit la classe RegExp.
POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
"search": "HotelName:/(Mo|Ho)tel/",
"queryType": "full",
"select": "HotelName",
"count": true
}
La réponse à cette requête doit être similaire à l’exemple suivant, (ajusté par souci de concision) :
{
"@odata.count": 25,
"value": [
{
"@search.score": 1,
"HotelName": "Country Residence Hotel"
},
{
"@search.score": 1,
"HotelName": "Downtown Mix Hotel"
},
{
"@search.score": 1,
"HotelName": "Gastronomic Landscape Hotel"
},
. . .
{
"@search.score": 1,
"HotelName": "Trails End Motel"
},
{
"@search.score": 1,
"HotelName": "Nordick's Valley Motel"
},
{
"@search.score": 1,
"HotelName": "King's Cellar Hotel"
}
]
}
Remarque
Les requêtes Regex ne sont pas analysées. La seule transformation effectuée sur les termes de requête partiels est l’utilisation de minuscules.
Exemple 6 : 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 (?). L’analyseur de requêtes Lucene prend en charge l’utilisation de ces symboles avec un terme unique, et non une expression.
Dans cette requête, recherchez les noms d’hôtels qui contiennent le préfixe sc. Vous ne pouvez pas utiliser un symbole * ni ? comme premier caractère d’une recherche.
POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
"search": "HotelName:sc*",
"queryType": "full",
"select": "HotelName",
"count": true
}
La réponse à cette requête doit ressembler à l’exemple suivant :
{
"@odata.count": 1,
"value": [
{
"@search.score": 1,
"HotelName": "Waterfront Scottish Inn"
}
]
}
Remarque
Les requêtes par caractères génériques ne sont pas analysées. La seule transformation effectuée sur les termes de requête partiels est l’utilisation de minuscules.
Contenu connexe
Essayez de spécifier des requêtes dans le code. Le lien suivant explique comment configurer des requêtes de recherche à l’aide des SDK Azure.
Vous trouverez davantage d’informations de référence sur la syntaxe et sur l’architecture de requête ainsi que des exemples en cliquant sur les articles suivants :