DocumentaçãoAEM 6.5Guia do usuário

Consultas e indexação do Oak oak-queries-and-indexing

Last update: Wed Mar 20 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
NOTE
Este artigo é sobre como configurar índices no AEM 6. Para obter as práticas recomendadas de otimização do desempenho de consulta e indexação, consulte Práticas recomendadas para consultas e indexação.

Introdução introduction

Ao contrário do Jackrabbit 2, o Oak não indexa o conteúdo por padrão. Os índices personalizados devem ser criados quando necessário, assim como com os bancos de dados relacionais tradicionais. Se não houver índice para uma consulta específica, muitos nós possivelmente serão percorridos. A query ainda pode funcionar, mas provavelmente está lenta.

Se o Oak encontrar uma consulta sem um índice, uma mensagem de log de nível WARN será impressa:

*WARN* Traversed 1000 nodes with filter Filter(query=select ...) consider creating an index or changing the query

Idiomas de consulta compatíveis supported-query-languages

O mecanismo de consulta Oak é compatível com os seguintes idiomas:

  • XPath (recomendado)
  • SQL-2
  • SQL (obsoleto)
  • JQOM

Tipos de indexador e cálculo de custo indexer-types-and-cost-calculation

O back-end baseado no Apache Oak permite que indexadores diferentes sejam conectados ao repositório.

Um indexador é o Índice de propriedade, para o qual a definição do índice é armazenada no próprio repositório.

Implementações para Apache Lucene e Solr também estão disponíveis por padrão, pois ambas oferecem suporte à indexação de texto completo.

A variável Índice de passagem é usada se nenhum outro indexador estiver disponível. Isso significa que o conteúdo não é indexado e os nós de conteúdo são percorridos para encontrar correspondências para a consulta.

Se houver vários indexadores disponíveis para um query, cada indexador disponível estimará o custo de execução do query. O Oak escolhe o indexador com o menor custo estimado.

chlimage_1-148

O diagrama acima é uma representação de alto nível do mecanismo de execução de consulta do Apache Oak.

Primeiro, a consulta é analisada em uma Árvore de sintaxe abstrata. Em seguida, a consulta é verificada e transformada em SQL-2, que é a linguagem nativa para consultas do Oak.

Em seguida, cada índice é consultado para estimar o custo do query. Depois de concluído, os resultados do índice mais barato são recuperados. Finalmente, os resultados são filtrados para garantir que o usuário atual tenha acesso de leitura ao resultado e que o resultado corresponda à consulta completa.

Configuração dos índices configuring-the-indexes

NOTE
Para um repositório grande, criar um índice é uma operação demorada. Isso é verdade para a criação inicial de um índice e para a reindexação (reconstrução de um índice depois de alterar a definição). Consulte também Solução de problemas de índices Oak e Como evitar a reindexação lenta.

Se a reindexação for necessária em repositórios grandes, especialmente ao usar MongoDB e para índices de texto completo, considere a pré-extração de texto e o uso do oak-run para criar o índice inicial e reindexar.

Os índices são configurados como nós no repositório sob o Oak:índice nó.

O tipo do nó do índice deve ser oak:QueryIndexDefinition. Várias opções de configuração estão disponíveis para cada indexador como propriedades de nó. Para obter mais informações, consulte os detalhes de configuração de cada tipo de indexador abaixo.

O índice de propriedade the-property-index

O Índice de propriedade é útil para consultas que têm restrições de propriedade, mas não são de texto completo. Ela pode ser configurada seguindo o procedimento abaixo:

  1. Abra o CRXDE acessando http://localhost:4502/crx/de/index.jsp

  2. Criar um nó em oak:índice

  3. Nomeie o nó PropertyIndex e defina o tipo de nó como oak:QueryIndexDefinition

  4. Defina as seguintes propriedades para o novo nó:

    • tipo: property (do tipo String)
    • propertyNames: jcr:uuid (do tipo Nome)

    Este exemplo específico indexa a variável jcr:uuid propriedade, cujo trabalho é expor o identificador exclusivo universalmente (UUID) do nó ao qual ele está anexado.

  5. Salve as alterações.

O Índice de propriedades tem as seguintes opções de configuração:

  • A variável type A propriedade especifica o tipo de índice e, nesse caso, deve ser definida como propriedade

  • A variável propertyNames propriedade indica a lista das propriedades armazenadas no índice. Caso esteja ausente, o nome do nó é usado como um valor de referência do nome da propriedade. Neste exemplo, a variável jcr:uuid A propriedade cujo trabalho é expor o identificador exclusivo (UUID) de seu nó é adicionada ao índice.

  • A variável único sinalizador que, se definido como true adiciona uma restrição de exclusividade no índice de propriedade.

  • A variável declaringNodeTypes A propriedade permite especificar um determinado tipo de nó ao qual o índice se aplica somente.

  • A variável reindexar sinalizador que, se definido como true, aciona uma reindexação completa de conteúdo.

O índice ordenado the-ordered-index

O índice Ordenado é uma extensão do índice Propriedade. No entanto, foi descontinuado. Os índices desse tipo devem ser substituídos pelo Índice de propriedades Lucene.

Índice de texto completo Lucene the-lucene-full-text-index

Um indexador de texto completo baseado no Apache Lucene está disponível no AEM 6.

Se um índice de texto completo for configurado, todas as consultas que têm uma condição de texto completo usarão o índice de texto completo, independentemente de haver outras condições indexadas e independentemente de haver uma restrição de caminho.

Se nenhum índice de texto completo estiver configurado, as consultas com condições de texto completo não funcionarão conforme esperado.

Como o índice é atualizado por meio de um thread em segundo plano assíncrono, algumas pesquisas de texto completo ficam indisponíveis por uma pequena janela de tempo até que os processos em segundo plano sejam concluídos.

Você pode configurar um índice de texto completo Lucene seguindo o procedimento abaixo:

  1. Abra o CRXDE e crie um nó em oak:índice.

  2. Nomeie o nó LuceneIndex e defina o tipo de nó como oak:QueryIndexDefinition

  3. Adicione as seguintes propriedades ao nó:

    • tipo: lucene (do tipo String)
    • assíncrono: async (do tipo String)

  4. Salve as alterações.

O Índice Lucene tem as seguintes opções de configuração:

  • A variável type propriedade que especifica o tipo de índice deve ser definida como lucene
  • A variável async propriedade que deve ser definida como async. Isso envia o processo de atualização do índice para uma thread em segundo plano.
  • A variável includePropertyTypes propriedade, que define qual subconjunto de tipos de propriedade é incluído no índice.
  • A variável excludePropertyNames propriedade que define uma lista de nomes de propriedade - propriedades que devem ser excluídas do índice.
  • A variável reindexar sinalizador que, quando definido como true, aciona uma reindexação completa de conteúdo.

A documentação desta seção se aplica aos índices Apache Lucene, Elasticsearch e fulltext do PostgreSQL, SQLite e MySQL, por exemplo. O exemplo a seguir é para AEM/Oak/Lucene.

Dados a serem indexados

O ponto inicial são os dados que devem ser indexados. Considere os seguintes documentos, como exemplo:

ID do documento
Caminho
Texto completo
100
/content/rubik
"Rubik é uma marca finlandesa."
200
/content/rubiksCube
"O Cubo Mágico foi inventado em 1974."
300
/content/cube
"Um cubo é um objeto tridimensional."

Índice invertido

O mecanismo de indexação divide o texto completo em palavras chamadas "tokens" e cria um índice chamado "índice invertido". Este índice contém a lista de documentos onde ele aparece para cada palavra.

Palavras curtas e comuns (também chamadas de "palavras irrelevantes") não são indexadas. Todos os tokens são convertidos em minúsculas e a raiz é aplicada.

Caracteres especiais, como "-" não são indexados.

Token
IDs de documento
194
…, 200,…
marca
…, 100,…
cubo
…, 200, 300,…
dimension
300
finish
…, 100,…
inventar
200
objeto
…, 300,…
rubik
…, 100, 200,…

A lista de documentos está classificada. Isso é útil ao consultar.

Pesquisa

Veja abaixo um exemplo de query. Observe que todos os caracteres especiais (como ') foram substituídas por um espaço:

/jcr:root/content//element(\*; cq:Page)`[` jcr:contains('Rubik s Cube')`]`

As palavras são tokenizadas e filtradas da mesma forma que na indexação (palavras de caractere único são removidas, por exemplo). Nesse caso, a busca é por:

+:fulltext:rubik +:fulltext:cube

O índice consulta a lista de documentos para essas palavras. Se houver muitos documentos, a lista poderá ser grande. Como exemplo, suponha que eles contenham o seguinte:

Token
IDs de documento
rubik
10, 100, 200, 1000
cubo
30, 200, 300, 2000

A Lucene inverte de um lado para o outro entre as duas listas (ou round-robin n listas, ao pesquisar por n palavras):

  • Lido no "rubik" recebe a primeira entrada: encontra 10
  • A leitura no "cubo" obtém a primeira entrada > = 10 10 não é encontrado, então o próximo é 30.
  • Lido no "rubik" recebe a primeira entrada > = 30: encontra 100.
  • A leitura no "cubo" obtém a primeira entrada > = 100: encontra 200.
  • Lido no "rubik" recebe a primeira entrada > = 200 200 é encontrado. Portanto, o documento 200 é uma combinação para ambos os termos. Isso é lembrado.
  • Lido no "rubik" recebe a próxima entrada: 1000.
  • A leitura no "cubo" obtém a primeira entrada > = 1000: encontra 2000.
  • Lido no "rubik" recebe a primeira entrada > = 2000: fim da lista.
  • Por fim, você pode interromper a pesquisa.

O único documento encontrado que contém ambos os termos é 200, como no exemplo abaixo:

200
/content/rubiksCube
"O Cubo Mágico foi inventado em 1974."

Quando várias entradas são encontradas, elas são classificadas por pontuação.

O índice de propriedade Lucene the-lucene-property-index

Desde Oak 1.0.8, Lucene pode ser usado para criar índices que envolvem restrições de propriedade que não são de texto completo.

Para obter um Índice de propriedades Lucene, a variável fulltextEnabled a propriedade deve ser sempre definida como falsa.

Dê o exemplo de consulta a seguir:

select * from [nt:base] where [alias] = '/admin'

Para definir um Índice de propriedades Lucene para a consulta acima, adicione a seguinte definição criando um nó em oak:index:

  • Nome: LucenePropertyIndex
  • Tipo: oak:QueryIndexDefinition

Depois que o nó for criado, adicione as seguintes propriedades:

  • tipo:

    code language-xml 
    lucene (of type String)

  • assíncrono:

    code language-xml 
    async (of type String)

  • fulltextEnabled:

    code language-xml 
    false (of type Boolean)

  • includePropertyNames: ["alias"] (of type String)

NOTE
Comparado ao Índice de propriedades normal, o Índice de propriedades Lucene é sempre configurado no modo assíncrono. Portanto, os resultados retornados pelo índice nem sempre podem refletir o estado mais atualizado do repositório.
NOTE
Para obter informações mais específicas sobre o Índice de propriedades Lucene, consulte o Página de documentação do Apache Jackrabbit Oak Lucene.

Analisadores Lucene lucene-analyzers

Desde a versão 1.2.0, o Oak oferece suporte a analisadores Lucene.

Os analisadores são usados quando um documento é indexado e no momento da consulta. Um analisador examina o texto dos campos e gera um fluxo de token. Os analisadores Lucene são compostos de uma série de classes de tokenizador e filtro.

Os analisadores podem ser configurados por meio da variável analyzers nó (do tipo nt:unstructured) dentro do oak:index definição.

O analisador padrão de um índice é configurado no default filho do nó analisadores.

chlimage_1-149

NOTE
Para obter uma lista de analisadores disponíveis, consulte a documentação da API da versão do Lucene que você está usando.

Especificação direta da classe do analisador specifying-the-analyzer-class-directly

Se quiser usar qualquer analisador pronto para uso, você poderá configurá-lo seguindo o procedimento abaixo:

  1. Localize o índice com o qual você deseja usar o analisador sob o oak:index nó.

  2. No índice, crie um nó secundário chamado default do tipo nt:unstructured.

  3. Adicione uma propriedade ao nó padrão com as seguintes propriedades:

    • Nome: class
    • Tipo: String
    • Valor: org.apache.lucene.analysis.standard.StandardAnalyzer

    O valor é o nome da classe do analisador que você deseja usar.

    Você também pode definir o analisador a ser usado com uma versão específica do lucene usando o opcional luceneMatchVersion propriedade de string. Uma sintaxe válida para usá-la com o Lucene 4.7 seria:

    • Nome: luceneMatchVersion
    • Tipo: String
    • Valor: LUCENE_47

    Se luceneMatchVersion não for fornecida, a Oak usará a versão do Lucene com a qual foi enviada.

  4. Se quiser adicionar um arquivo de palavras irrelevantes às configurações do analisador, você pode criar um nó sob a default um com as seguintes propriedades:

    • Nome: stopwords
    • Tipo: nt:file

Criação de analisadores por meio de composição creating-analyzers-via-composition

Os analisadores também podem ser compostos com base em Tokenizers, TokenFilters, e CharFilters. Você pode fazer isso especificando um analisador e criando nós secundários de seus tokenizers e filtros opcionais que são aplicados na ordem listada. Consulte também https://cwiki.apache.org/confluence/display/solr/AnalyzersTokenizersTokenFilters#Specifying_an_Analyzer_in_the_schema

Considere essa estrutura de nó como um exemplo:

  • Nome: analyzers

    • Nome: default

      • Nome: charFilters

      • Tipo: nt:unstructured

        • Nome: HTMLStrip
        • Nome: Mapping

      • Nome: tokenizer

        • Nome da propriedade: name

          • Tipo: String
          • Valor: Standard

      • Nome: filters

      • Tipo: nt:unstructured

        • Nome: LowerCase

        • Nome: Stop

          • Nome da propriedade: words

            • Tipo: String
            • Valor: stop1.txt, stop2.txt

          • Nome: stop1.txt

            • Tipo: nt:file

          • Nome: stop2.txt

            • Tipo: nt:file

O nome dos filtros, charFilters e tokenizers são formados pela remoção dos sufixos de fábrica. Assim:

  • org.apache.lucene.analysis.standard.StandardTokenizerFactory torna-se standard

  • org.apache.lucene.analysis.charfilter.MappingCharFilterFactory torna-se Mapping

  • org.apache.lucene.analysis.core.StopFilterFactory torna-se Stop

Qualquer parâmetro de configuração necessário para a fábrica é especificado como a propriedade do nó em questão.

Para casos como carregar palavras de interrupção em que o conteúdo de arquivos externos deve ser carregado, o conteúdo pode ser fornecido criando um nó filho de nt:file tipo para o arquivo em questão.

O índice Solr the-solr-index

A finalidade do índice Solr é a pesquisa de texto completo, mas ele também pode ser usado para indexar a pesquisa por caminho, restrições de propriedade e restrições de tipo principal. Isso significa que o índice Solr no Oak pode ser usado para qualquer tipo de consulta JCR.

A integração no AEM acontece no nível do repositório, de modo que o Solr é um dos possíveis índices que podem ser usados no Oak, a nova implementação do repositório enviada com o AEM.

Ele pode ser configurado para funcionar como um servidor remoto com a instância do AEM.

Configuração do AEM com um único servidor Solr remoto configuring-aem-with-a-single-remote-solr-server

O AEM também pode ser configurado para funcionar com uma instância remota do servidor Solr:

  1. Baixe e extraia a versão mais recente do Solr. Para obter mais informações, consulte a seção Documentação de instalação do Apache Solr.

  2. Agora, crie dois fragmentos Solr. Você pode fazer isso criando pastas para cada fragmento na pasta em que o Solr foi desempacotado:

    • Para o primeiro fragmento, crie a pasta:

    <solrunpackdirectory>\aemsolr1\node1

    • Para o segundo fragmento, crie a pasta:

    <solrunpackdirectory>\aemsolr2\node2

  3. Localize a instância de exemplo no pacote Solr. Está em uma pasta chamada " example" na raiz do pacote.

  4. Copie as seguintes pastas da instância de exemplo para as duas pastas compartilhadas ( aemsolr1\node1 e aemsolr2\node2):

    • contexts
    • etc
    • lib
    • resources
    • scripts
    • solr-webapp
    • webapps
    • start.jar

  5. Crie uma pasta chamada " cfg" em cada uma das duas pastas compartilhadas.

  6. Coloque os arquivos de configuração Solr e Zookeeper no recém-criado cfg pastas.

    note note
    NOTE
    Para obter mais informações sobre a configuração Solr e ZooKeeper, consulte o Documentação da configuração Solr e a variável Guia de introdução do ZooKeeper.

  7. Inicie o primeiro fragmento com suporte do ZooKeeper acessando aemsolr1\node1 e executando o seguinte comando:

    code language-xml 
    java -Xmx2g -Dbootstrap_confdir=./cfg/oak/conf -Dcollection.configName=myconf -DzkRun -DnumShards=2 -jar start.jar

  8. Inicie o segundo fragmento acessando aemsolr2\node2 e executando o seguinte comando:

    code language-xml 
    java -Xmx2g -Djetty.port=7574 -DzkHost=localhost:9983 -jar start.jar

  9. Depois que ambos os fragmentos forem iniciados, teste se tudo está ativo e em execução conectando-se à interface Solr em http://localhost:8983/solr/#/

  10. Inicie o AEM e acesse o Console da Web em http://localhost:4502/system/console/configMgr

  11. Defina a seguinte configuração em Configuração do servidor remoto Oak Solr:

    • URL HTTP Solr: http://localhost:8983/solr/

  12. Escolher Solr remoto na lista suspensa em Oak Solr provedor de servidor.

  13. Acesse o CRXDE e faça logon como administrador.

  14. Crie um nó chamado solrIndex em oak:índice e defina as seguintes propriedades:

    • tipo: solr (do tipo String)
    • assíncrono: async (do tipo String)
    • reindexar: true (do tipo Booleano)

  15. Salve as alterações.

Configuração recomendada para Solr recommended-configuration-for-solr

Veja abaixo um exemplo de uma configuração básica que pode ser usada com todas as três implantações Solr descritas neste artigo. Ele acomoda os índices de propriedade dedicados que já estão presentes no AEM; não use com outros aplicativos.

Para usá-lo corretamente, você deve colocar o conteúdo do arquivo diretamente no Diretório Home Solr. Se houver implantações com vários nós, ela deverá ir diretamente para a pasta raiz de cada nó.

Arquivos de configuração Solr recomendados

Obter arquivo

Ferramentas de indexação do AEM aem-indexing-tools

O AEM 6.1 também integra duas ferramentas de indexação presentes no AEM 6.0 como parte do conjunto de ferramentas do Adobe Consulting Services Commons:

  1. Explicar consulta, uma ferramenta projetada para ajudar os administradores a entender como as consultas são executadas;
  2. Gerenciador de índice Oak, uma Interface do Usuário da Web para manter os índices existentes.

Agora você pode contatá-los acessando Ferramentas - Operações - Painel - Diagnóstico na tela de boas-vindas AEM.

Para obter mais informações sobre como usá-los, consulte a Documentação do Painel de operações.

Criação de índices de propriedade por meio do OSGi creating-property-indexes-via-osgi

O pacote ACS Commons também expõe as configurações de OSGi que podem ser usadas para criar índices de propriedade.

Você pode acessá-lo no Console da Web procurando por "Garantir índice de propriedade do Oak".

chlimage_1-150

Solução de problemas de indexação troubleshooting-indexing-issues

Podem surgir situações em que as consultas demoram muito para serem executadas e o tempo geral de resposta do sistema é lento.

Esta seção apresenta um conjunto de recomendações sobre o que deve ser feito para rastrear a causa desses problemas e conselhos sobre como resolvê-los.

Preparando informações de depuração para análise preparing-debugging-info-for-analysis

A maneira mais fácil de obter as informações necessárias para a consulta que está sendo executada é por meio do Ferramenta Explicar consulta. Isso permite coletar as informações precisas necessárias para depurar uma consulta lenta sem a necessidade de consultar as informações de nível de log. Isso é desejável se você souber a query que está sendo depurada.

Se isso não for possível por algum motivo, você poderá coletar os logs de indexação em um único arquivo e usá-lo para solucionar seu problema específico.

Ativar registro enable-logging

Para ativar o registro, você deve ativar DEPURAR logs de nível para as categorias relacionadas à indexação e consultas do Oak. Essas categorias são:

  • org.apache.jackrabbit.oak.plugins.index
  • org.apache.jackrabbit.oak.query
  • com.day.cq.search

A variável com.day.cq.search A categoria só será aplicável se você estiver usando o utilitário QueryBuilder fornecido pelo AEM.

NOTE
É importante que os logs sejam definidos como DEBUG somente enquanto a consulta que você deseja solucionar problemas estiver sendo executada. Caso contrário, muitos eventos serão gerados nos logs ao longo do tempo. Por causa disso, uma vez coletados os registros necessários, volte para o registro em nível INFO para as categorias mencionadas acima.

Você pode ativar o registro seguindo este procedimento:

  1. Aponte seu navegador para https://serveraddress:port/system/console/slinglog
  2. Clique em Adicionar novo logger na parte inferior do console.
  3. Na linha recém-criada, adicione as categorias mencionadas acima. Você pode usar o + assine para adicionar mais de uma categoria a um único agente de log.
  4. Escolher DEPURAR do Nível de log lista suspensa.
  5. Defina o arquivo de saída como logs/queryDebug.log. Isso correlaciona todos os eventos DEBUG em um único arquivo de log.
  6. Execute a consulta ou renderize a página que está usando a consulta que você deseja depurar.
  7. Depois de executar a query, volte para o console de registro e altere o nível de log do agente de registro recém-criado para INFORMAÇÕES.

Configuração do índice index-configuration

A maneira como a consulta é avaliada é amplamente afetada pela configuração do índice. É importante analisar a configuração do índice ou enviá-la para o suporte. Você pode obter a configuração como um pacote de conteúdo ou uma representação JSON.

Normalmente, a configuração de indexação é armazenada no /oak:index no CRXDE, você pode obter a versão JSON em:

https://serveraddress:port/oak:index.tidy.-1.json

Se o índice estiver configurado em um local diferente, altere o caminho de acordo.

Saída do MBean mbean-output

Às vezes, é útil fornecer a saída de MBeans relacionados ao índice para depuração. Você pode fazer isso ao:

  1. Indo para o console JMX em:
    https://serveraddress:port/system/console/jmx

  2. Procurar os seguintes MBeans:

    • Estatísticas do Índice Lucene
    • Estatísticas de suporte a CopyOnRead
    • Estatísticas de consulta do Oak
    • IndexStats

  3. Clique em cada um dos MBeans para obter estatísticas de desempenho. Crie uma captura de tela ou anote-as caso seja necessário enviar um suporte.

Você também pode obter a variante JSON dessas estatísticas nos seguintes URLs:

  • https://serveraddress:port/system/sling/monitoring/mbeans/org/apache/jackrabbit/oak/%2522LuceneIndex%2522.tidy.-1.json
  • https://serveraddress:port/system/sling/monitoring/mbeans/org/apache/jackrabbit/oak/%2522LuceneIndex%2522.tidy.-1.json
  • https://serveraddress:port/system/sling/monitoring/mbeans/org/apache/jackrabbit/oak/%2522LuceneIndex%2522.tidy.-1.json
  • https://serveraddress:port/system/sling/monitoring/mbeans/org/apache/jackrabbit/oak/%2522LuceneIndex%2522.tidy.-1.json

Você também pode fornecer saída JMX consolidada por meio de https://serveraddress:port/system/sling/monitoring/mbeans/org/apache/jackrabbit/oak.tidy.3.json. Isso incluiria todos os detalhes do MBean relacionado ao Oak no formato JSON.

Outros detalhes other-details

Você pode coletar detalhes adicionais para ajudar a solucionar o problema, como:

  1. A versão do Oak em que sua instância está sendo executada. Você pode ver isso abrindo o CRXDE e observando a versão no canto inferior direito da página de boas-vindas ou verificando a versão do org.apache.jackrabbit.oak-core pacote.
  2. A saída do depurador do QueryBuilder da consulta com problema. O depurador pode ser acessado em: https://serveraddress:port/libs/cq/search/content/querydebug.html
recommendation-more-help
19ffd973-7af2-44d0-84b5-d547b0dffee2