查询和索引最佳实践 query-and-indexing-best-practices

在 AEM as a Cloud Service 中，有关索引的所有操作方面都是自动化的。这使开发人员能够专注于创建高效的查询及其相应的索引定义。

何时使用查询 when-to-use-queries

查询是访问内容的一种方式，但不是唯一可用的方法。在许多情况下，可以通过其他方式更有效地访问存储库中的内容。您应该考虑查询是否是访问用例内容的最佳和最有效的方式。

存储库和分类设计 repository-and-taxonomy-design

在设计存储库的分类时，需要考虑几个因素。其中包括访问控制、本地化、组件和页面属性继承等。

在设计涵盖这些方面的分类法时，考虑索引设计的“可通行性”也很重要。在这种情况下，可通行性是分类法允许基于其路径以可预测地方式访问内容的能力。这样的系统比需要执行多个查询的系统更有效、容易维护。

此外，在设计分类法时，考虑排序是否重要也很重要。 如果不需要显式排序，并且需要大量同级节点，则最好使用无序节点类型，如sling:Folder或oak:Unstructured。在需要排序的情况下，nt:unstructured 和 sling:OrderedFolder 更合适。

组件中的查询 queries-in-components

由于查询可能是在 AEM 系统上执行的最繁重的操作之一，因此最好在组件中避免查询。每次呈现页面时执行多个查询通常会降低系统的性能。有两种策略可用于在呈现组件时避免执行查询：遍历节点 ​和​ 预取结果。

遍历节点 traversing-nodes

如果存储库的设计允许事先了解所需数据的位置，则可以部署从必要路径检索此数据的代码，而无需运行查询来查找它。

这方面的一个例子是呈现适合特定类别的内容。一种方法是使用类别属性组织内容，并且可以通过查询该属性来填充显示类别中项目的组件。

更好的方法是按类别通过分类法构造此内容，以便可以手动检索。

例如，如果内容存储在类似于以下的分类法中：

/content/myUnstructuredContent/parentCategory/childCategory/contentPiece

可以简单地检索 /content/myUnstructuredContent/parentCategory/childCategory 节点，解析其子节点并用于呈现组件。

此外，当您处理一个小的或同质的结果集时，遍历存储库并收集所需的节点会比通过手工创建查询来返回相同的结果集更快。 作为一般考虑，应尽可能避免查询。

预取结果 prefetching-results

有时，组件周围的内容或需求不允许使用节点遍历作为检索所需数据的方法。在这种情况下，需要在呈现组件之前执行所需的查询，以确保最佳性能。

如果可以在编写组件时计算组件所需的结果，并且预期内容不会更改，则可以在完成更改后执行查询。

如果数据或内容会定期更改，则可以按计划或通过侦听器执行查询，以更新基础数据。然后，可以将结果写入存储库中的共享位置。任何需要此数据的组件都可以从该单个节点提取值，而无需在运行时执行查询。

类似的策略可用于将结果保存在内存缓存中，该缓存在启动时会被填充，并会在进行更改时更新（使用 JCR ObservationListener 或 Sling ResourceChangeListener）。

优化查询 optimizing-queries

Oak 文档提供了如何执行查询的高级概述。这是本文件所述所有优化活动的基础。

AEM as a Cloud Service提供了查询性能工具，该工具旨在支持实现高效的查询。

查询性能工具可通过云管理器中的开发者控制台访问。与 AEM 6.x 版本相比，AEM as a Cloud Service 的查询性能工具可提供更多有关查询执行细节的信息。

此图表说明了使用查询性能工具优化查询的一般流程。

使用索引 use-an-index

每个查询都应该使用索引来提供最佳性能。在大多数情况下，现有的开箱即用的索引应足以处理查询。

有时需要将自定义属性添加到现有索引中，以使用该索引查询其他约束。有关详细信息，请参阅文档内容搜索和索引。本文档的JCR查询备忘表部分描述了索引上的属性定义必须如何支持特定的查询类型。

使用正确的标准 use-the-right-criteria

任何查询的主要约束都应该是一种属性匹配，因为这是最有效的类型。添加更多属性约束会进一步限制结果。

查询引擎只考虑单个索引。这意味着可以并且应该通过向现有索引添加更多自定义索引属性来对其进行自定义。

本文档的JCR查询备忘表部分列出了可用的约束，并概述了索引定义的外观必须如何，才能选取它。 使用查询性能工具测试查询并确保使用了正确的索引，并且查询引擎不需要评估索引之外的约束。

排序 ordering

如果请求的是结果的特定顺序，那么查询引擎可以通过两种方式实现这种排序：

限制结果大小 restrict-result-size

查询结果的检索大小是查询性能的一个重要因素。由于结果是以延迟方式获取的，因此在运行时和内存使用方面，仅获取前 20 个结果与获取 10000 个结果是不同的。

这也意味着，只有在获取所有结果的情况下，才能正确确定结果集的大小。因此，请务必限制获取的结果集，要么通过增加查询（详见本文档的 JCR 查询备忘表部分），要么通过限制结果的读取来进行限制。

这样的限制还可以防止查询引擎达到 100000 个节点的​ 遍历限制，这会导致强制停止查询。

如果必须完全处理潜在的大型结果集，请参阅本文档的包含大型结果集的查询部分。

查询性能工具 query-performance-tool

查询性能工具(位于/libs/granite/operations/content/diagnosistools/queryPerformance.html，可通过Cloud Manager🔗中的Developer Console使用)提供 —

“慢查询”和“常用查询”表包括 —

这些表可帮助识别未完全编制索引的查询(请参阅使用索引或读取的节点过多（另请参阅存储库遍历和索引遍历）。 此类查询将突出显示，并将相应的关注领域标示为红色。

提供了Reset Statistics选项以删除表中收集的所有现有统计信息。 这允许执行特定查询（通过应用程序本身或Explain查询工具）并分析执行统计信息。

说明查询

Explain查询工具允许开发人员了解查询执行计划（请参阅读取查询执行计划），包括执行查询时使用的任何索引的详细信息。 这可用于了解为查询编制索引以预测或追溯分析其性能的效率。

说明查询

要解释查询，请执行以下操作：

查询说明弹出窗口 query-explanation-popup

选择Explain后，将显示一个弹出窗口，描述查询说明的结果（如果选中，还会显示执行）。
此弹出窗口包含的详细信息 —

读取查询执行计划 reading-query-execution-plan

查询执行计划包含预测（或解释）特定查询的性能所需的一切。 通过比较原始JCR（或查询生成器）查询中的限制和排序与在基础索引（Lucene、Elastic或Property）中执行的查询，了解查询的执行效率。

请考虑以下查询 —

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

…其中包含 —

说明此查询会导致以下计划 —

[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])) */

在此计划中，描述在基础索引中执行的查询的部分是 —

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 }]

计划的这一部分指出：

此类查询可能执行良好，因为从索引查询返回的结果不会在查询引擎中进一步过滤（除了访问控制过滤）。 但是，如果不遵循最佳实践，此类查询仍可能执行缓慢 — 请参阅下面的索引遍历。

考虑不同的查询 —

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

…其中包含 —

说明此查询会导致以下计划 —

[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])) */

在此计划中，描述在基础索引中执行的查询的部分是 —

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

计划的这一部分指出：

此查询执行计划将导致/content/dam下的每个资产都从索引中读取，然后由查询引擎进一步筛选（这将仅包括那些与结果集中的非索引属性限制匹配的资产）。

即使只有一小部分资源与限制jcr:content/metadata/myProperty = "My Property Value"匹配，查询也必须读取大量节点以（尝试）填充请求的结果“页面”。 这可能会导致查询性能不佳，查询性能工具中显示为Read Optimization得分很低)，并可能导致出现警告消息，指示正在遍历大量节点（请参阅索引遍历）。

要优化此第二个查询的性能，请创建damAssetLucene-9索引的自定义版本(damAssetLucene-9-custom-1)并添加以下属性定义 —

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

JCR查询备忘单 jcr-query-cheatsheet

为了支持创建高效的 JCR 查询和索引定义，JCR 查询备忘表可供下载，并可在开发过程中用作参考。

它包含 QueryBuilder、XPath 和 SQL-2 的示例查询，并涵盖了在查询性能方面表现不同的多个场景。它还提供了关于如何构建或定制 Oak 索引的建议。本备忘单的内容适用于AEM as a Cloud Service和AEM 6.5。

索引定义最佳实践 index-definition-best-practices

以下是定义或扩展索引时要考虑的一些最佳实践。

自动Cloud Manager管道检查将强制实施上述某些最佳实践。

具有大型结果集的查询 queries-with-large-result-sets

虽然建议避免使用具有大型结果集的查询，但在某些情况下，必须处理大型结果集。通常情况下，结果的大小事先无法知道，因此应采取一些预防措施，以便可靠地进行处理。

存储库遍历 repository-traversal

遍历存储库的查询不使用索引，而是使用与以下类似的消息进行日志记录。

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

通过此日志片段，您可以确定：

有了这些信息，可以使用本文件优化查询部分中描述的方法优化该查询。

索引遍历 index-traversal

使用索引但仍读取大量节点的查询将记录一条类似于以下内容的消息（请注意术语Index-Traversed而不是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//*)

出现这种情况有多种原因 —