Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Note
Recherche Azure AI est disponible via le portail Azure, les API REST et les SDK Azure. Il sous-tend également Foundry IQ, la couche de connaissances managée qui transforme le contenu d’entreprise en bases de connaissances réutilisables et prenant en charge les autorisations pour les agents dans le portail Microsoft Foundry.
Important
Les fonctionnalités, capacités ou propriétés marquées (préversion) ne sont pas couvertes par un accord de niveau de service, ne sont pas recommandées pour les workloads de production et peuvent être modifiées ou faire l’objet de restrictions avant leur mise à disposition générale. Les Recherche Azure AI termes de la préversion s'appliquent à toutes les fonctionnalités d'aperçu, qu'il s'agisse d'une fonctionnalité autonome ou d'une partie d'une fonctionnalité généralement disponible.
Cette section étend la configuration de navigation à facettes avec des exemples illustrant l’utilisation de base et d’autres scénarios.
Les champs facetables sont définis dans un index, mais les paramètres de facette et les expressions sont définis dans les requêtes de requête. Si vous avez un index avec des champs facetables, vous pouvez essayer des hiérarchies de facettes (préversion),des agrégations de facettes (préversion) et des filtres de facettes (préversion) sur les index existants.
Paramètres de facette et syntaxe
Selon l’API, une requête de facette est généralement un tableau d’expressions de facette appliquées aux résultats de recherche. Chaque expression de facette contient un nom de champ facetable, éventuellement suivi d’une liste séparée par des virgules de paires nom-valeur.
- Requête facette est une requête qui inclut une propriété de facette.
-
Le champ facetable est une définition de champ dans l’index de recherche attribué avec la
facetablepropriété. - nombre de correspondances pour chaque facette trouvée dans les résultats de la recherche.
Le tableau suivant décrit les paramètres de facette utilisés dans les exemples.
| Paramètre de facette | Description | Utilisation | Exemple |
|---|---|---|---|
count |
Nombre maximal de termes de facette par structure. | Entier. La valeur par défaut est 10. Il n’existe aucune limite supérieure, mais des valeurs plus élevées dégradent les performances, en particulier si le champ à facettes contient un grand nombre de termes uniques. Cela est dû à la façon dont les requêtes de facette sont distribuées entre les fragments. Vous pouvez définir count à zéro ou à une valeur supérieure ou égale au nombre de valeurs uniques dans le champ facetable pour obtenir un nombre exact sur toutes les partitions. L’inconvénient est une latence accrue. |
Tags,count:5 limite la réponse de navigation par facettes à 5 compartiments à facettes qui contiennent les nombres de facettes les plus nombreux, mais ils peuvent être dans n’importe quel ordre. |
sort |
Détermine l’ordre des compartiments de facettes. | Les valeurs valides sont count, , -countvalue, -value. Utilisez count pour répertorier les facettes de la plus grande à la plus petite. Permet -count de trier dans l’ordre croissant (le plus petit au plus grand). Permet value de trier alphanumériquement par valeur de facette dans l’ordre croissant. Permet -value de trier l’ordre décroissant par valeur. |
"facet=Category,count:3,sort:count" obtient les trois premiers groupes de facettes dans les résultats de recherche, répertoriés dans l’ordre décroissant par le nombre de correspondances dans chaque Catégorie. Si les trois premières catégories sont Économique, Long Séjour et Luxe, et Économique a 5 succès, Long Séjour a 6, et Luxe a 4, alors les compartiments de facettes sont classés dans l'ordre Long Séjour, Économique, Luxe. Un autre exemple est"facet=Rating,sort:-value". Elle produit des facettes pour toutes les évaluations possibles, dans l’ordre décroissant par valeur. Si les évaluations sont comprises entre 1 et 5, les facettes sont classées 5, 4, 3, 2, 1, quel que soit le nombre de documents correspondant à chaque évaluation. |
values |
Fournit des valeurs pour les étiquettes de facette. | Définissez des valeurs numériques délimitées par des barres verticales ou des valeurs Edm.DateTimeOffset spécifiant un ensemble dynamique de valeurs d’entrées de facettes. Les valeurs doivent être répertoriées dans un ordre séquentiel croissant pour obtenir les résultats attendus. |
"facet=baseRate,values:10 | 20" génère trois compartiments : un pour le taux de base compris entre 0 et 10 exclus, un de 10 à 20 exclus et un pour 20 et plus. Une chaîne "facet=lastRenovationDate,values:2024-02-01T00:00:00Z" produit deux compartiments à facettes : un pour les hôtels rénovés avant février 2024, et un pour les hôtels rénovés le 1er février 2024 ou ultérieur. |
interval |
Fournit une séquence d’intervalles pour les facettes qui peuvent être regroupées en intervalles. | Intervalle entier supérieur à zéro pour les nombres, ou minute, heure, jour, semaine, mois, trimestre, année pour les valeurs d’heure de date. |
"facet=baseRate,interval:100" produit des seaux à facettes basés sur des intervalles de taux de base de taille 100. Si les tarifs de base sont compris entre 60 $ et 600 $, il existe des compartiments à facettes pour 0-100, 100-200, 200-300, 300-400, 400-500 et 500-600. La chaîne "facet=lastRenovationDate,interval:year" produit un compartiment à facettes pour chaque année qu’un hôtel a été rénové. |
timeoffset |
Spécifie le décalage horaire UTC à prendre en compte dans la définition des limites de temps. | Défini sur ([+-]hh:mm, [+-]hhmm, or [+-]hh). S’il est utilisé, le timeoffset paramètre doit être combiné avec l’option d’intervalle, et uniquement lorsqu’il est appliqué à un champ de type Edm.DateTimeOffset. |
"facet=lastRenovationDate,interval:day,timeoffset:-01:00" utilise la limite de jour qui commence à 01:00:00 UTC (minuit dans le fuseau horaire cible). |
count et sort peuvent être combinés dans la même spécification de facette, mais ils ne peuvent pas être combinés avec interval ou values.
interval et values ne peut pas être combiné ensemble.
Les facettes d’intervalle de date et d’heure sont calculées en fonction de l’heure UTC si timeoffset n’est pas spécifié. Par exemple, pour "facet=lastRenovationDate,interval:day", la limite de jour commence à 00:00:00 UTC.
Exemple de facette de base
Les requêtes de facettes suivantes fonctionnent avec l’index hotels-sample. Vous pouvez utiliser la vue JSON dans l’Explorateur de recherche pour coller dans la requête JSON. Pour obtenir de l’aide sur la prise en main, consultez Ajouter une navigation à facettes aux résultats de la recherche.
Cette première requête récupère les facettes pour les Catégories, les Évaluations, les Tags et les chambres avec baseRate valeurs dans des plages spécifiques. Notez que la dernière facette se trouve sur un sous-champ de la collection Rooms. Les facettes comptent le document parent (Hôtels) et non les sous-documents intermédiaires (Salles), de sorte que la réponse détermine le nombre d’hôtels qui ont des chambres dans chaque catégorie tarifaire.
POST /indexes/hotels-sample/docs/search?api-version={{api_version}}
{
"search": "ocean view",
"facets": [ "Category", "Rating", "Tags", "Rooms/BaseRate,values:80|150|220" ],
"count": true
}
Ce deuxième exemple utilise un filtre pour affiner le résultat de la requête à facettes précédente une fois que l’utilisateur sélectionne l’évaluation 3 et la catégorie « Motel ».
POST /indexes/hotels-sample/docs/search?api-version={{api_version}}
{
"search": "water view",
"facets": [ "Tags", "Rooms/BaseRate,values:80|150|220" ],
"filter": "Rating eq 3 and Category eq 'Motel'",
"count": true
}
Le troisième exemple définit une limite supérieure sur les termes uniques retournés dans une requête. La valeur par défaut est 10, mais vous pouvez augmenter ou diminuer cette valeur à l’aide du paramètre count sur l’attribut de facette. Cet exemple retourne des facettes de la ville, limitées à 5.
POST /indexes/hotels-sample/docs/search?api-version={{api_version}}
{
"search": "view",
"facets": [ "Address/City,count:5" ],
"count": true
}
Cet exemple montre trois facettes pour « Category », « Tags » et « Rating », avec un remplacement de nombre sur « Tags » et un remplacement de plage pour « Rating », qui est autrement stocké sous la forme d’un double dans l’index.
POST https://{{service_name}}.search.windows.net/indexes/hotels-sample/docs/search?api-version={{api_version}}
{
"search": "*",
"facets": [
"Category",
"Tags,count:5",
"Rating,values:1|2|3|4|5"
],
"count": true
}
Pour chaque arborescence de navigation à facettes, il existe une limite par défaut des 10 principales instances de facette trouvées par la requête. Cette valeur par défaut est logique pour les structures de navigation, car elle conserve la liste des valeurs à une taille gérable. Vous pouvez remplacer la valeur par défaut en affectant une valeur à « count ». Par exemple, "Tags,count:5" réduit le nombre d’étiquettes sous la section Étiquettes aux cinq premières.
Pour les valeurs Numeric et DateTime uniquement, vous pouvez définir explicitement des valeurs sur le champ de facette (par exemple facet=Rating,values:1|2|3|4|5) pour séparer les résultats en plages contiguës (plages basées sur des valeurs numériques ou des périodes). Vous pouvez également ajouter « interval », comme dans facet=Rating,interval:1.
Chaque plage est générée à l’aide de 0 comme point de départ, d’une valeur de la liste en tant que point de terminaison, puis coupée de la plage précédente pour créer des intervalles discrets.
Exemple de valeurs distinctes
Vous pouvez formuler une requête qui retourne un nombre de valeurs distinct pour chaque champ facetable. Cet exemple formule une requête vide ou non qualifiée ("search": "*") qui correspond à tous les documents, mais en définissant top sur zéro, vous obtenez uniquement les nombres, sans résultat.
Pour des raisons de concision, cette requête inclut seulement deux champs marqués comme facetable dans l’index de l’exemple d’hôtels.
POST https://{{service_name}}.search.windows.net/indexes/hotels-sample/docs/search?api-version={{api_version}}
{
"search": "*",
"count": true,
"top": 0,
"facets": [
"Category", "Address/StateProvince""
]
}
Les résultats de cette requête sont les suivants :
{
"@odata.count": 50,
"@search.facets": {
"Address/StateProvince": [
{
"count": 9,
"value": "WA"
},
{
"count": 6,
"value": "CA "
},
{
"count": 4,
"value": "FL"
},
{
"count": 3,
"value": "NY"
},
{
"count": 3,
"value": "OR"
},
{
"count": 3,
"value": "TX"
},
{
"count": 2,
"value": "GA"
},
{
"count": 2,
"value": "MA"
},
{
"count": 2,
"value": "TN"
},
{
"count": 1,
"value": "AZ"
}
],
"Category": [
{
"count": 13,
"value": "Budget"
},
{
"count": 12,
"value": "Suite"
},
{
"count": 7,
"value": "Boutique"
},
{
"count": 7,
"value": "Resort and Spa"
},
{
"count": 6,
"value": "Extended-Stay"
},
{
"count": 5,
"value": "Luxury"
}
]
},
"value": []
}
Exemple de hiérarchie de facettes (préversion)
À l’aide de l’API REST version la plus récente ou du portail Azure, vous pouvez configurer une hiérarchie de facettes à l’aide des opérateurs > et ;.
| Opérateur | Description |
|---|---|
> |
L’opérateur d’imbrication (hiérarchique) désigne une relation parent-enfant. |
; |
L’opérateur point-virgule désigne plusieurs champs au même niveau d’imbrication, qui sont tous les enfants du même parent. Le parent ne doit contenir qu’un seul champ. Les champs parent et enfant doivent tous deux être facetable. |
L’ordre des opérations dans une expression de facette qui inclut des hiérarchies de facettes est :
- Opérateur d’options (virgule
,) qui sépare les paramètres de facette pour le champ de facette, tels que la virgule dansRooms/BaseRate,values - Les parenthèses, telles que celles englobantes
(Rooms/BaseRate,values:50 ; Rooms/Type). - Opérateur d’imbrication (crochet angulaire
>) - Opérateur d’ajout (point-virgule
;), illustré dans un deuxième exemple"Tags>(Rooms/BaseRate,values:50 ; Rooms/Type)"de cette section, où deux facettes enfants sont des pairs sous le parent Tags.
Remarquez que les parenthèses sont traitées avant l’imbrication et les opérations d'apposition : A > B ; C serait différent de A > (B ; C).
Il existe plusieurs exemples pour les hiérarchies de facettes. Le premier exemple est une requête qui retourne seulement quelques documents, ce qui est utile pour afficher une réponse complète. Les facettes comptent le document parent (Hôtels) et non les sous-documents intermédiaires (Chambres), donc la réponse détermine le nombre d’hôtels qui possèdent des chambres dans chaque compartiment de facettes.
POST /indexes/hotels-sample/docs/search?api-version=2026-08-01-preview
{
"search": "ocean",
"facets": ["Address/StateProvince>Address/City", "Tags>Rooms/BaseRate,values:50"],
"select": "HotelName, Description, Tags, Address/StateProvince, Address/City",
"count": true
}
Les résultats de cette requête sont les suivants. Les deux hôtels ont des piscines. Dans le cas des autres, un seul hôtel fournit la commodité.
{
"@odata.count": 2,
"@search.facets": {
"Tags": [
{
"value": "pool",
"count": 2,
"@search.facets": {
"Rooms/BaseRate": [
{
"to": 50,
"count": 0
},
{
"from": 50,
"count": 2
}
]
}
},
{
"value": "air conditioning",
"count": 1,
"@search.facets": {
"Rooms/BaseRate": [
{
"to": 50,
"count": 0
},
{
"from": 50,
"count": 1
}
]
}
},
{
"value": "bar",
"count": 1,
"@search.facets": {
"Rooms/BaseRate": [
{
"to": 50,
"count": 0
},
{
"from": 50,
"count": 1
}
]
}
},
{
"value": "restaurant",
"count": 1,
"@search.facets": {
"Rooms/BaseRate": [
{
"to": 50,
"count": 0
},
{
"from": 50,
"count": 1
}
]
}
},
{
"value": "view",
"count": 1,
"@search.facets": {
"Rooms/BaseRate": [
{
"to": 50,
"count": 0
},
{
"from": 50,
"count": 1
}
]
}
}
],
"Address/StateProvince": [
{
"value": "FL",
"count": 1,
"@search.facets": {
"Address/City": [
{
"value": "Tampa",
"count": 1
}
]
}
},
{
"value": "HI",
"count": 1,
"@search.facets": {
"Address/City": [
{
"value": "Honolulu",
"count": 1
}
]
}
}
]
},
"value": [
{
"@search.score": 1.6076145,
"HotelName": "Ocean Water Resort & Spa",
"Description": "New Luxury Hotel for the vacation of a lifetime. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.",
"Tags": [
"view",
"pool",
"restaurant"
],
"Address": {
"City": "Tampa",
"StateProvince": "FL"
}
},
{
"@search.score": 1.0594962,
"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"
],
"Address": {
"City": "Honolulu",
"StateProvince": "HI"
}
}
]
}
Ce deuxième exemple étend le précédent, illustrant plusieurs facettes de niveau supérieur avec plusieurs enfants. Notez que l’opérateur point-virgule (;) sépare chaque enfant.
POST /indexes/hotels-sample/docs/search?api-version=2026-08-01-preview
{
"search": "+ocean",
"facets": ["Address/StateProvince > Address/City", "Tags > (Rooms/BaseRate,values:50 ; Rooms/Type)"],
"select": "HotelName, Description, Tags, Address/StateProvince, Address/City",
"count": true
}
Une réponse partielle, abrégée pour la concision, affiche des étiquettes contenant des facettes enfants pour le tarif de base et le type des chambres. Dans l'index de l'échantillon d'hôtels, les deux hôtels qui correspondent à +ocean, ont des chambres de chaque type et une piscine.
{
"@odata.count": 2,
"@search.facets": {
"Tags": [
{
"value": "pool",
"count": 2,
"@search.facets": {
"Rooms/BaseRate": [
{
"to": 50,
"count": 0
},
{
"from": 50,
"count": 2
}
],
"Rooms/Type": [
{
"value": "Budget Room",
"count": 2
},
{
"value": "Deluxe Room",
"count": 2
},
{
"value": "Standard Room",
"count": 2
},
{
"value": "Suite",
"count": 2
}
]
}}]},
...
}
Ce dernier exemple montre les règles de précédence pour les parenthèses qui affectent les niveaux d’imbrication. Supposons que vous souhaitez retourner une hiérarchie de facettes dans cet ordre.
Address/StateProvince
Address/City
Category
Rating
Pour retourner cette hiérarchie, créez une requête dans laquelle la catégorie et l’évaluation sont frères sous Adresse/Ville.
{
"search": "beach",
"facets": [
"Address/StateProvince > (Address/City > (Category ; Rating))"
],
"select": "HotelName, Description, Tags, Address/StateProvince, Address/City",
"count": true
}
Si vous supprimez les parenthèses les plus proches, La catégorie et l’évaluation ne sont plus frères, car les règles de précédence signifient que l’opérateur > est évalué avant ;.
{
"search": "beach",
"facets": [
"Address/StateProvince > (Address/City > Category ; Rating)"
],
"select": "HotelName, Description, Tags, Address/StateProvince, Address/City",
"count": true
}
Le parent de niveau supérieur est toujours Address/StateProvince, mais maintenant Address/City et Rating sont au même niveau.
Address/StateProvince
Rating
Address/City
Category
Exemple de filtrage de facettes (préversion)
À l’aide de l’API REST version la plus récente ou du portail Azure, vous pouvez configurer des filtres de facettes.
Le filtrage de facettes vous permet de limiter les valeurs de facette retournées à celles correspondant à une expression régulière spécifiée. Deux nouveaux paramètres acceptent une expression régulière appliquée au champ de facette :
-
includeTermFilterfiltre les valeurs de facette pour celles qui correspondent à l’expression régulière -
excludeTermFilterfiltre les valeurs de facette sur celles qui ne correspondent pas à l’expression régulière
Si une chaîne de facette satisfait aux deux conditions, le excludeTermFilter prend la priorité parce que l'ensemble des chaînes de seaux est d'abord évalué avec includeTermFilter puis exclu avec excludeTermFilter.
Seules les valeurs de facette qui correspondent à l’expression régulière sont retournées. Vous pouvez combiner ces paramètres avec d’autres options de facette (par exemple, count, sortet facette hiérarchique) sur les champs de chaîne.
Étant donné que l’expression régulière est imbriquée dans une valeur de chaîne JSON, vous devez échapper les guillemets doubles (") et les caractères de barre oblique inverse (\). L’expression régulière elle-même est délimitée par la barre oblique (/). Pour plus d’informations sur les modèles d’échappement, consultez la recherche d’expressions régulières.
L’exemple suivant montre comment échapper des caractères spéciaux dans votre expression régulière, comme une barre oblique inverse, des guillemets doubles ou des caractères de syntaxe d’expression régulière.
{
"search": "*",
"facets": ["name,includeTermFilter:/EscapeBackslash\\\OrDoubleQuote\\"OrRegexCharacter\\(/"]
}
Voici un exemple de filtre à facettes qui s'applique aux hôtels économiques et aux hôtels de long séjour, avec l'évaluation en tant que sous-catégorie de chaque catégorie d'hôtel.
POST /indexes/hotels-sample/docs/search?api-version=2026-08-01-preview
{
"search": "*",
"facets": ["(Category,includeTermFilter:/(Budget|Extended-Stay)/)>Rating,values:1|2|3|4|5"],
"select": "HotelName, Category, Rating",
"count": true
}
L’exemple suivant est une réponse abrégée (les documents d’hôtel sont omis pour la concision).
{
"@odata.count": 50,
"@search.facets": {
"Category": [
{
"value": "Budget",
"count": 13,
"@search.facets": {
"Rating": [
{
"to": 1,
"count": 0
},
{
"from": 1,
"to": 2,
"count": 0
},
{
"from": 2,
"to": 3,
"count": 4
},
{
"from": 3,
"to": 4,
"count": 5
},
{
"from": 4,
"to": 5,
"count": 4
},
{
"from": 5,
"count": 0
}
]
}
},
{
"value": "Extended-Stay",
"count": 6,
"@search.facets": {
"Rating": [
{
"to": 1,
"count": 0
},
{
"from": 1,
"to": 2,
"count": 0
},
{
"from": 2,
"to": 3,
"count": 4
},
{
"from": 3,
"to": 4,
"count": 1
},
{
"from": 4,
"to": 5,
"count": 1
},
{
"from": 5,
"count": 0
}
]
}
}
]
},
"value": [ ALL 50 HOTELS APPEAR HERE ]
}
Exemple d’agrégation de facettes (version préliminaire)
À l’aide de l’API REST version la plus récente ou du portail Azure, vous pouvez agréger des facettes.
Les agrégations de facettes vous permettent de calculer des métriques à partir de valeurs de facette. La fonctionnalité d’agrégation fonctionne en même temps que les options de facette existantes.
| Agrégateur | Description |
|---|---|
| Somme | Retourne la valeur cumulée totale du champ sur tous les documents. S’applique uniquement aux types numériques. Était pris en charge dans les versions préliminaires antérieures. |
| Min | Retourne la valeur minimale du champ dans tous les documents. S’applique uniquement aux types numériques. |
| Max | Retourne la valeur maximale du champ dans tous les documents. S’applique uniquement aux types numériques. |
| Moy. | Retourne la valeur moyenne du champ dans tous les documents. S’applique uniquement aux types numériques. |
| Cardinalité | Retourne le nombre approximatif de valeurs distinctes du champ dans tous les documents à l’aide de l’algorithme HyperLogLog. Vous pouvez effectuer des requêtes cardinality sur les champs à facettes, y compris les champs de type chaîne et date/heure (ainsi que leurs formulaires de collection correspondants). |
Définition de seuils de précision pour l’agrégation de cardinalité
Sur une agrégation de cardinalité, vous pouvez définir une precisionThreshold option en tant que démarcation entre les nombres qui sont censés être proches de la précision et les nombres qui peuvent être moins précis. La valeur maximale est de 40 000. La valeur par défaut est 3 000.
L'opération de facettage est effectuée en mémoire. Augmenter la valeur de precisionThreshold entraîne une consommation de mémoire plus élevée (la valeur precisionThreshold multipliée par 8 octets).
Exemple : Agrégation de facettes de somme
Vous pouvez additionner n’importe quel champ facetable d’un type de données numérique (à l’exception des vecteurs et des coordonnées géographiques).
Voici un exemple utilisant l’index hotels-sample. Le champ Rooms/SleepsCount est à facettes et numérique, c'est pourquoi nous choisissons ce champ pour démontrer la fonction de somme. Si nous ajoutons ce champ, nous obtenons le nombre de nuits pour l’ensemble de l’hôtel. Rappelez-vous que les facettes comptent le document parent (Hôtels) et non les sous-documents intermédiaires (Chambres), de sorte que la réponse additionne le SleepsCount de toutes les chambres pour l’ensemble de l’hôtel. Dans cette requête, nous ajoutons un filtre pour additionner le SleepsCount pour un seul hôtel.
POST /indexes/hotels-sample/docs/search?api-version=2026-08-01-preview
{
"search": "*",
"filter": "HotelId eq '41'",
"facets": [ "Rooms/SleepsCount, metric: sum"],
"select": "HotelId, HotelName, Rooms/Type, Rooms/SleepsCount",
"count": true
}
Une réponse pour la requête peut ressembler à l’exemple suivant. Windy Ocean Model peut accueillir un total de 40 invités.
{
"@odata.count": 1,
"@search.facets": {
"Rooms/SleepsCount": [
{
"sum": 40.0
}
]
},
"value": [
{
"@search.score": 1.0,
"HotelId": "41",
"HotelName": "Windy Ocean Motel",
"Rooms": [
{
"Type": "Suite",
"SleepsCount": 4
},
{
"Type": "Deluxe Room",
"SleepsCount": 2
},
{
"Type": "Budget Room",
"SleepsCount": 2
},
{
"Type": "Budget Room",
"SleepsCount": 2
},
{
"Type": "Suite",
"SleepsCount": 2
},
{
"Type": "Standard Room",
"SleepsCount": 2
},
{
"Type": "Deluxe Room",
"SleepsCount": 2
},
{
"Type": "Suite",
"SleepsCount": 2
},
{
"Type": "Suite",
"SleepsCount": 4
},
{
"Type": "Standard Room",
"SleepsCount": 4
},
{
"Type": "Standard Room",
"SleepsCount": 2
},
{
"Type": "Deluxe Room",
"SleepsCount": 2
},
{
"Type": "Suite",
"SleepsCount": 2
},
{
"Type": "Standard Room",
"SleepsCount": 2
},
{
"Type": "Deluxe Room",
"SleepsCount": 2
},
{
"Type": "Deluxe Room",
"SleepsCount": 2
},
{
"Type": "Standard Room",
"SleepsCount": 2
}
]
}
]
}
Exemple : composite de toutes les agrégations
Voici un exemple utilisant un index hypothétique « facettes » qui affiche la syntaxe de chaque agrégation. Notez que la cardinalité a une option supplémentaire precisionThreshold (la valeur par défaut est 3 000) définie sur 40 000 dans cet exemple.
POST https://search-service.search.windows.net/indexes/facets/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{token}}
Content-Type: application/json
{
"search": "*",
"facets": [// field names are named <something>Value in this example
"cardinalityValue, metric: cardinality,precisionThreshold: 40000",
"sumValue,metric: sum",
"avgValue,metric: avg",
"minValue,metric: min",
"maxValue,metric: max"
]
}
Une réponse pour la requête peut ressembler à l’exemple suivant.
{
"@search.facets": {
"cardinalityValue": [
{
"cardinality": 24000 // Number of distinct values in "cardinalityValue" field
}
],
"sumValue": [
{
"sum": 1200000 // Sum of all values in "sumValue" field
}
],
"avgValue": [
{
"avg": 50 // Average of all values in "avgValue" field
}
],
"minValue": [
{
"min": 1 // Minimum value in "minValue" field
}
],
"maxValue": [
{
"max": 100 // Maximum value in "maxValue" field
}
]
}
}
Exemple : Spécifier une valeur par défaut pour remplacer les valeurs manquantes
Toutes les métriques prennent en charge la spécification d’une valeur par défaut lorsqu’un document ne contient pas de valeur.
Pour les types non chaînes (numérique, datetime, booléen), définissez le
defaultparamètre sur une valeur spécifique :"default: 42".Pour les types de chaînes, définissez le
defaultparamètre sur une chaîne délimitée à l’aide du délimiteur apostrophe unique :"default: 'mystringhere'".
Vous pouvez ajouter une valeur par défaut à utiliser si un document contient une valeur Null pour ce champ : "facets": [ "Rooms/SleepsCount, metric: sum, default:2"]. Si une chambre a une valeur Null pour le champ Rooms/SleepsCount, la valeur par défaut remplace la valeur manquante.
Voici une requête qui illustre la spécification par défaut pour chaque type de champ.
POST https://search-service.search.windows.net/indexes/facets/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{token}}
Content-Type: application/json
{
"search": "*",
"facets": [// field names are named <datatype>Value in this example
"stringfield, metric: cardinality, default: 'my string goes here'",
"doubleField,metric: sum, default: 5.0",
"intField,metric: sum, default: 5",
"longField,metric: sum, default: 5"
]
}
Pour les champs de chaîne, une valeur par défaut est délimitée à l’aide du caractère guillemet unique. Pour échapper au caractère, préfixez-le avec la barre oblique inversée « ' ». Tous les caractères sont valides dans les délimiteurs de chaîne. Le caractère terminal ne doit pas être une barre oblique inverse.
Exemple : Plusieurs métriques sur le même champ
Si les données sous-jacentes prennent en charge le cas d’usage, vous pouvez spécifier plusieurs métriques sur le même champ.
POST https://search-service.search.windows.net/indexes/facets/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{token}}
Content-Type: application/json
{
"search": "*",
"facets": [
"fieldA, metric: cardinality, precisionThreshold: 40000",
"fieldA, metric: sum",
"fieldA, metric: avg",
"fieldA, metric: min",
"fieldA, metric: max"
]
}
Une réponse pour la requête peut ressembler à l’exemple suivant.
{
"@search.facets": {
"fieldA": [
{
"cardinality": 24000 // Number of distinct values in "fieldA" field
},
{
"sum": 1200000 // Sum of all values in " fieldA " field
},
{
"avg": 5 // Avg of all values in " fieldA " field
},
{
"min": 0 // Min of all values in " fieldA " field
},
{
"max": 1200 // Max of all values in " fieldA " field
}
]
}
}
Étapes suivantes
Revisitez la configuration de navigation par facettes pour les outils et les API, puis passez en revue les meilleures pratiques pour l’utilisation des facettes dans le code.
Nous vous recommandons C#: Ajouter la recherche aux applications web pour obtenir un exemple de navigation à facettes qui inclut du code pour la couche de présentation. L’exemple inclut également des filtres, des suggestions et la saisie semi-automatique. Il utilise JavaScript et React pour la couche de présentation.