Bonnes pratiques en matière de requête et d’indexation query-and-indexing-best-practices

Dans AEM as a Cloud Service, tous les aspects opérationnels concernant l’indexation sont automatisés. Cela permet aux développeurs de se concentrer sur la création de requêtes efficaces et leurs définitions d’index correspondantes.

Quand utiliser des requêtes when-to-use-queries

Les requêtes sont un moyen d’accéder au contenu, mais elles ne sont pas la seule possibilité. Dans de nombreuses situations, l’accès au contenu du référentiel est plus efficace par d’autres moyens. Vous devez déterminer si les requêtes sont la meilleure manière, et la plus efficace, d’accéder au contenu pour votre cas d’utilisation.

Référentiel et conception de taxonomie repository-and-taxonomy-design

Lors de la conception de la taxonomie d’un référentiel, plusieurs facteurs doivent être pris en compte. Il s’agit entre autres des contrôles d’accès, de la localisation et de l’héritage des propriétés de composant et de page, et bien plus encore.

Lors de la conception d’une taxonomie qui tient compte de ces facteurs, il est également important de penser à la « traversabilité » de la conception de l’indexation. Dans ce contexte, la traversabilité est la capacité d’une taxonomie à permettre un accès prévisible au contenu en fonction de son chemin d’accès. Cela permet d’obtenir un système plus efficace, plus facile à gérer qu’un système nécessitant l’exécution de plusieurs requêtes.

De plus, lors de la conception d’une taxonomie, il est important de se demander si l’ordre importe. Dans les cas où un ordre explicite n’est pas nécessaire et qu’un grand nombre de nœuds frères est attendu, il est préférable d’utiliser un type de nœud non ordonné tel que sling:Folder ou oak:Unstructured. Dans les cas où un ordre est obligatoire, nt:unstructured et sling:OrderedFolder serait plus approprié.

Requêtes dans les composants queries-in-components

Comme les requêtes peuvent être l’une des opérations les plus contraignantes effectuées sur un système AEM, il est préférable de les éviter dans vos composants. L’exécution de plusieurs requêtes à chaque rendu de page peut souvent dégrader les performances du système. Deux stratégies sont conseillées pour éviter l’exécution de requêtes lors du rendu de composants : le parcours transversal des nœuds et la pré-récupération des résultats.

Parcours transversal des nœuds traversing-nodes

Si le référentiel est conçu de manière à permettre une connaissance préalable de l’emplacement des données requises, le code qui récupère ces données dans les chemins nécessaires peut être déployé sans avoir à exécuter de requêtes pour le trouver.

Par exemple, le rendu de contenu correspondant à une certaine catégorie. Une méthode consiste à organiser le contenu avec une propriété de catégorie qui peut être interrogée pour renseigner un composant qui affiche des éléments dans une catégorie.

Une meilleure approche serait de structurer ce contenu dans une taxonomie par catégorie afin qu’il puisse être récupéré manuellement.

Par exemple, si le contenu est stocké dans une taxonomie similaire à :

/content/myUnstructuredContent/parentCategory/childCategory/contentPiece

Le nœud /content/myUnstructuredContent/parentCategory/childCategory peut simplement être récupéré ; ses tâches enfants peuvent être analysées et utilisées pour le rendu du composant.

En outre, lorsque vous traitez un ensemble de résultats petit ou homogène, il peut être plus rapide de parcourir le référentiel et de rassembler les nœuds requis, plutôt que de concevoir une requête pour renvoyer le même ensemble de résultats. En règle générale, les requêtes doivent être évitées lorsque cela est possible.

Prérécupération des résultats prefetching-results

Parfois, le contenu ou les exigences liées à un composant ne permettent pas d’utiliser le parcours transversal des nœuds comme méthode de récupération des données requises. Dans ce cas, les requêtes requises doivent être exécutées avant le rendu du composant afin que des performances optimales soient garanties.

Si les résultats requis pour le composant peuvent être calculés au moment de sa création et qu’aucun changement de contenu n’est attendu, la requête peut être exécutée après que des modifications soient effectuées.

Si les données ou le contenu changent régulièrement, la requête peut être exécutée selon un planning ou via un listener pour la mise à jour des données sous-jacentes. Ensuite, les résultats peuvent être écrits à un emplacement partagé dans le référentiel. Tous les composants qui ont besoin de ces données peuvent ensuite extraire les valeurs de ce nœud unique sans avoir à exécuter une requête lors de l’exécution.

Une stratégie similaire peut être utilisée pour conserver le résultat dans un cache en mémoire, qui est renseigné au démarrage et mis à jour chaque fois que des modifications sont effectuées (à l’aide d’un JCR ObservationListenerou d’un SlingResourceChangeListener).

Optimiser les requêtes optimizing-queries

La documentation d’Oak fournit une présentation générale de l’exécution des requêtes. C’est la base de toutes les activités d’optimisation décrites dans ce document.

AEM as a Cloud Service fournit l’outil Query Performance Tool, conçu pour prendre en charge l’implémentation de requêtes efficaces.

L’outil de performance de requête est accessible via Developer Console dans Cloud Manager. L’outil de performance de requête d’AEM as a Cloud Service fournit plus d’informations sur les détails de l’exécution de la requête à partir de la version AEM 6.x.

Ce graphique illustre le flux général d’utilisation de l’outil de performance des requêtes pour optimiser les requêtes.

Utiliser un index use-an-index

Chaque requête doit utiliser un index pour fournir des performances optimales. Dans la plupart des cas, les index prêts à l’emploi existants doivent être suffisants pour gérer les requêtes.

Il arrive que des propriétés personnalisées doivent être ajoutées à un index existant, de sorte que des contraintes supplémentaires puissent être interrogées à l’aide de l’index. Consultez le document Recherche et indexation de contenu pour en savoir plus. La section Aide-mémoire pour les requêtes JCR de ce document décrit l’aspect que doit prendre une définition de propriété sur un index pour prendre en charge un type de requête spécifique.

Utiliser les critères appropriés use-the-right-criteria

La contrainte principale sur toute requête doit être une correspondance de propriété, car il s’agit du type le plus efficace. L’ajout d’autres contraintes de propriété limite davantage le résultat.

Le moteur de requête ne prend en compte qu’un seul index. Cela signifie qu’un index existant peut et doit être personnalisé en y ajoutant d’autres propriétés d’index personnalisées.

La section Aide-mémoire pour les requêtes JCRde ce document répertorie les contraintes disponibles et décrit également à quoi doit ressembler une définition d’index pour être récupérée. Utilisez l’outil Performances des requêtes pour tester la requête et vous assurer que l’index approprié est utilisé et que le moteur de requête n’a pas besoin d’évaluer les contraintes en dehors de l’index.

Commande ordering

Si une commande spécifique du résultat est demandée, le moteur de requête peut effectuer deux opérations :

Limiter la taille du résultat restrict-result-size

La taille récupérée du résultat de la requête est un facteur important dans les performances de la requête. Comme la récupération du résultat est différée, il y a une différence dans la simple récupération des 20 premiers résultats par rapport à la récupération de 10 000 résultats, tant dans l’exécution que dans l’utilisation de la mémoire.

Cela signifie également que la taille du jeu de résultats ne peut être déterminée correctement que si tous les résultats sont récupérés. Pour cette raison, l’ensemble des résultats récupérés doit toujours être limité, soit en augmentant la requête (voir la section Aide-mémoire pour les requêtes JCR pour plus de détails) ou en limitant la lecture des résultats.

Une telle limite empêche également le moteur de requête de consulter la limite de traversée de 100 000 nœuds, ce qui entraîne un arrêt forcé de la requête.

Reportez-vous à la section Requêtes avec des jeux de résultats volumineux de ce document si un jeu de résultats potentiellement volumineux doit être complètement traité.

Outil de performance de requête query-performance-tool

L’outil de performance de requête (situé à l’adresse /libs/granite/operations/content/diagnosistools/queryPerformance.html et disponible via le Developer Console dans Cloud Manager) fournit :

Les tableaux « Requêtes lentes » et « Requêtes populaires » incluent -

Ces tables permettent d’identifier les requêtes qui ne sont pas entièrement indexées (voir Utilisation d’un index ou qui lisent trop de nœuds (voir également Traversée de référentiel et Traversée d’index). Ces requêtes seront mises en évidence, avec les zones de préoccupation appropriées marquées en rouge.

L’option Reset Statistics est fournie pour supprimer toutes les statistiques existantes collectées dans les tableaux. Cela permet l’exécution d’une requête particulière (soit via l’application elle-même, soit via l’outil Expliquer la requête ) et l’analyse des statistiques d’exécution.

Expliquer la requête

L’outil Expliquer la requête permet aux développeurs et aux développeuses de comprendre le plan d’exécution de la requête (voir Lecture du plan d’exécution de la requête), y compris les détails de tout index utilisé lors de l’exécution de la requête. Vous pouvez l’utiliser pour comprendre l’efficacité de l’indexation d’une requête pour prédire ou analyser rétrospectivement ses performances.

Expliquer une requête

Pour expliquer une requête, procédez comme suit :

Fenêtre contextuelle d’explication de la requête query-explanation-popup

Après avoir sélectionné Explain, l’utilisateur voit s’afficher un pop-up décrivant le résultat de l’explication de la requête (et son exécution, si elle est sélectionnée).
Ce pop-up contient des détails sur -

Lecture du plan d'exécution des requêtes reading-query-execution-plan

Le plan d’exécution de requête contient tout ce qui est nécessaire pour prédire (ou expliquer) les performances d’une requête particulière. Comprenez l’efficacité de l’exécution de la requête en comparant les restrictions et l’ordre dans la requête JCR (ou Query Builder) d’origine à la requête exécutée dans l’index sous-jacent (Lucene, Elastic ou Property).

Considérez la requête suivante -

/jcr:root/content/dam//element(*, dam:Asset) [jcr:content/metadata/dc:title = "My Title"] order by jcr:created

…qui contient -

L’explication de cette requête génère le plan suivant : -

[dam:Asset] as [a] /* lucene:damAssetLucene-9(/oak:index/damAssetLucene-9) +:ancestors:/content/dam +jcr:content/metadata/dc:title:My Title ordering:[{ propertyName : jcr:created, propertyType : UNDEFINED, order : ASCENDING }] where ([a].[jcr:content/metadata/dc:title] = 'My Title') and (isdescendantnode([a], [/content/dam])) */

Dans ce plan, la section décrivant la requête exécutée dans l’index sous-jacent est -

lucene:damAssetLucene-9(/oak:index/damAssetLucene-9) +:ancestors:/content/dam +jcr:content/metadata/dc:title:My Title ordering:[{ propertyName : jcr:created, propertyType : UNDEFINED, order : ASCENDING }]

Cette section du plan stipule que :

Une telle requête est susceptible de fonctionner correctement, car les résultats renvoyés par la requête d’index ne seront pas filtrés davantage dans le moteur de requête (à l’exception du filtrage par contrôle d’accès). Cependant, il est toujours possible qu’une telle requête s’exécute lentement si les bonnes pratiques ne sont pas suivies (voir la section Traversée d’index ci-dessous).

En envisageant une autre requête -

/jcr:root/content/dam//element(*, dam:Asset) [jcr:content/metadata/myProperty = "My Property Value"] order by jcr:created

…qui contient -

L’explication de cette requête génère le plan suivant : -

[dam:Asset] as [a] /* lucene:damAssetLucene-9-custom-1(/oak:index/damAssetLucene-9-custom-1) :ancestors:/content/dam ordering:[{ propertyName : jcr:created, propertyType : UNDEFINED, order : ASCENDING }] where ([a].[jcr:content/metadata/myProperty] = 'My Property Value') and (isdescendantnode([a], [/content/dam])) */

Dans ce plan, la section décrivant la requête exécutée dans l’index sous-jacent est -

lucene:damAssetLucene-9(/oak:index/damAssetLucene-9) :ancestors:/content/dam ordering:[{ propertyName : jcr:created, propertyType : UNDEFINED, order : ASCENDING }]

Cette section du plan stipule que :

Ce plan d’exécution de requête entraîne la lecture de chaque ressource sous /content/dam à partir de l’index, puis son filtrage par le moteur de requête (qui inclut uniquement celles correspondant à la restriction de propriété non indexée dans le jeu de résultats).

Même si seul un petit pourcentage de ressources correspond au jcr:content/metadata/myProperty = "My Property Value" de restriction, la requête doit lire un grand nombre de nœuds pour (tenter de) remplir la « page » de résultats demandée. Cela peut se traduire par une requête peu performante, qui s’affichera comme ayant un score de Read Optimization faible dans l’outil Performance des requêtes) et peut entraîner des messages WARN indiquant qu’un grand nombre de nœuds est en cours de traversée (voir Traversée d’index).

Pour optimiser les performances de cette seconde requête, créez une version personnalisée de l’index damAssetLucene-9 (damAssetLucene-9-custom-1) et ajoutez la définition de propriété suivante :

"myProperty": {
  "jcr:primaryType": "nt:unstructured",
  "propertyIndex": true,
  "name": "jcr:content/metadata/myProperty"
}

Aide-mémoire sur les requêtes JCR jcr-query-cheatsheet

Pour prendre en charge la création de requêtes JCR et de définitions d’index efficaces, la section Aide-mémoire pour les requêtes JCR peut être téléchargée et utilisée comme référence pendant le développement.

Il contient des exemples de requêtes pour QueryBuilder, XPath et SQL-2, couvrant plusieurs scénarios qui se comportent différemment en termes de performances des requêtes. Il fournit également des recommandations sur la version ou la personnalisation d’index Oak. Le contenu de cet aide-mémoire s’applique à AEM as a Cloud Service ainsi qu’à la version 6.5 d’AEM.

Bonnes Pratiques Relatives À La Définition D’Index index-definition-best-practices

Vous trouverez ci-dessous quelques bonnes pratiques à prendre en compte lors de la définition ou de l’extension d’index.

Les vérifications automatisées du pipeline Cloud Manager appliqueront certaines des bonnes pratiques décrites ci-dessus.

Requêtes avec jeux de résultats volumineux queries-with-large-result-sets

Bien qu’il soit recommandé d’éviter les requêtes avec des jeux de résultats volumineux, il existe des cas valides où des jeux de résultats volumineux doivent être traités. Souvent la taille du résultat n’est pas connue à l’avance, certaines précautions doivent donc être prises pour rendre le traitement fiable.

Traversée de référentiel repository-traversal

Les requêtes qui traversent le référentiel n’utilisent pas d’index et se connectent avec un message similaire à ce qui suit.

28.06.2022 13:32:52.804 *WARN* [127.0.0.1 [1656415972414] POST /libs/settings/granite/operations/diagnosis/granite_queryperformance.explain.json HTTP/1.1] org.apache.jackrabbit.oak.plugins.index.Cursors$TraversingCursor Traversed 98000 nodes with filter Filter(query=select [jcr:path], [jcr:score], * from [nt:base] as a /* xpath: //* */, path=*) called by com.adobe.granite.queries.impl.explain.query.ExplainQueryServlet.getHeuristics; consider creating an index or changing the query

Grâce à ce fragment de code de journal, vous pouvez déterminer :

Grâce à ces informations, il est possible d’optimiser cette requête à l’aide des méthodes décrites dans la section Optimisation des requêtes de ce document.

Traversée d'index index-traversal

Les requêtes qui utilisent un index, mais qui lisent toujours un grand nombre de nœuds, sont consignées avec un message similaire au suivant (notez le terme Index-Traversed plutôt que Traversed).

05.10.2023 10:56:10.498 *WARN* [127.0.0.1 [1696502982443] POST /libs/settings/granite/operations/diagnosis/granite_queryperformance.explain.json HTTP/1.1] org.apache.jackrabbit.oak.plugins.index.search.spi.query.FulltextIndex$FulltextPathCursor Index-Traversed 60000 nodes with filter Filter(query=select [jcr:path], [jcr:score], * from [dam:Asset] as a where isdescendantnode(a, '/content/dam') order by [jcr:content/metadata/unindexedProperty] /* xpath: /jcr:root/content/dam//element(*, dam:Asset) order by jcr:content/metadata/unindexedProperty */, path=/content/dam//*)

Cela peut se produire pour plusieurs raisons :