Práticas recomendadas de indexação no AEM
Saiba mais sobre as práticas recomendadas de indexação no Adobe Experience Manager (AEM). O Apache Jackrabbit Oak habilita a pesquisa de conteúdo no AEM e os seguintes são pontos-chave:
- Imediatamente, o AEM fornece vários índices para oferecer suporte à funcionalidade de pesquisa e consulta, por exemplo
damAssetLucene
,cqPageLucene
e muito mais. - Todas as definições de índice são armazenadas no repositório no nó
/oak:index
. - O AEM as a Cloud Service só oferece suporte a índices Oak Lucene.
- A configuração do índice deve ser gerenciada na base de código do projeto AEM e implantada usando os pipelines de CI/CD do Cloud Manager.
- Se vários índices estiverem disponíveis para uma determinada consulta, o índice com o menor custo estimado será usado.
- Se nenhum índice estiver disponível para uma determinada consulta, a árvore de conteúdo será percorrida para encontrar o conteúdo correspondente. No entanto, o limite padrão via
org.apache.jackrabbit.oak.query.QueryEngineSettingsService
é percorrer apenas 10.0000 nós. - Os resultados de uma consulta são filtrados por último para garantir que o usuário atual tenha acesso de leitura. Isso significa que os resultados da consulta podem ser menores que o número de nós indexados.
- A reindexação do repositório após as alterações de definição de índice requer tempo e depende do tamanho do repositório.
Para ter uma funcionalidade de pesquisa eficiente e correta que não afete o desempenho da instância do AEM, é importante entender as práticas recomendadas de indexação.
Índice personalizado vs. OOTB
Às vezes, você deve criar índices personalizados para dar suporte aos requisitos de pesquisa. No entanto, siga as diretrizes abaixo antes de criar índices personalizados:
-
Entenda os requisitos de pesquisa e verifique se os índices OOTB podem dar suporte aos requisitos de pesquisa. Use a Ferramenta de Desempenho de Consulta, disponível em SDK local e AEMCS via Developer Console ou
https://author-pXXXX-eYYYY.adobeaemcloud.com/ui#/aem/libs/granite/operations/content/diagnosistools/queryPerformance.html?appId=aemshell
. -
Defina uma consulta ideal, use o fluxograma de otimização de consultas e a Folha de características de consulta JCR como referência.
-
Se os índices OOTB não forem compatíveis com os requisitos de pesquisa, você terá duas opções. No entanto, examine as Dicas para Criar Índices Eficientes
- Personalizar o índice OOTB: opção preferencial, pois é fácil de manter e atualizar.
- Índice totalmente personalizado: somente se a opção acima não funcionar.
Personalizar o índice OOTB
-
No AEMCS, ao personalizar o índice OOTB, use a convenção de nomenclatura <OOTBIndexName>-<productVersion>-custom-<customVersion>. Por exemplo,
cqPageLucene-custom-1
oudamAssetLucene-8-custom-1
. Isso ajuda a mesclar a definição de índice personalizado sempre que o índice OOTB é atualizado. Consulte Alterações em índices prontos para uso para obter mais detalhes. -
No AEM 6.X, a nomeação acima não funciona. No entanto, basta atualizar o índice OOTB com as propriedades necessárias no nó
indexRules
. -
Sempre copie a definição de índice OOTB mais recente da instância AEM usando o Gerenciador de pacotes CRX DE (https://experienceleague.adobe.com/crx/packmgr/?lang=pt-BR), renomeie-a e adicione personalizações dentro do arquivo XML.
-
Armazene a definição de índice no projeto AEM em
ui.apps/src/main/content/jcr_root/_oak_index
e implante-a usando os pipelines CI/CD do Cloud Manager. Consulte Implantando Definições de Índice Personalizadas para obter mais detalhes.
Índice totalmente personalizado
A criação de um índice totalmente personalizado deve ser a última opção e somente se a opção acima não funcionar.
-
Ao criar um índice totalmente personalizado, use <prefix>.<customIndexName>-<version>-custom-<customVersion> convenção de nomenclatura. Por exemplo,
wknd.adventures-1-custom-1
. Isso ajuda a evitar conflitos de nomenclatura. Aqui,wknd
é o prefixo eadventures
é o nome de índice personalizado. Essa convenção é aplicável ao AEM 6.X e ao AEMCS e ajuda a preparar a migração futura para o AEMCS. -
O AEM CS é compatível apenas com os índices Lucene, portanto, para se preparar para a migração futura para o AEM, sempre use os índices Lucene. Consulte Índices Lucene versus Índices de propriedades para obter mais detalhes.
-
Evite criar um índice personalizado no mesmo tipo de nó do índice OOTB. Em vez disso, personalize o índice OOTB com as propriedades necessárias no nó
indexRules
. Por exemplo, não crie um índice personalizado no tipo de nódam:Asset
, mas personalize o índicedamAssetLucene
OOTB. Foi uma causa raiz comum de problemas de desempenho e funcionais. -
Além disso, evite adicionar vários tipos de nó, por exemplo
cq:Page
ecq:Tag
, sob o nó de regras de indexação (indexRules
). Em vez disso, crie índices separados para cada tipo de nó. -
Como mencionado na seção acima, armazene a definição de índice no projeto AEM em
ui.apps/src/main/content/jcr_root/_oak_index
e implante-a usando os pipelines de CI/CD do Cloud Manager. Consulte Implantando Definições de Índice Personalizadas para obter mais detalhes. -
As diretrizes de definição do índice são:
- O tipo de nó (
jcr:primaryType
) deve seroak:QueryIndexDefinition
- O tipo de índice (
type
) deve serlucene
- A propriedade assíncrona (
async
) deve serasync,nrt
- Use
includedPaths
e evite a propriedadeexcludedPaths
. Sempre defina o valorqueryPaths
com o mesmo valor que o valorincludedPaths
. - Para impor a restrição de caminho, use a propriedade
evaluatePathRestrictions
e defina-a comotrue
. - Use a propriedade
tags
para marcar o índice e, durante a consulta, especifique esse valor de marcas para usar o índice. A sintaxe de consulta geral é<query> option(index tag <tagName>)
.
code language-xml /oak:index/wknd.adventures-1-custom-1 - jcr:primaryType = "oak:QueryIndexDefinition" - type = "lucene" - compatVersion = 2 - async = ["async", "nrt"] - includedPaths = ["/content/wknd"] - queryPaths = ["/content/wknd"] - evaluatePathRestrictions = true - tags = ["customAdvSearch"] ...
- O tipo de nó (
Exemplos
Para entender as práticas recomendadas, vamos analisar alguns exemplos.
Uso indevido da propriedade de tags
A imagem abaixo mostra a definição de índice OOTB e personalizado, destacando a propriedade tags
. Ambos os índices usam o mesmo valor visualSimilaritySearch
.
Análise
Este é um uso inadequado da propriedade tags
no índice personalizado. O mecanismo de consulta do Oak escolhe o índice personalizado sobre a causa do índice OOTB do custo estimado mais baixo.
A maneira correta é personalizar o índice OOTB e adicionar as propriedades necessárias no nó indexRules
. Consulte Personalizando o índice OOTB para obter mais detalhes.
Índice no tipo de nó dam:Asset
A imagem abaixo mostra o índice personalizado para o tipo de nó dam:Asset
com a propriedade includedPaths
definida como um caminho específico.
Análise
Se você executar o omnisearch no Assets, ele retornará resultados incorretos porque o índice personalizado tem um custo estimado mais baixo.
Não crie um índice personalizado no tipo de nó dam:Asset
, mas personalize o índice damAssetLucene
OOTB com as propriedades necessárias no nó indexRules
.
Vários tipos de nó nas regras de indexação
A imagem abaixo mostra o índice personalizado com vários tipos de nó sob o nó indexRules
.
Análise
Não é recomendável adicionar vários tipos de nó em um único índice. No entanto, convém adicionar tipos de nó de índice no mesmo índice se os tipos de nó estiverem intimamente relacionados, por exemplo, cq:Page
e cq:PageContent
.
Uma solução válida é personalizar o índice OOTB cqPageLucene
e damAssetLucene
, adicionar as propriedades necessárias sob o nó indexRules
existente.
Ausência da propriedade queryPaths
A imagem abaixo mostra o índice personalizado (não seguindo também a convenção de nomenclatura) sem a propriedade queryPaths
.
Análise
Sempre defina o valor queryPaths
com o mesmo valor que o valor includedPaths
. Além disso, para impor a restrição de caminho, defina a propriedade evaluatePathRestrictions
como true
.
Consulta com tag de índice
A imagem abaixo mostra o índice personalizado com a propriedade tags
e como usá-lo durante a consulta.
/jcr:root/content/dam//element(*,dam:Asset)[(jcr:content/@contentFragment = 'true' and jcr:contains(., '/content/sitebuilder/test/mysite/live/ja-jp/mypage'))]order by @jcr:created descending option (index tag assetPrefixNodeNameSearch)
Análise
Demonstra como definir um valor de propriedade tags
não conflitante e correto no índice e usá-lo durante a consulta. A sintaxe de consulta geral é <query> option(index tag <tagName>)
. Consulte também Marca de Índice de Opção de Consulta
Índice personalizado
A imagem abaixo mostra o índice personalizado com o nó suggestion
para obter a funcionalidade de pesquisa avançada.
Análise
É um caso de uso válido para criar um índice personalizado para a funcionalidade de pesquisa avançada. No entanto, o nome do índice deve seguir o <prefix>.<customIndexName>-<version>-custom-<customVersion> convenção de nomenclatura.
Otimização de índice ao desabilitar o Apache Tika
O AEM usa o Apache Tika para extrair conteúdo de metadados e texto de arquivos de tipos como PDF, Word, Excel e muito mais. O conteúdo extraído é armazenado no repositório e indexado pelo índice Oak Lucene.
Às vezes, os usuários não exigem a capacidade de pesquisar no conteúdo de um arquivo/ativo, nesses casos, você pode melhorar o desempenho da indexação desativando o Apache Tika. As vantagens são:
- Indexação mais rápida
- Redução de tamanho do índice
- Menos uso de hardware
Desativar por tipo MIME
Para desativar o Apache Tika por tipo MIME, use as seguintes etapas:
- Adicione o nó
tika
do tipont:unstructured
sob a definição de índice OOBT ou personalizado. No exemplo a seguir, o tipo de PDF mime está desabilitado para o índice OOTBdamAssetLucene
.
/oak:index/damAssetLucene
- jcr:primaryType = "oak:QueryIndexDefinition"
- type = "lucene"
...
<tika jcr:primaryType="nt:unstructured">
<config.xml/>
</tika>
- Adicione o
config.xml
com os seguintes detalhes no nótika
.
<properties>
<parsers>
<parser class="org.apache.tika.parser.EmptyParser">
<mime>application/pdf</mime>
<!-- Add more mime types to disable -->
</parsers>
</properties>
- Para atualizar o índice armazenado, defina a propriedade
refresh
comotrue
no nó de definição de índice. Consulte Propriedades de Definição de Índice para obter mais detalhes.
A imagem a seguir mostra o índice OOTB damAssetLucene
com o nó tika
e o arquivo config.xml
que desabilita o PDF e outros tipos MIME.
Desativar completamente
Para desativar completamente o Apache Tika, siga as etapas abaixo:
- Adicione a propriedade
includePropertyTypes
em/oak:index/<INDEX-NAME>/indexRules/<NODE-TYPE>
e defina o valor comoString
. Por exemplo, na imagem abaixo, a propriedadeincludePropertyTypes
é adicionada ao tipo de nódam:Asset
do índice OOBTdamAssetLucene
.
- Adicione
data
com as propriedades abaixo do nóproperties
, verifique se é o primeiro nó acima da definição de propriedade. Por exemplo, veja a imagem abaixo:
/oak:index/<INDEX-NAME>/indexRules/<NODE-TYPE>/properties/data
- jcr:primaryType = "nt:unstructured"
- type = "String"
- name = "jcr:data"
- nodeScopeIndex = false
- propertyIndex = false
- analyze = false
- Reindexe a definição de índice atualizada definindo a propriedade
reindex
comotrue
no nó de definição de índice.
Ferramentas úteis
Vamos analisar algumas ferramentas que podem ajudá-lo a definir, analisar e otimizar os índices.
Ferramenta de criação de índice
A ferramenta Gerador de Definição de Índice Oak ajuda a gerar a definição de índice com base nas consultas de entrada. Criar um índice personalizado é um bom ponto de partida.
Ferramenta Analisar índice
A ferramenta Analisador de Definição de Índice ajuda o a analisar a definição do índice e fornece recomendações para melhorar a definição do índice.
Ferramenta de desempenho de consulta
A Ferramenta de Desempenho de Consulta do OOTB, disponível no SDK local e no AEMCS via Developer Console ou https://author-pXXXX-eYYYY.adobeaemcloud.com/ui#/aem/libs/granite/operations/content/diagnosistools/queryPerformance.html?appId=aemshell
, ajuda o a analisar o desempenho da consulta e a Folha de características de consulta JCR para definir a consulta ideal.
Dicas e ferramentas para solução de problemas
A maioria dos itens abaixo é aplicável para AEM 6.X e solução de problemas local.
-
Gerenciador de Índice disponível em
http://host:port/libs/granite/operations/content/diagnosistools/indexManager.html
para obter informações de índice, como tipo, última atualização, tamanho. -
Registro detalhado de pacotes Java™ relacionados à consulta e indexação do Oak, como
org.apache.jackrabbit.oak.plugins.index
,org.apache.jackrabbit.oak.query
ecom.day.cq.search
viahttp://host:port/system/console/slinglog
, para solução de problemas. -
MBean JMX do tipo IndexStats disponível em
http://host:port/system/console/jmx
para obter informações de índice, como status, progresso ou estatísticas relacionadas à indexação assíncrona. Também fornece FailingIndexStats, se não houver resultados aqui, significa que nenhum índice está corrompido. AsyncIndexerService marca qualquer índice que não seja atualizado por 30 minutos (configurável) como corrompido e interrompe a indexação. Se uma consulta não estiver fornecendo os resultados esperados, é útil que os desenvolvedores verifiquem isso antes de prosseguir com a reindexação, pois a reindexação é computacionalmente cara e demorada. -
MBean JMX do tipo LuceneIndex disponível em
http://host:port/system/console/jmx
para estatísticas do Índice Lucene, como tamanho, número de documentos por definição de índice. -
MBean JMX do tipo QueryStat disponível em
http://host:port/system/console/jmx
para Estatísticas de consulta do Oak, incluindo consultas lentas e populares com detalhes como consulta, tempo de execução.
Recursos adicionais
Consulte a seguinte documentação para obter mais informações: