Affinement d’une requête dans SharePoint
Apprenez à utiliser les fonctionnalités d’affinement des requêtes SharePoint par programme dans les requêtes de recherche et les résultats.
Vous pouvez utiliser les fonctionnalités d’affinement des requêtes pour fournir aux utilisateurs finaux des options d’affinement qui sont pertinentes pour leurs requêtes. Ces fonctionnalités permettent à l’utilisateur final d’analyser en détail les résultats de la recherche en utilisant des données d’affinement calculées pour les résultats. Les données d’affinement sont calculées par le composant d’index, en fonction de l’agrégation des statistiques de propriétés gérées pour tous les résultats d’une requête de recherche.
L'affinement de requêtes est généralement utilisé pour les métadonnées associées aux éléments indexés, comme la date de création, l'auteur ou les types de fichier qui apparaissent dans l'élément. Grâce aux options d’affinement, vous pouvez affiner votre requête pour ne présenter que les éléments créés sur une période donnée ou afficher uniquement les éléments d’un certain type de fichier.
Utilisation des affinements dans le modèle objet requête
Il existe deux requêtes impliquées dans l'affinement de requête :
- Vous pouvez demander qu’un ensemble d’affinements soit retourné dans les résultats de la recherche en ajoutant une spécification d’affinement à la requête de l’utilisateur final. Une spécification d'affinement est l'entrée de la propriété Refiners . Cette requête est exécutée sur l'index de recherche. Les résultats de la recherche seront composés de résultats pertinents et de données d'affinement.
- Vous pouvez utiliser les données d’affinement pour affiner les résultats de la recherche en créant une requête affinée. Ajoutez la propriété RefinementFilters à la requête afin que les résultats finaux de la recherche répondent aux exigences du texte de la requête d’origine de l’utilisateur final et de l’option d’affinement sélectionnée à partir des données d’affinement.
Les sections suivantes décrivent ces étapes en détail et fournissent des exemples de code.
Ajout d'affinements à la requête de l'utilisateur final à l'aide des spécifications d'affinement
Vous pouvez spécifier les affinements de requête demandés à l’aide de la propriété Refiners de la classe KeywordQuery . Pour spécifier les affinements de requête demandés, utilisez la syntaxe suivante :
<refiner>[,<refiner>]*
Chaque affinement (« refiner ») présente le format suivant :
<refiner-name>[(parameter=value[,parameter=value]*)]?
Où :
<refiner-name>est le nom de la propriété gérée associée à l'affinement. Cette propriété gérée doit être définie sur Refinable ou Sortable dans le schéma de recherche.- La liste facultative de paires
parameter=valuespécifie des valeurs de configuration non définies par défaut pour l'affinement nommé. Si un paramètre d'un affinement n'est pas répertorié dans les parenthèses, la configuration du schéma de recherche vous donne la valeur par défaut. Le tableau 1 répertorie les valeurs possibles pour les pairesparameter=value.
Remarque
Quand vous spécifiez des affinements, l’exigence minimale consiste à spécifier un nom d’affinement (« refiner-name »), qui prend la forme d’une propriété gérée.
Exemple
Refiners = "FileType"
Sinon, vous pouvez également utiliser la syntaxe avancée pour ajuster les paramètres d'affinement :
Refiners = "FileType,Write(discretize=manual/2013-01-01/2013-08-22/2013-09-15/2013-09-21/2013-09-22),companies"
Tableau 1 : Liste des paramètres pour les affinements
| Paramètre | Description |
|---|---|
| deephits |
Remplace le nombre d'accès par défaut qui est utilisé comme base pour le calcul des affinements. Lors de la production des affinements, tous les résultats de la requête seront évalués. Normalement, le fait d'utiliser ce paramètre améliorera les performances de recherche. Syntaxe deephits=<integer value> Exemple price(deephits=1000) Remarque : cette limite s’applique dans chaque partition d’index. Le nombre réel d’accès évalués sera supérieur à cette valeur en raison de l’agrégation entre les partitions de recherche. |
| discretize |
Spécifie les intervalles personnalisés (bacs d’affinement) pour les affinements numériques. Syntaxe discretize=manual/<threshold>/<threshold>[/<threshold>]* Exemple write(discretize=manual/2013-01-01/2013-08-22/2013-09-15/2013-09-21/2013-09-22) L’attribut <threshold> spécifie le seuil pour chaque bac d’affinement. Un seul intervalle est appliqué à l'ensemble des éléments sous le premier seuil spécifié, entre chaque seuil consécutif et pour l'ensemble des éléments au-dessus du dernier seuil. Pour un affinement de type DateTime, spécifiez le seuil en fonction de l'un des formats conformes à la norme ISO 8601 suivants :
|
| sort |
Définit la manière de trier les bacs dans un affinement de chaîne. Syntaxe sort=<property>/<direction> Les attributs effectuent les opérations suivantes :
sort=name/ascending Valeur par défaut : frequency/descending |
| filter |
Définit comment les bacs au sein d’un affinement de type String sont filtrés avant d’être renvoyés au client. Syntaxe filter=<bins>/<freq>/<prefix>[<levels>] Les attributs effectuent les opérations suivantes :
|
| cutoff |
Limite les données qui doivent être transférées et traitées pour les affinements de chaîne en profondeur. Vous pouvez configurer les affinements pour renvoyer uniquement les valeurs les plus pertinentes (bacs). Remarque : ce filtrage de coupure est effectué dans chaque partition d’index. Cela diffère du paramètre filter qui effectue un filtrage des résultats uniquement. Vous pouvez combiner les deux paramètres. Syntaxe cutoff=<frequency>/<minbins>/<maxbins> Les attributs effectuent les opérations suivantes :
|
Exemple : ajouter des affinements
L'exemple de modèle objet client suivant montre comment demander par programme trois affinements : FileType, Write et Companies. Write représente la date de dernière modification de l'élément et utilise la syntaxe avancée pour renvoyer les bacs de date/heure de taille fixe.
using (var context = new ClientContext("http://<serverName>/<siteCollectionPath>"))
{
var query = new KeywordQuery(context)
{
QueryText = "home",
Refiners = "FileType,Write(discretize=manual/2013-01-01/2013-08-22/2013-09-
15/2013-09-21/2013-09-22),companies"
};
var executor = new SearchExecutor(context);
var results = executor.ExecuteQuery(query);
context.ExecuteQuery();
ResultTable relevantResultsTable = results.Value[0];
ResultTable refinerResultsTable = results.Value[1];
Console.WriteLine(refinerResultsTable.RowCount + " refinement options:");
foreach (var refinementOption in refinerResultsTable.ResultRows)
{
Console.WriteLine("RefinerName: '{0}' RefinementName: '{1}'
RefinementValue: '{2}' RefinementToken: '{3}' RefinementCount: '{4}'",
refinementOption["RefinerName"],
refinementOption["RefinementName"],
refinementOption["RefinementValue"],
refinementOption["RefinementToken"],
refinementOption["RefinementCount"]
);
}
}
Explication des données d'affinement que vous obtenez dans le résultat de la recherche
Si vous avez activé l’affinement de requête pour une propriété managée dans votre requête, le résultat de la requête contient des données d’affinement divisées en bacs d’affinement. Ces données se trouvent dans la table RefinementResults ( RefinementResults ) dans resultTableCollection . Un compartiment d’affinement représente une valeur ou une plage de valeurs spécifique pour la propriété managée. La table RefinementResults contient une ligne par bac d’affinement et contient les colonnes, comme spécifié dans le tableau 2.
Tableau 2 : données renvoyées pour les bacs d’affinement
| Paramètre | Description |
|---|---|
| RefinerName | Nom de l'affinement de requête. |
| RefinementName | Chaîne qui représente le bac d'affinement. Cette chaîne est généralement utilisée lorsque vous présentez les options d'affinement aux utilisateurs sur une page de résultats de recherche. |
| RefinementValue | Chaîne mise en forme en fonction de l'implémentation et qui représente l'affinement. Ces données sont renvoyées pour le débogage et ne sont généralement pas requises pour le client. |
| RefinementToken | Une chaîne qui représente le bac d'affinement à utiliser avec RefinerName lorsque vous effectuez une requête affinée. |
| RefinementCount | Nombre de résultats pour ce bac d'affinement. Ces données représentent le nombre d’éléments (y compris les doublons) dans le résultat de la recherche avec une valeur pour la propriété gérée donnée qui correspond à ce bac d’affinement. |
Exemple : données d'affinement
Le tableau 3 ci-dessous contient deux lignes de données d'affinement. La première ligne présente les données d'affinement pour les éléments indexés, où le type de fichier est HTML. La deuxième ligne présente les données d’affinement pour les éléments indexés, où les heures de dernière modification s’échelonnent du 21/09/2013 au 22/09/2013.
Tableau 3 : format et contenu des données d’affinement
| RefinerName | RefinementName | RefinementValue | RefinementToken | RefinementCount |
|---|---|---|---|---|
| FileType | Html | Html | "????68746d6c" | 50553 |
| Écriture | De 2013-09-21T00:00:00Z à 2013-09-22T00:00:00Z | De 2013-09-21T00:00:00Z à 2013-09-22T00:00:00Z | range(2013-09-21T00:00:00Z, 2013-09-22T00:00:00Z) | 37 |
Création d'une requête affinée
Un résultat de recherche présente des options d'affinement sous la forme de valeurs de chaîne ou de plages de valeurs. Chaque plage de valeurs numériques ou valeur de chaîne est appelée bac d'affinement, et chaque bac d'affinement est associé à une valeur RefinementToken. Une option d'affinement est associée à une propriété gérée, qui est fournie par la valeur RefinerName.
Les valeurs RefinementToken et RefinerName sont toutes deux concaténées pour créer une chaîne refinement filter. Cette chaîne représente un filtre qui peut être utilisé pour limiter les éléments de résultat de recherche et n'inclure que les éléments où une propriété gérée a une valeur comprise dans un bac d'affinement. Pour résumer :
refinement filter = <RefinerName>:<RefinementToken>
Vous pouvez fournir un ou plusieurs filtres d’affinement pour une requête affinée en ajoutant des filtres d’affinement à la propriété RefinementFilters de la classe KeywordQuery . Plusieurs filtres d'affinement permettent de fournir un affinement à plusieurs niveaux dans les résultats de recherche et d'appliquer l'affinement sur des propriétés à valeurs multiples. Par exemple, vous pouvez affiner la requête pour qu’elle ne renvoie que les éléments qui ont deux auteurs précis (chacun étant représenté par un bac d’affinement) mais exclure les éléments qui n’ont que l’un des deux auteurs.
Exemple 1 : création d’une requête affinée pour des types de fichiers HTML
L’exemple CSOM suivant décrit comment effectuer un affinement par programme, pour limiter les résultats de la recherche au type de fichier HTML uniquement. Comme mentionné dans Exemple : Données d’affinement, les données d’affinement associées à cette option d’affinement ont RefinerName défini sur Filetype et RefinementToken défini sur « ???? 68746d6c ».
using (var context = new ClientContext("http://<serverName>/<siteCollectionPath>"))
{
var query = new KeywordQuery(context)
{
QueryText = "home"
};
query.RefinementFilters.Add("FileType:\\"????68746d6c\\"");
var executor = new SearchExecutor(context);
var results = executor.ExecuteQuery(query);
context.ExecuteQuery();
ResultTable relevantResultsTable = results.Value[0];
var resultCount = 1;
foreach (var relevantResult in relevantResultsTable.ResultRows)
{
Console.WriteLine("Relevant result number {0} has file type {1}.",
resultCount, relevantResult["FileType"]);
resultCount++;
}
}
Exemple 2 : création d’une requête affinée à l’aide des données d’affinement obtenues précédemment
L'exemple de modèle objet client suivant montre comment exécuter une requête avec une spécification d'affinement pour créer des données d'affinement qui sont ensuite utilisées pour exécuter l'affinement. Cet exemple simule le processus d'un utilisateur final qui sélectionne la première option d'affinement.
using (var context = new ClientContext("http://<serverName>/<siteCollectionPath>"))
{
// Step 1: Run the query with refiner spec to provide refinement data in search result
var query = new KeywordQuery(context)
{
QueryText = "home",
Refiners = "FileType,Write(discretize=manual/2013-01-01/2013-08-22/2013-09-15/2013-09-21/2013-09-22),companies"
};
Console.WriteLine("Run query '{0}' with refiner spec '{1}'.", query.QueryText, query.Refiners);
var executor = new SearchExecutor(context);
var results = executor.ExecuteQuery(query);
context.ExecuteQuery();
// The query has been run and we can now look at the refinement data, to view the
// refinement options
ResultTable relevantResultsTable = results.Value[0];
ResultTable refinerResultsTable = results.Value[1];
Console.WriteLine("Got back {0} refinement options in the result:",
refinerResultsTable.RowCount);
foreach (var refinementOption in refinerResultsTable.ResultRows)
{
Console.WriteLine("RefinerName: '{0}' RefinementName: '{1}'
RefinementValue: '{2}' RefinementToken: '{3}' RefinementCount: '{4}'",
refinementOption["RefinerName"],
refinementOption["RefinementName"],
refinementOption["RefinementValue"],
refinementOption["RefinementToken"],
refinementOption["RefinementCount"]
);
}
// Step 2: Run the refined query with refinement filter to drill down into
// the search results. This example uses the first refinement option in the refinement
// data, if available. This simulates an end user selecting this refinement option.
var refinementOptionArray = refinerResultsTable.ResultRows.ToArray();
if (refinementOptionArray.Length > 0)
{
var firstRefinementOption = refinementOptionArray[6];
// Construct the refinement filter by concatenation
var refinementFilter = firstRefinementOption["RefinerName"] + ":" +
firstRefinementOption["RefinementToken"];
var refinedQuery = new KeywordQuery(context)
{
QueryText = query.QueryText
};
refinedQuery.RefinementFilters.Add(refinementFilter);
refinedQuery.SelectProperties.Add("FileType");
refinedQuery.SelectProperties.Add("Write");
refinedQuery.SelectProperties.Add("Companies");
Console.WriteLine("Run query '{0}' with refinement filter '{1}'",
refinedQuery.QueryText, refinementFilter);
var refinedResults = executor.ExecuteQuery(refinedQuery);
context.ExecuteQuery();
ResultTable refinedRelevantResultsTable = refinedResults.Value[0];
var resultCount = 1;
foreach (var relevantResult in refinedRelevantResultsTable.ResultRows)
{
Console.WriteLine("Relevant result number {0} has FileType='{1}',
Write='{2}', Companies='{3}'",
resultCount,
relevantResult["FileType"],
relevantResult["Write"],
relevantResult["Companies"]
);
resultCount++;
}
}
}
Voir aussi
- Configurer les propriétés du composant WebPart d’affinement dans SharePoint
- Vue d’ensemble du schéma de recherche dans SharePoint