Query e indicizzazione Oak oak-queries-and-indexing
Introduzione introduction
A differenza di Jackrabbit 2, Oak non indicizza il contenuto per impostazione predefinita. Gli indici personalizzati devono essere creati quando necessario, come con i database relazionali tradizionali. Se non esiste un indice per una query specifica, è possibile che vengano attraversati molti nodi. La query potrebbe ancora funzionare, ma è probabilmente lenta.
Se Oak rileva una query senza un indice, viene stampato un messaggio di registro di livello WARN:
*WARN* Traversed 1000 nodes with filter Filter(query=select ...) consider creating an index or changing the query
Lingue di query supportate supported-query-languages
Il motore di query di Oak supporta le seguenti lingue:
- XPath (consigliato)
- SQL-2
- SQL (obsoleto)
- JQOM
Tipi di indicizzatore e calcolo dei costi indexer-types-and-cost-calculation
Il backend basato su Apache Oak consente di collegare diversi indicizzatori all’archivio.
Un indicizzatore è l'Indice proprietà, per il quale la definizione dell'indice è archiviata nell'archivio stesso.
Per impostazione predefinita, sono disponibili anche le implementazioni per Apache Lucene e Solr, che supportano entrambe l'indicizzazione full-text.
Se non è disponibile alcun altro indicizzatore, viene utilizzato l'Indice trasversale. Ciò significa che il contenuto non è indicizzato e che i nodi di contenuto vengono attraversati per trovare corrispondenze alla query.
Se per una query sono disponibili più indicizzatori, ogni indicizzatore disponibile stima il costo dell'esecuzione della query. Oak sceglie quindi l’indicizzatore con il costo stimato più basso.
Il diagramma precedente è una rappresentazione di alto livello del meccanismo di esecuzione delle query di Apache Oak.
Innanzitutto, la query viene analizzata in una struttura ad albero della sintassi astratta. Quindi, la query viene controllata e trasformata in SQL-2, che è la lingua nativa per le query Oak.
Successivamente, ogni indice viene consultato per stimare il costo della query. Una volta completato, vengono recuperati i risultati dall’indice più economico. Infine, i risultati vengono filtrati, sia per garantire che l’utente corrente abbia accesso in lettura al risultato sia che il risultato corrisponda alla query completa.
Configurazione degli indici configuring-the-indexes
Se la reindicizzazione è necessaria in archivi di grandi dimensioni, specialmente quando si utilizza MongoDB e per gli indici full-text, considera la pre-estrazione del testo e l’utilizzo di oak-run per creare l’indice iniziale e reindicizzare.
Gli indici sono configurati come nodi nell'archivio nel nodo Oak:index.
Il tipo del nodo indice deve essere oak:QueryIndexDefinition. Per ogni indicizzatore sono disponibili diverse opzioni di configurazione come proprietà del nodo. Per ulteriori informazioni, consulta i dettagli di configurazione per ogni tipo di indicizzatore riportati di seguito.
Indice proprietà the-property-index
L'indice delle proprietà è utile per le query che hanno vincoli di proprietà ma non sono full-text. Può essere configurato seguendo la procedura seguente:
-
Apri CRXDE andando su
http://localhost:4502/crx/de/index.jsp
-
Crea un nodo in oak:index
-
Denomina il nodo PropertyIndex e imposta il tipo di nodo su oak:QueryIndexDefinition
-
Imposta le seguenti proprietà per il nuovo nodo:
- tipo:
property
(di tipo Stringa) - propertyNames:
jcr:uuid
(di tipo Name)
In questo esempio particolare viene indicizzata la proprietà
jcr:uuid
, il cui processo consiste nell'esporre l'identificatore univoco universale (UUID) del nodo a cui è associata. - tipo:
-
Salva le modifiche.
L’indice delle proprietà dispone delle seguenti opzioni di configurazione:
-
La proprietà type specifica il tipo di indice e in questo caso deve essere impostata su property
-
La proprietà propertyNames indica l'elenco delle proprietà memorizzate nell'indice. Se manca, il nome del nodo viene utilizzato come valore di riferimento del nome di proprietà. In questo esempio, la proprietà jcr:uuid il cui processo consiste nell'esporre l'identificatore univoco (UUID) del relativo nodo viene aggiunta all'indice.
-
Il flag unique che, se impostato su true, aggiunge un vincolo di univocità nell'indice della proprietà.
-
La proprietà DeclaringNodeTypes consente di specificare un determinato tipo di nodo a cui si applica solo l'indice.
-
Il flag reindex che, se impostato su true, attiva una reindicizzazione del contenuto completo.
Indice ordinato the-ordered-index
L'indice Ordinato è un'estensione dell'indice Proprietà. Tuttavia, è stato dichiarato obsoleto. Gli indici di questo tipo devono essere sostituiti con Indice proprietà Lucene.
Indice full-text Lucene the-lucene-full-text-index
Un indicizzatore full-text basato su Apache Lucene è disponibile in AEM 6.
Se è configurato un indice full-text, tutte le query con una condizione full-text utilizzano l'indice full-text, indipendentemente dall'esistenza di altre condizioni indicizzate e da eventuali restrizioni di percorso.
Se non è configurato alcun indice full-text, le query con condizioni full-text non funzionano come previsto.
Poiché l’indice viene aggiornato tramite un thread in background asincrono, alcune ricerche full-text non sono disponibili per una piccola finestra di tempo fino al completamento dei processi in background.
Per configurare un indice full-text Lucene, attenersi alla procedura descritta di seguito.
-
Apri CRXDE e crea un nodo in oak:index.
-
Denomina il nodo LuceneIndex e imposta il tipo di nodo su oak:QueryIndexDefinition
-
Aggiungi le seguenti proprietà al nodo:
- tipo:
lucene
(di tipo Stringa) - asincrono:
async
(di tipo String)
- tipo:
-
Salva le modifiche.
L’indice Lucene dispone delle seguenti opzioni di configurazione:
- La proprietà type che specifica il tipo di indice deve essere impostata su lucene
- La proprietà async che deve essere impostata su async. In questo modo il processo di aggiornamento dell’indice viene inviato a un thread in background.
- La proprietà includePropertyTypes, che definisce il sottoinsieme dei tipi di proprietà inclusi nell'indice.
- La proprietà excludePropertyNames che definisce un elenco di nomi di proprietà, ovvero proprietà da escludere dall'indice.
- Il flag reindex che, se impostato su true, attiva una reindicizzazione del contenuto completo.
Ricerca full-text understanding-fulltext-search
La documentazione di questa sezione si applica, ad esempio, agli indici Apache Lucene, Elasticsearch e full-text di PostgreSQL, SQLite e MySQL. L’esempio seguente è per AEM/Oak/Lucene.
Dati da indicizzare
Il punto di partenza sono i dati che devono essere indicizzati. Prendi ad esempio i seguenti documenti:
Indice invertito
Il meccanismo di indicizzazione suddivide il testo completo in parole chiamate "token" e crea un indice denominato "indice invertito". Questo indice contiene l'elenco dei documenti in cui viene visualizzato per ogni parola.
Le parole brevi e comuni (dette anche "parole non significative") non sono indicizzate. Tutti i token vengono convertiti in minuscolo e viene applicato lo stemming.
I caratteri speciali come "-" non sono indicizzati.
L'elenco dei documenti è ordinato. Questo è utile quando si esegue una query.
Ricerca in corso
Di seguito è riportato un esempio di query. Tutti i caratteri speciali (ad esempio ') sono stati sostituiti da uno spazio:
/jcr:root/content//element(\*; cq:Page)`[` jcr:contains('Rubik s Cube')`]`
Le parole vengono tokenizzate e filtrate nello stesso modo in cui vengono indicizzate (le parole a carattere singolo vengono rimosse, ad esempio). In questo caso, la ricerca è per:
+:fulltext:rubik +:fulltext:cube
L'indice consulta l'elenco dei documenti per tali parole. Se sono presenti molti documenti, l'elenco può essere di grandi dimensioni. Ad esempio, supponiamo che contengano quanto segue:
Lucene si sposta avanti e indietro tra i due elenchi (o elenchi round robin n
, durante la ricerca di n
parole):
- Leggi nel "rubik" ottiene la prima voce: trova 10
- La lettura nel "cubo" ottiene la prima voce
>
= 10. 10 non è stato trovato, quindi quello successivo è 30. - Leggi in "rubik" ottiene la prima voce
>
= 30: ne trova 100. - Letto nel "cubo" ottiene la prima voce
>
= 100: ne trova 200. - Leggere in "rubik" ottiene la prima voce
>
= 200. 200. Quindi il documento 200 corrisponde a entrambi i termini. Questo viene ricordato. - Leggi nella "rubik" ottiene la prossima voce: 1000.
- Letto nel "cubo" ottiene la prima voce
>
= 1000: trova 2000. - Leggi in "rubik" ottiene la prima voce
>
= 2000: fine dell'elenco. - Infine, puoi interrompere la ricerca.
L’unico documento trovato che contiene entrambi i termini è 200, come nell’esempio seguente:
Quando vengono trovate più voci, queste vengono ordinate in base al punteggio.
Indice della proprietà Lucene the-lucene-property-index
A partire da Oak 1.0.8, Lucene può essere utilizzato per creare indici che comportano vincoli di proprietà che non sono full-text.
Per ottenere un indice della proprietà Lucene, la proprietà fulltextEnabled deve essere sempre impostata su false.
Prendi il seguente esempio di query:
select * from [nt:base] where [alias] = '/admin'
Per definire un indice delle proprietà Lucene per la query precedente, è possibile aggiungere la seguente definizione creando un nodo in oak:index
:
- Nome:
LucenePropertyIndex
- Tipo:
oak:QueryIndexDefinition
Una volta creato il nodo, aggiungi le seguenti proprietà:
-
tipo:
code language-xml lucene (of type String)
-
asincrono:
code language-xml async (of type String)
-
fulltextEnabled:
code language-xml false (of type Boolean)
-
includePropertyNames:
["alias"] (of type String)
Analizzatori Lucene lucene-analyzers
A partire dalla versione 1.2.0, Oak supporta gli analizzatori Lucene.
Gli analizzatori vengono utilizzati sia quando un documento viene indicizzato che al momento della query. Un analizzatore esamina il testo dei campi e genera un flusso di token. Gli analizzatori Lucene sono composti da una serie di classi di tokenizzatore e filtro.
Gli analizzatori possono essere configurati tramite il nodo analyzers
(di tipo nt:unstructured
) nella definizione oak:index
.
L'analizzatore predefinito per un indice è configurato nell'elemento figlio default
del nodo analizzatori.
Specifica diretta della classe dell'analizzatore specifying-the-analyzer-class-directly
Se desideri utilizzare un analizzatore predefinito, puoi configurarlo seguendo la procedura seguente:
-
Individuare l'indice con cui si desidera utilizzare l'analizzatore sotto il nodo
oak:index
. -
Nell'indice creare un nodo figlio denominato
default
di tipont:unstructured
. -
Aggiungi una proprietà al nodo predefinito con le seguenti proprietà:
- Nome:
class
- Tipo:
String
- Valore:
org.apache.lucene.analysis.standard.StandardAnalyzer
Il valore è il nome della classe dell'analizzatore che si desidera utilizzare.
È inoltre possibile impostare l'analizzatore da utilizzare con una versione specifica di Lucene utilizzando la proprietà stringa facoltativa
luceneMatchVersion
. Una sintassi valida per utilizzarlo con Lucene 4.7 sarebbe:- Nome:
luceneMatchVersion
- Tipo:
String
- Valore:
LUCENE_47
Se
luceneMatchVersion
non viene fornito, Oak utilizza la versione di Lucene con cui è stato fornito. - Nome:
-
Se desideri aggiungere un file di parole non significative alle configurazioni dell'analizzatore, puoi creare un nodo sotto
default
con le seguenti proprietà:- Nome:
stopwords
- Tipo:
nt:file
- Nome:
Creazione di analizzatori tramite la composizione creating-analyzers-via-composition
Gli analizzatori possono essere composti anche in base a Tokenizers
, TokenFilters
e CharFilters
. Per farlo, specifica un analizzatore e crea nodi secondari dei suoi tokenizer e filtri opzionali applicati nell’ordine elencato. Vedi anche https://cwiki.apache.org/confluence/display/solr/AnalyzersTokenizersTokenFilters#Specifying_an_Analyzer_in_the_schema
Considera questa struttura di nodi come un esempio:
-
Nome:
analyzers
-
Nome:
default
-
Nome:
charFilters
-
Tipo:
nt:unstructured
- Nome:
HTMLStrip
- Nome:
Mapping
- Nome:
-
Nome:
tokenizer
-
Nome proprietà:
name
- Tipo:
String
- Valore:
Standard
- Tipo:
-
-
Nome:
filters
-
Tipo:
nt:unstructured
-
Nome:
LowerCase
-
Nome:
Stop
-
Nome proprietà:
words
- Tipo:
String
- Valore:
stop1.txt, stop2.txt
- Tipo:
-
Nome:
stop1.txt
- Tipo:
nt:file
- Tipo:
-
Nome:
stop2.txt
- Tipo:
nt:file
- Tipo:
-
-
-
-
Il nome dei filtri, charFilters e dei token viene formato rimuovendo i suffissi di fabbrica. Pertanto:
-
org.apache.lucene.analysis.standard.StandardTokenizerFactory
diventastandard
-
org.apache.lucene.analysis.charfilter.MappingCharFilterFactory
diventaMapping
-
org.apache.lucene.analysis.core.StopFilterFactory
diventaStop
Qualsiasi parametro di configurazione richiesto per la factory viene specificato come proprietà del nodo in questione.
In casi quali il caricamento di parole non significative in cui è necessario caricare contenuto da file esterni, il contenuto può essere fornito creando un nodo figlio di tipo nt:file
per il file in questione.
Indice Solr the-solr-index
L'indice Solr è una ricerca full-text, ma può anche essere utilizzato per indicizzare la ricerca in base al percorso, alle restrizioni di proprietà e alle restrizioni di tipo primario. Ciò significa che l’indice Solr in Oak può essere utilizzato per qualsiasi tipo di query JCR.
L’integrazione nell’AEM avviene a livello di archivio, in modo che Solr sia uno dei possibili indici utilizzabili in Oak, la nuova implementazione dell’archivio fornita con AEM.
Può essere configurato per funzionare come server remoto con l’istanza AEM.
Configurazione di AEM con un unico server Solr remoto configuring-aem-with-a-single-remote-solr-server
L'AEM può anche essere configurato per funzionare con un'istanza remota del server Solr:
-
Scarica ed estrai l’ultima versione di Solr. Per ulteriori informazioni su come eseguire questa operazione, consulta la documentazione sull'installazione di Apache Solr.
-
Ora, crea due frammenti Solr. A tale scopo, creare cartelle per ogni frammento della cartella in cui è stato decompresso Solr:
- Per la prima partizione, crea la cartella:
<solrunpackdirectory>\aemsolr1\node1
- Per la seconda partizione, crea la cartella:
<solrunpackdirectory>\aemsolr2\node2
-
Individuare l'istanza di esempio nel pacchetto Solr. Si trova in una cartella denominata "
example
" nella radice del pacchetto. -
Copiare le cartelle seguenti dall'istanza di esempio nelle due cartelle condivise (
aemsolr1\node1
eaemsolr2\node2
):contexts
etc
lib
resources
scripts
solr-webapp
webapps
start.jar
-
Creare una cartella denominata
cfg
in ognuna delle due cartelle condivise. -
Posiziona i file di configurazione Solr e Zookeeper nelle cartelle
cfg
appena create.note note NOTE Per ulteriori informazioni sulla configurazione di Solr e ZooKeeper, consultare la documentazione sulla configurazione di Solr e la Guida introduttiva di ZooKeeper. -
Avviare la prima partizione con il supporto ZooKeeper passando a
aemsolr1\node1
ed eseguendo il comando seguente:code language-xml java -Xmx2g -Dbootstrap_confdir=./cfg/oak/conf -Dcollection.configName=myconf -DzkRun -DnumShards=2 -jar start.jar
-
Avviare la seconda partizione scegliendo
aemsolr2\node2
ed eseguendo il comando seguente:code language-xml java -Xmx2g -Djetty.port=7574 -DzkHost=localhost:9983 -jar start.jar
-
Dopo l'avvio di entrambe le partizioni, verificare che tutto sia pronto e funzionante connettendosi all'interfaccia Solr all'indirizzo
http://localhost:8983/solr/#/
-
Avvia AEM e passa alla console Web all'indirizzo
http://localhost:4502/system/console/configMgr
-
Imposta la seguente configurazione in Configurazione server remoto Oak Solr:
- URL HTTP Solr:
http://localhost:8983/solr/
- URL HTTP Solr:
-
Scegliere Solr remoto nell'elenco a discesa del provider di server Oak Solr.
-
Vai a CRXDE e accedi come Amministratore.
-
Crea un nodo denominato solrIndex in oak:index e imposta le seguenti proprietà:
- tipo: solr (di tipo String)
- asincrono: asincrono (di tipo String)
- reindicizza: true (di tipo booleano)
-
Salva le modifiche.
Configurazione consigliata per Solr recommended-configuration-for-solr
Di seguito è riportato un esempio di configurazione di base che può essere utilizzata con tutte e tre le implementazioni Solr descritte in questo articolo. Consente di gestire gli indici di proprietà dedicati già presenti nell’AEM; non utilizzarli con altre applicazioni.
Per utilizzarlo correttamente, è necessario inserire il contenuto dell'archivio direttamente nella home directory Solr. In caso di distribuzioni con più nodi, questa deve trovarsi direttamente nella cartella principale di ciascun nodo.
File di configurazione Solr consigliati
Strumenti di indicizzazione AEM aem-indexing-tools
AEM 6.1 integra anche due strumenti di indicizzazione presenti in AEM 6.0 come parte degli strumenti Adobe Consulting Services Commons:
- Spiega query, uno strumento progettato per aiutare gli amministratori a comprendere il modo in cui vengono eseguite le query;
- Oak Index Manager, interfaccia utente Web per la gestione degli indici esistenti.
Ora puoi raggiungerli da Strumenti - Operazioni - Dashboard - Diagnosi dalla schermata di benvenuto dell'AEM.
Per ulteriori informazioni su come utilizzarli, consulta la documentazione di Operations Dashboard.
Creazione di indici di proprietà tramite OSGi creating-property-indexes-via-osgi
Il pacchetto ACS Commons espone anche configurazioni OSGi che possono essere utilizzate per creare indici di proprietà.
Puoi accedervi dalla console Web cercando "Assicurarsi che Oak Property Index".
Risoluzione dei problemi di indicizzazione troubleshooting-indexing-issues
Possono verificarsi situazioni in cui l’esecuzione delle query richiede molto tempo e il tempo di risposta generale del sistema è lento.
Questa sezione presenta una serie di raccomandazioni su ciò che deve essere fatto per rintracciare la causa di tali problemi e consigli su come risolverli.
Preparazione delle informazioni di debug per l'analisi preparing-debugging-info-for-analysis
Il modo più semplice per ottenere le informazioni richieste per la query in esecuzione è tramite lo strumento Spiega query. Questo consente di raccogliere le informazioni precise necessarie per eseguire il debug di una query lenta senza dover consultare le informazioni a livello di registro. Ciò è utile se si conosce la query di cui viene eseguito il debug.
Se questo non è possibile per qualsiasi motivo, puoi raccogliere i registri di indicizzazione in un singolo file e utilizzarli per risolvere il problema specifico.
Abilita registrazione enable-logging
Per abilitare la registrazione, devi abilitare i registri di livello DEBUG per le categorie relative alle query e all'indicizzazione di Oak. Tali categorie sono:
- org.apache.jackrabbit.oak.plugins.index
- org.apache.jackrabbit.oak.query
- com.day.cq.search
La categoria com.day.cq.search è applicabile solo se si utilizza l'utilità QueryBuilder fornita dall'AEM.
Per abilitare la registrazione, segui questa procedura:
- Puntare il browser a
https://serveraddress:port/system/console/slinglog
- Fare clic sul pulsante Aggiungi nuovo logger nella parte inferiore della console.
- Nella riga appena creata, aggiungi le categorie sopra indicate. È possibile utilizzare il segno + per aggiungere più di una categoria a un singolo logger.
- Scegliere DEBUG dall'elenco a discesa Livello di registro.
- Impostare il file di output su
logs/queryDebug.log
. In questo modo tutti gli eventi DEBUG vengono correlati in un unico file di registro. - Esegui la query o esegui il rendering della pagina che utilizza la query su cui desideri eseguire il debug.
- Dopo aver eseguito la query, torna alla console di registrazione e modifica il livello del registro appena creato in INFO.
Configurazione indice index-configuration
Il modo in cui la query viene valutata è influenzato in gran parte dalla configurazione dell’indice. È importante che la configurazione dell’indice sia analizzata o inviata al supporto. Puoi ottenere la configurazione come pacchetto di contenuti o una rappresentazione JSON.
In genere, la configurazione dell’indicizzazione viene memorizzata nel nodo /oak:index
in CRXDE. Puoi ottenere la versione JSON in:
https://serveraddress:port/oak:index.tidy.-1.json
Se l’indice è configurato in una posizione diversa, modifica di conseguenza il percorso.
Uscita MBean mbean-output
A volte è utile fornire l’output di MBean correlati all’indice per il debug. Per farlo, segui questi passaggi:
-
Vai alla console JMX all’indirizzo:
https://serveraddress:port/system/console/jmx
-
Cerca i seguenti MBean:
- Statistiche indice Lucene
- Statistiche di supporto CopyOnRead
- Statistiche query Oak
- IndexStats
-
Fare clic su ogni MBean per ottenere statistiche sulle prestazioni. Crea uno screenshot o annotali nel caso sia necessario un invio di supporto.
Puoi ottenere la variante JSON di queste statistiche anche dai seguenti URL:
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
È inoltre possibile fornire output JMX consolidato tramite https://serveraddress:port/system/sling/monitoring/mbeans/org/apache/jackrabbit/oak.tidy.3.json
. Questo includerebbe tutti i dettagli MBean relativi ad Oak in formato JSON.
Altri dettagli other-details
Puoi raccogliere ulteriori dettagli per risolvere il problema, ad esempio:
- La versione di Oak su cui è in esecuzione l’istanza. Per visualizzarlo, apri CRXDE e osserva la versione nell'angolo inferiore destro della pagina di benvenuto oppure controlla la versione del bundle
org.apache.jackrabbit.oak-core
. - L’output di QueryBuilder Debugger della query problematica. È possibile accedere al debugger in:
https://serveraddress:port/libs/cq/search/content/querydebug.html